Skip to main content

​
Gateway 문제 해결

이 문서는 심층 런북입니다. 먼저 빠른 triage 흐름이 필요하다면 /help/troubleshooting부터 시작하세요.

​
명령 사다리

다음 명령을 이 순서대로 먼저 실행하세요.
정상 신호:
  • openclaw gateway status에 Runtime: running, RPC probe: ok가 표시됨
  • openclaw doctor가 blocking config/service issue가 없다고 보고함
  • openclaw channels status --probe가 채널을 connected/ready로 표시함

​
Anthropic 429: 긴 컨텍스트에 추가 사용량 필요

로그나 오류에 다음이 포함될 때 사용합니다. HTTP 429: rate_limit_error: Extra usage is required for long context requests.
확인할 것:
  • 선택된 Anthropic Opus/Sonnet 모델에 params.context1m: true가 설정되어 있는지
  • 현재 Anthropic credential이 long-context 사용 대상인지
  • 1M beta path가 필요한 긴 세션/모델 실행에서만 실패하는지
해결 방법:
  1. 해당 모델의 context1m을 꺼서 일반 context window로 fallback합니다.
  2. 과금 가능한 Anthropic API key를 사용하거나 subscription account에서 Anthropic Extra Usage를 활성화합니다.
  3. Anthropic long-context 요청이 거부돼도 계속 실행되도록 fallback model을 구성합니다.
관련 문서:

​
응답이 없음

채널은 올라와 있지만 답변이 없다면, 무엇이든 다시 연결하기 전에 routing과 policy부터 확인하세요.
확인할 것:
  • DM sender의 pairing이 pending인지
  • 그룹 mention gating(requireMention, mentionPatterns)이 걸려 있는지
  • 채널/그룹 allowlist가 맞는지
