2026-07-13 기준 · OpenClaw 2026.7.1 안정 버전 기준 · 시리즈 1/3
결론부터: 이 에러는 고장이 아니라 설정 누락입니다. 터미널에서 openclaw config set gateway.mode "local" 한 줄 실행 후 게이트웨이를 재시작하면 해결됩니다. 게이트웨이(Gateway)를 내 기기에서 직접 돌리는 로컬 모드로 쓰겠다는 선언이 설정 파일에 없어서, 오픈클로가 시작 자체를 막아둔 상태입니다.
증상
게이트웨이를 시작하려고 하면 다음 메시지와 함께 실행이 거부됩니다:
Gateway start blocked: set gateway.mode=local
openclaw gateway status 를 쳐도 게이트웨이가 떠 있지 않고, 텔레그램·디스코드 등 연결해 둔 채널이 전부 응답하지 않습니다. 설치 직후 첫 실행이나, 온보딩(onboarding)을 중간에 끊었거나, 설정 파일을 손으로 편집한 뒤에 자주 나타납니다.
원인 (한 문장)
설정 파일(~/.openclaw/openclaw.json)에 게이트웨이 실행 모드가 local 로 지정되어 있지 않아, 오픈클로가 어느 모드로 떠야 할지 몰라 시작을 차단한 것입니다.
해결 단계
1) 게이트웨이 모드를 local 로 지정
openclaw config set gateway.mode "local"
설정 파일을 직접 열어 고쳐도 됩니다 (~/.openclaw/openclaw.json 의 gateway.mode 값 확인).
2) 온보딩을 아예 다시 돌리는 방법 (설치 직후라면 이쪽 권장)
openclaw onboard --mode local
온보딩 마법사가 모델 제공자·API 키 선택과 함께 게이트웨이 모드를 처음부터 잡아줍니다.
3) 게이트웨이 재시작 + 상태 확인
openclaw gateway restart
openclaw gateway status
4) 그래도 안 되면 자동 진단
openclaw doctor
openclaw doctor --fix
설정 파일 문법 오류(Invalid config)가 함께 있는 경우 openclaw config validate 로 어느 줄이 문제인지 확인할 수 있습니다.
관련 보안 주의
gateway.mode 를 만지는 김에 인증과 바인딩도 같이 확인하세요. 게이트웨이는 오픈클로의 관제탑이라, 모드만 켜고 인증 없이 외부로 노출하면 이번 에러보다 훨씬 큰 문제가 됩니다.
- 토큰 인증:
gateway.auth.mode: "token" - 바인딩:
--bind loopback(0.0.0.0 금지)
설치 전후로 지켜야 할 7가지는 오픈클로 보안 체크리스트 글에 설정 JSON 그대로 정리해 두었습니다. 게이트웨이(Gateway)·세션(Session) 같은 용어가 낯설면 AI 에이전트 단어장을 먼저 보세요.
에러를 고쳤다면, 이제 일을 시킬 차례
게이트웨이가 떴다는 건 내 컴퓨터에 24시간 AI 비서가 대기 중이라는 뜻입니다. 비개발자 기준으로 오픈클로 세팅부터 반복 업무 자동화까지 다루는 AI 에이전트 강의에서 1차시를 무료로 미리 볼 수 있습니다.
FAQ
Q. gateway.mode 를 local 말고 다른 값으로 두면 안 되나요?
A. 내 기기에서 직접 돌리는 일반적인 개인 사용이라면 local 이 맞습니다. 원격 게이트웨이에 붙는 구성은 별도 인증 설정이 전제됩니다.
Q. 명령을 실행했는데 이번엔 포트 에러(EADDRINUSE)가 나요.
A. 이미 다른 게이트웨이 프로세스가 포트를 잡고 있는 경우입니다 — 시리즈 2편(EADDRINUSE 해결법)을 보세요.
이 글은 2026-07-13 기준 OpenClaw 공식 트러블슈팅 문서(docs.openclaw.ai/gateway/troubleshooting)의 에러 문자열·해결 명령을 그대로 인용해 작성했습니다. 버전 업데이트로 명령·설정 키가 바뀔 수 있으니 공식 문서를 함께 확인하세요.