Gateway 문제 해결 가이드

분명 어제까지는 잘 작동했는데, 갑자기 응답이 없거나 연결이 끊기면 정말 당황스럽죠. 로그를 봐도 어디부터 손을 대야 할지 막막할 때가 있습니다. 특히 설정 하나를 바꿨거나 업데이트를 한 직후라면 더 그렇고요.

이 가이드는 Gateway가 멈췄을 때 빠르게 복구할 수 있는 실질적인 해결 방법을 정리했습니다. 복잡한 분석 대신, 가장 먼저 실행해야 할 명령어부터 상황별 체크리스트까지 하나씩 살펴볼게요.

필요한 것

OpenClaw CLI 설치
실행 중인 Gateway 인스턴스
관련 채널 권한 및 설정 정보

빠른 시작

문제가 생겼을 때 가장 먼저 이 명령어들을 순서대로 실행해 보세요. 5분 안에 상태를 파악할 수 있습니다.

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에서 채널이 connected 또는 ready 상태로 나타납니다.

문제 해결

1. 채널은 연결되었는데 응답이 없는 경우

채널 상태는 정상이지만 아무런 답변이 없다면, 연결을 다시 시도하기 전에 라우팅과 정책 설정을 먼저 확인해야 합니다.

openclaw status
openclaw channels status --probe
openclaw pairing list <channel>
openclaw config get channels
openclaw logs --follow

확인 사항:

DM 발신자의 페어링이 pending 상태인지 확인하세요.
그룹 멘션 제한(requireMention, mentionPatterns)이 걸려 있는지 보세요.
채널이나 그룹의 allowlist 설정이 일치하는지 확인하세요.

주요 오류 로그:

drop guild message (mention required) : 멘션이 있을 때까지 그룹 메시지를 무시합니다.
pairing request : 발신자 승인이 필요합니다.
blocked / allowlist : 정책에 의해 발신자나 채널이 필터링되었습니다.

2. 대시보드 및 UI 연결 실패

대시보드나 제어 UI가 연결되지 않는다면 URL, 인증 모드, 보안 컨텍스트 설정을 점검하세요.

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

확인 사항:

probe URL과 대시보드 URL이 정확한지 확인하세요.
클라이언트와 Gateway 사이의 인증 모드나 토큰이 일치하는지 보세요.
장치 식별이 필요한 곳에 일반 HTTP를 사용 중인지 확인하세요.

주요 오류 로그:

device identity required : 보안 컨텍스트가 아니거나 장치 인증이 누락되었습니다.
unauthorized / 재연결 루프 : 토큰이나 비밀번호가 일치하지 않습니다.
gateway connect failed: : 호스트, 포트 또는 URL 대상이 잘못되었습니다.

3. Gateway 서비스가 실행되지 않을 때

서비스는 설치되었지만 프로세스가 유지되지 않는 경우입니다.

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

확인 사항:

Runtime: stopped 메시지와 함께 종료 힌트가 있는지 보세요.
CLI 설정과 서비스 설정이 충돌하는지 확인하세요.
포트나 리스너 충돌이 있는지 점검하세요.

주요 오류 로그:

Gateway start blocked: set gateway.mode=local : 로컬 Gateway 모드가 활성화되지 않았습니다.
refusing to bind gateway ... without auth : 루프백이 아닌 주소에 바인딩하면서 토큰/비밀번호 설정을 누락했습니다.
another gateway instance is already listening / EADDRINUSE : 포트 충돌이 발생했습니다.

4. 메시지 흐름이 끊긴 경우

채널 상태는 연결되어 있지만 메시지가 오가지 않는다면 정책과 권한을 집중적으로 보세요.

openclaw channels status --probe
openclaw pairing list <channel>
openclaw status --deep
openclaw logs --follow
openclaw config get channels

확인 사항:

DM 정책(pairing, allowlist, open, disabled)을 확인하세요.
그룹 allowlist 및 멘션 요구 사항을 보세요.
채널 API 권한이나 스코프가 누락되었는지 확인하세요.

주요 오류 로그:

mention required : 그룹 멘션 정책에 의해 메시지가 무시되었습니다.
pairing / 승인 대기 흔적 : 발신자가 승인되지 않았습니다.
missing_scope, not_in_channel, Forbidden, 401/403 : 채널 인증이나 권한 문제입니다.

5. Cron 및 Heartbeat 문제

예약된 작업이나 Heartbeat가 실행되지 않는다면 스케줄러 상태부터 확인해야 합니다.

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

확인 사항:

Cron이 활성화되어 있고 다음 실행 시간이 있는지 확인하세요.
작업 실행 이력 상태(ok, skipped, error)를 보세요.
Heartbeat 건너뜀 이유(quiet-hours 등)를 확인하세요.

주요 오류 로그:

cron: scheduler disabled : Cron이 비활성화되어 작업이 자동으로 실행되지 않습니다.
cron: timer tick failed : 스케줄러 실행 실패입니다. 파일이나 런타임 오류를 확인하세요.
heartbeat skipped (reason=quiet-hours) : 활성 시간대 외의 시간입니다.
heartbeat: unknown accountId : Heartbeat 대상 계정 ID가 유효하지 않습니다.

6. Node 및 도구 실행 실패

Node는 연결되었는데 도구가 작동하지 않는다면 권한과 승인 상태를 격리해서 확인하세요.

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

확인 사항:

Node가 온라인이며 예상된 기능을 갖추고 있는지 확인하세요.
카메라, 마이크, 위치, 화면 공유 등 OS 권한이 부여되었는지 보세요.
실행 승인 및 allowlist 상태를 확인하세요.

주요 오류 로그:

NODE_BACKGROUND_UNAVAILABLE : Node 앱이 포그라운드에 있어야 합니다.
*_PERMISSION_REQUIRED : OS 권한이 누락되었습니다.
SYSTEM_RUN_DENIED: approval required : 실행 승인이 대기 중입니다.
SYSTEM_RUN_DENIED: allowlist miss : allowlist에 의해 명령이 차단되었습니다.

7. 브라우저 도구 실패

Gateway는 정상이지만 브라우저 도구만 실패할 때 사용하세요.

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

확인 사항:

브라우저 실행 파일 경로가 유효한지 확인하세요.
CDP 프로필에 접속 가능한지 보세요.
확장 프로그램 레이어 탭이 연결되었는지 확인하세요.

주요 오류 로그:

Failed to start Chrome CDP on port : 브라우저 프로세스 실행에 실패했습니다.
browser.executablePath not found : 설정된 경로가 잘못되었습니다.
Chrome extension relay is running, but no tab is connected : 확장 프로그램 릴레이가 연결되지 않았습니다.

8. 업데이트 후 갑자기 작동하지 않을 때

대부분의 업데이트 후 문제는 설정이 틀어지거나 더 엄격해진 기본값 때문입니다.

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 호출이 로컬 서비스가 아닌 원격지를 대상으로 할 수 있습니다.

2) 바인딩 및 인증 가드레일 확인

openclaw config get gateway.bind
openclaw config get gateway.auth.token

lan, tailnet 등 루프백이 아닌 바인딩은 반드시 인증 설정이 필요합니다.
예전 키인 gateway.token은 더 이상 gateway.auth.token을 대체하지 않습니다.

3) 페어링 및 장치 식별 상태 확인

openclaw devices list
openclaw pairing list <channel>

대시보드나 Node에 대한 장치 승인이 대기 중인지 확인하세요.

모든 확인 후에도 설정과 런타임이 일치하지 않는다면 서비스를 재설치해 보세요.

openclaw gateway install --force
openclaw gateway restart

여전히 해결되지 않는 문제가 있나요? AI Setup Assistant에게 질문하고 바로 답을 찾아보세요.

다음 단계

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.