게이트웨이 문제 해결

이 페이지는 심층 문제 해결 가이드입니다. 빠른 분류 흐름이 필요하면 먼저 /help/troubleshooting을 참고하세요.

명령 순서

다음 명령을 순서대로 먼저 실행하세요:

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

정상 상태 신호:

• openclaw gateway status에서 Runtime: running 및 RPC probe: ok 표시.
• openclaw doctor에서 차단 설정/서비스 문제 없음 보고.
• openclaw channels status --probe에서 연결됨/준비됨 채널 표시.

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

로그/오류에 다음이 포함될 때 사용하세요: HTTP 429: rate_limit_error: Extra usage is required for long context requests.

openclaw logs --follow
openclaw models status
openclaw config get agents.defaults.models

확인 사항:

• 선택된 Anthropic Opus/Sonnet 모델에 params.context1m: true가 있음.
• 현재 Anthropic 인증 정보가 긴 컨텍스트 사용에 적합하지 않음.
• 1M 베타 경로가 필요한 긴 세션/모델 실행에서만 요청 실패.

해결 방법:

1. 해당 모델의 context1m을 비활성화하여 일반 컨텍스트 윈도우로 대체.
2. 결제가 가능한 Anthropic API 키를 사용하거나, 구독 계정에서 Anthropic Extra Usage를 활성화.
3. Anthropic 긴 컨텍스트 요청이 거부될 때 실행이 계속되도록 대체 모델 설정.

관련:

• /providers/anthropic
• /reference/token-use
• /help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic

응답 없음

채널은 연결되었지만 아무 응답이 없으면, 재연결하기 전에 라우팅과 정책을 먼저 확인하세요.

openclaw status
openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw config get channels
openclaw logs --follow

확인 사항:

• DM 발신자에 대한 페어링 대기 중.
• 그룹 멘션 게이팅 (requireMention, mentionPatterns).
• 채널/그룹 허용 목록 불일치.

일반적인 시그니처:

• drop guild message (mention required → 멘션할 때까지 그룹 메시지 무시됨.
• pairing request → 발신자에 승인 필요.
• blocked / allowlist → 발신자/채널이 정책에 의해 필터링됨.

관련:

• /channels/troubleshooting
• /channels/pairing
• /channels/groups

대시보드 Control UI 연결

대시보드/Control UI가 연결되지 않으면, URL, 인증 모드, 보안 컨텍스트 가정을 확인하세요.

openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --json

확인 사항:

• 올바른 프로브 URL과 대시보드 URL.
• 클라이언트와 게이트웨이 간 인증 모드/토큰 불일치.
• 디바이스 ID가 필요한 곳에서 HTTP 사용.

일반적인 시그니처:

• device identity required → 비보안 컨텍스트 또는 디바이스 인증 누락.
• device nonce required / device nonce mismatch → 클라이언트가 챌린지 기반 디바이스 인증 흐름(connect.challenge + device.nonce)을 완료하지 않음.
• device signature invalid / device signature expired → 클라이언트가 현재 핸드셰이크에 대해 잘못된 페이로드(또는 만료된 타임스탬프)에 서명.
• AUTH_TOKEN_MISMATCH + canRetryWithDeviceToken=true → 클라이언트가 캐시된 디바이스 토큰으로 한 번 재시도 가능.
• 재시도 후 반복되는 unauthorized → 공유 토큰/디바이스 토큰 불일치. 토큰 설정을 갱신하고 필요시 디바이스 토큰을 재승인/갱신.
• gateway connect failed: → 잘못된 호스트/포트/URL 대상.

인증 상세 코드 빠른 참조

실패한 connect 응답의 error.details.code를 사용하여 다음 조치를 선택하세요:

디바이스 인증 v2 마이그레이션 확인:

openclaw --version
openclaw doctor
openclaw gateway status

로그에 nonce/서명 오류가 표시되면, 연결 클라이언트를 업데이트하고 다음을 확인하세요:

1. connect.challenge를 기다림
2. 챌린지 바인딩된 페이로드에 서명
3. 동일한 챌린지 nonce로 connect.params.device.nonce를 전송

관련:

• /web/control-ui
• /gateway/authentication
• /gateway/remote
• /cli/devices

게이트웨이 서비스가 실행되지 않음

서비스는 설치되었지만 프로세스가 유지되지 않을 때 사용하세요.

openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --deep

확인 사항:

• 종료 힌트와 함께 Runtime: stopped.
• 서비스 설정 불일치 (Config (cli) vs Config (service)).
• 포트/리스너 충돌.

일반적인 시그니처:

• Gateway start blocked: set gateway.mode=local → 로컬 게이트웨이 모드가 활성화되지 않음. 해결: 설정에서 gateway.mode="local"을 설정 (또는 openclaw configure 실행). 전용 openclaw 사용자를 통해 Podman으로 OpenClaw를 실행하는 경우, 설정은 ~openclaw/.openclaw/openclaw.json에 있습니다.
• refusing to bind gateway ... without auth → 토큰/비밀번호 없이 비루프백 바인딩.
• another gateway instance is already listening / EADDRINUSE → 포트 충돌.

관련:

• /gateway/background-process
• /gateway/configuration
• /gateway/doctor

채널 연결됨, 메시지 미전달

채널 상태는 연결됨이지만 메시지 흐름이 멈춘 경우, 정책, 권한, 채널별 전달 규칙에 집중하세요.

openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw status --deep
openclaw logs --follow
openclaw config get channels

확인 사항:

• DM 정책 (pairing, allowlist, open, disabled).
• 그룹 허용 목록과 멘션 요구사항.
• 누락된 채널 API 권한/범위.

일반적인 시그니처:

• mention required → 그룹 멘션 정책에 의해 메시지 무시됨.
• pairing / 대기 승인 추적 → 발신자가 승인되지 않음.
• missing_scope, not_in_channel, Forbidden, 401/403 → 채널 인증/권한 문제.

관련:

• /channels/troubleshooting
• /channels/whatsapp
• /channels/telegram
• /channels/discord

크론 및 하트비트 전달

크론이나 하트비트가 실행되지 않거나 전달되지 않으면, 먼저 스케줄러 상태를 확인한 후 전달 대상을 확인하세요.

openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow

확인 사항:

• 크론 활성화 및 다음 wake 존재 여부.
• 작업 실행 기록 상태 (ok, skipped, error).
• 하트비트 건너뛰기 이유 (quiet-hours, requests-in-flight, alerts-disabled).

일반적인 시그니처:

• cron: scheduler disabled; jobs will not run automatically → 크론 비활성화됨.
• cron: timer tick failed → 스케줄러 tick 실패. 파일/로그/런타임 오류 확인.
• heartbeat skipped + reason=quiet-hours → 활성 시간 윈도우 밖.
• heartbeat: unknown accountId → 하트비트 전달 대상의 잘못된 계정 ID.
• heartbeat skipped + reason=dm-blocked → 하트비트 대상이 DM 스타일 목적지로 확인되었으나 agents.defaults.heartbeat.directPolicy (또는 에이전트별 재정의)가 block으로 설정됨.

관련:

• /automation/troubleshooting
• /automation/cron-jobs
• /gateway/heartbeat

노드 페어링 후 도구 실패

노드가 페어링되었지만 도구가 실패하면, 포그라운드, 권한, 승인 상태를 분리하세요.

openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
openclaw logs --follow
openclaw status

확인 사항:

• 예상 기능을 갖춘 노드 온라인 상태.
• 카메라/마이크/위치/화면에 대한 OS 권한 부여.
• 실행 승인 및 허용 목록 상태.

일반적인 시그니처:

• NODE_BACKGROUND_UNAVAILABLE → 노드 앱이 포그라운드에 있어야 함.
• *_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → OS 권한 누락.
• SYSTEM_RUN_DENIED: approval required → 실행 승인 대기 중.
• SYSTEM_RUN_DENIED: allowlist miss → 허용 목록에 의해 명령 차단됨.

관련:

• /nodes/troubleshooting
• /nodes/index
• /tools/exec-approvals

브라우저 도구 실패

게이트웨이 자체는 정상이지만 브라우저 도구 작업이 실패할 때 사용하세요.

openclaw browser status
openclaw browser start --browser-profile openclaw
openclaw browser profiles
openclaw logs --follow
openclaw doctor

확인 사항:

• 유효한 브라우저 실행 파일 경로.
• CDP 프로필 도달 가능성.
• profile="chrome"에 대한 확장 릴레이 탭 연결.

일반적인 시그니처:

• Failed to start Chrome CDP on port → 브라우저 프로세스 실행 실패.
• browser.executablePath not found → 설정된 경로가 잘못됨.
• Chrome extension relay is running, but no tab is connected → 확장 릴레이가 연결되지 않음.
• Browser attachOnly is enabled ... not reachable → attach-only 프로필에 도달 가능한 대상이 없음.

관련:

• /tools/browser-linux-troubleshooting
• /tools/chrome-extension
• /tools/browser

업그레이드 후 갑자기 문제가 발생한 경우

대부분의 업그레이드 후 문제는 설정 드리프트이거나 이전보다 엄격해진 기본값 적용 때문입니다.

1) 인증 및 URL 재정의 동작 변경

openclaw gateway status
openclaw config get gateway.mode
openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode

확인 사항:

• gateway.mode=remote이면, CLI 호출이 로컬 서비스가 정상인데도 원격을 대상으로 할 수 있습니다.
• 명시적 --url 호출은 저장된 인증 정보로 대체하지 않습니다.

일반적인 시그니처:

• gateway connect failed: → 잘못된 URL 대상.
• unauthorized → 엔드포인트에 도달했지만 인증이 잘못됨.

2) 바인딩 및 인증 가드레일 강화

openclaw config get gateway.bind
openclaw config get gateway.auth.token
openclaw gateway status
openclaw logs --follow

확인 사항:

• 비루프백 바인딩 (lan, tailnet, custom)에 인증 설정 필요.
• gateway.token과 같은 이전 키는 gateway.auth.token을 대체하지 않음.

일반적인 시그니처:

• refusing to bind gateway ... without auth → 바인딩+인증 불일치.
• RPC probe: failed + 런타임 실행 중 → 게이트웨이는 살아 있지만 현재 인증/URL로 접근 불가.

3) 페어링 및 디바이스 ID 상태 변경

openclaw devices list
openclaw pairing list --channel <channel> [--account <id>]
openclaw logs --follow
openclaw doctor

확인 사항:

• 대시보드/노드에 대한 대기 디바이스 승인.
• 정책 또는 ID 변경 후 대기 DM 페어링 승인.

일반적인 시그니처:

• device identity required → 디바이스 인증 미충족.
• pairing required → 발신자/디바이스 승인 필요.

확인 후에도 서비스 설정과 런타임이 일치하지 않으면, 동일한 프로필/상태 디렉터리에서 서비스 메타데이터를 재설치하세요:

openclaw gateway install --force
openclaw gateway restart

관련:

• /gateway/pairing
• /gateway/authentication
• /gateway/background-process