자주 보이는 시그니처:
  • drop guild message (mention required -> mention 전에는 그룹 메시지를 무시함
  • pairing request -> sender 승인 필요
  • blocked / allowlist -> sender/channel이 정책에 의해 필터링됨
관련 문서:

​
Dashboard / Control UI 연결 문제

dashboard 또는 Control UI가 연결되지 않으면 URL, auth mode, secure context 가정을 검증하세요.
확인할 것:
  • probe URL과 dashboard URL이 맞는지
  • client와 gateway의 auth mode/token이 일치하는지
  • device identity가 필요한데 HTTP를 쓰고 있지는 않은지
자주 보이는 시그니처:
  • device identity required -> secure context가 아니거나 device auth가 없음
  • device nonce required / device nonce mismatch -> client가 challenge 기반 device auth flow(connect.challenge + device.nonce)를 완료하지 못함
  • device signature invalid / device signature expired -> 현재 handshake에 대해 잘못된 payload를 서명했거나 timestamp가 오래됨
  • AUTH_TOKEN_MISMATCH와 canRetryWithDeviceToken=true -> cached device token으로 신뢰된 재시도 1회를 할 수 있음
  • 그 재시도 뒤에도 unauthorized가 반복됨 -> shared token/device token drift 가능성. token config를 새로 맞추고 device token을 재승인/rotate해야 할 수 있음
  • gateway connect failed: -> host/port/url 대상이 틀림

​
Auth detail code 빠른 매핑

실패한 connect 응답의 error.details.code를 보고 다음 조치를 고르세요. Device auth v2 migration 확인:
로그에 nonce/signature 오류가 보이면, 연결 client를 업데이트하고 다음을 확인하세요.
  1. connect.challenge를 기다리는지
  2. challenge에 바인딩된 payload에 서명하는지
  3. 같은 challenge nonce를 connect.params.device.nonce로 보내는지
관련 문서:

​
Gateway 서비스가 실행되지 않음

서비스는 설치됐지만 프로세스가 유지되지 않을 때 사용합니다.
확인할 것:
  • Runtime: stopped와 함께 exit hint가 나오는지
  • service config mismatch가 있는지 (Config (cli) vs Config (service))
  • port/listener 충돌이 있는지
자주 보이는 시그니처:
  • Gateway start blocked: set gateway.mode=local -> local gateway mode가 활성화되지 않음. config에서 gateway.mode="local"로 바꾸거나 openclaw configure를 실행하세요. Podman의 전용 openclaw 사용자로 실행 중이면 config는 ~openclaw/.openclaw/openclaw.json에 있습니다.
  • refusing to bind gateway ... without auth -> non-loopback bind인데 token/password가 없음
  • another gateway instance is already listening / EADDRINUSE -> port 충돌
관련 문서:

​
채널은 연결됐지만 메시지가 흐르지 않음

채널 상태는 connected인데 메시지 흐름이 멈췄다면, policy와 permission, 채널별 delivery rule에 집중하세요.
확인할 것:
  • DM policy(pairing, allowlist, open, disabled)
  • 그룹 allowlist와 mention requirement
  • 채널 API permission/scope 누락
자주 보이는 시그니처:
  • mention required -> 그룹 mention policy 때문에 무시됨
  • pairing / pending approval trace -> sender가 아직 승인되지 않음
  • missing_scope, not_in_channel, Forbidden, 401/403 -> channel auth/permission 이슈
관련 문서:

​
Cron / heartbeat 전달 문제

cron이나 heartbeat가 실행되지 않았거나 전달되지 않았다면, 먼저 scheduler 상태를 보고 그다음 delivery target을 확인하세요.
확인할 것:
  • cron이 활성화되어 있고 next wake가 존재하는지
  • job run history 상태가 ok, skipped, error 중 무엇인지
  • heartbeat skip reason이 quiet-hours, requests-in-flight, alerts-disabled 중 어떤 것인지
자주 보이는 시그니처:
  • cron: scheduler disabled; jobs will not run automatically -> cron 비활성화
  • cron: timer tick failed -> scheduler tick 실패. 파일/로그/런타임 오류를 확인
  • heartbeat skipped와 reason=quiet-hours -> active hours 바깥
  • heartbeat: unknown accountId -> heartbeat delivery target의 account id가 잘못됨
  • heartbeat skipped와 reason=dm-blocked -> heartbeat 대상이 DM 스타일 목적지로 해석됐지만 agents.defaults.heartbeat.directPolicy 또는 agent override가 block
관련 문서:

​
페어링된 node에서 도구가 실패함

node는 paired 상태인데 도구가 실패한다면 foreground, permission, approval 상태를 분리해서 보세요.
확인할 것:
  • node가 online이며 기대한 capability를 갖고 있는지
  • camera/mic/location/screen에 대한 OS permission이 부여됐는지
  • exec approval과 allowlist 상태
자주 보이는 시그니처:
  • NODE_BACKGROUND_UNAVAILABLE -> node app이 foreground에 있어야 함
  • *_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED -> OS permission 부족
  • SYSTEM_RUN_DENIED: approval required -> exec approval 대기 중
  • SYSTEM_RUN_DENIED: allowlist miss -> allowlist에 없는 명령
관련 문서:

​
브라우저 도구 실패

gateway 자체는 정상이지만 browser tool action만 실패할 때 사용합니다.
확인할 것:
  • 유효한 browser executable path
  • CDP profile reachability
  • profile="chrome"일 때 extension relay tab attachment
자주 보이는 시그니처:
  • Failed to start Chrome CDP on port -> browser process가 시작하지 못함
  • browser.executablePath not found -> 설정된 경로가 잘못됨
  • Chrome extension relay is running, but no tab is connected -> extension relay가 탭에 붙지 못함
  • Browser attachOnly is enabled ... not reachable -> attach-only profile에 연결 가능한 target이 없음
관련 문서:

​
업그레이드 후 갑자기 문제가 생겼을 때

업그레이드 직후 깨지는 문제는 대부분 config drift이거나, 이전에는 느슨했던 기본값이 이제 엄격하게 강제되는 경우입니다.

​
1) Auth와 URL override 동작이 바뀜

확인할 것:
  • gateway.mode=remote라면 CLI call이 local 서비스가 아니라 remote를 보고 있을 수 있음
  • 명시적인 --url 호출은 저장된 credential로 fallback하지 않음
자주 보이는 시그니처:
  • gateway connect failed: -> URL 대상이 틀림
  • unauthorized -> endpoint에는 닿았지만 auth가 틀림

​
2) Bind와 auth 가드레일이 더 엄격해짐

확인할 것:
  • non-loopback bind(lan, tailnet, custom)에는 auth가 필요함
  • 예전 키인 gateway.token은 gateway.auth.token을 대체하지 않음
자주 보이는 시그니처:
  • refusing to bind gateway ... without auth -> bind와 auth 조합이 맞지 않음
  • RPC probe: failed인데 runtime은 running -> gateway는 살아 있지만 현재 auth/url로는 접근 불가

​
3) Pairing과 device identity 상태가 바뀜

확인할 것:
  • dashboard/node에 대해 pending device approval이 있는지
  • policy나 identity 변경 뒤 DM pairing approval이 다시 필요한지
자주 보이는 시그니처:
  • device identity required -> device auth가 충족되지 않음
  • pairing required -> sender/device 승인이 필요함
서비스 config와 runtime이 여전히 어긋나 있으면, 같은 profile/state directory를 기준으로 service metadata를 다시 설치하세요.
관련 문서: