OpenClaw 문제 해결 가이드: 멈춘 워크플로우를 다시 살리는 방법

분명 어제까지 잘 작동하던 코드가 갑자기 멈춰버리면 정말 당혹스럽죠. 로그를 봐도 어디서부터 손을 대야 할지 막막하고, 설정 하나가 꼬인 것 같은데 원인을 찾느라 소중한 시간을 허비하곤 해요.

이런 상황에서 가장 필요한 건 복잡한 설명보다 당장 실행해 볼 수 있는 명확한 진단 순서입니다. OpenClaw가 제대로 작동하지 않을 때, 단 몇 분 안에 문제를 파악하고 다시 정상 궤도로 돌려놓을 수 있는 체크리스트를 정리했습니다.

필요한 것

시작하기 전에 다음 환경이 준비되어 있는지 확인해 주세요.

• OpenClaw CLI가 설치된 터미널 환경
• 현재 실행 중인 OpenClaw Gateway 및 서비스에 대한 접근 권한

Quick Start: 1분 진단 스텝

문제가 생겼다면 고민하지 말고 아래 명령어들을 순서대로 입력해 보세요. 서비스의 현재 상태를 가장 빠르게 파악할 수 있는 방법입니다.

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

정상적인 상태라면 다음과 같은 결과가 출력됩니다.

• openclaw status: 설정된 채널들이 표시되며, 인증 에러가 없어야 합니다.
• openclaw gateway status: Runtime: running 및 RPC probe: ok 메시지가 보여야 합니다.
• openclaw doctor: 차단된 설정이나 서비스 에러가 없어야 합니다.
• openclaw channels status --probe: 채널 상태가 connected 또는 ready로 표시됩니다.

Troubleshooting: 상황별 해결 방법

어떤 부분에서 문제가 발생했나요? 아래의 주요 이슈 중에서 현재 상황에 맞는 해결책을 찾아보세요.

1. 응답이 없는 경우 (No replies)

메시지를 보냈는데 아무런 응답이 없다면 아래 명령어로 상태를 점검하세요.

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

체크포인트:

• 로그에 drop guild message (mention required)가 찍힌다면 Discord 등에서 멘션 게이트 설정에 걸린 것입니다.
• pairing request가 보인다면 발신자가 승인되지 않아 DM 페어링 승인을 기다리는 중입니다.

2. Dashboard 또는 Control UI 연결 실패

UI 화면이 뜨지 않거나 연결되지 않을 때의 조치 방법입니다.

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

체크포인트:

• openclaw gateway status 결과에 Dashboard: http://... 주소가 정확히 표시되는지 확인하세요.
• 로그에 device identity required가 있다면 비보안 환경(HTTP)이라 장치 인증을 완료할 수 없는 상태입니다.

3. Gateway 시작 및 서비스 실행 오류

Gateway가 실행되지 않거나 서비스가 로드되었음에도 작동하지 않는 경우입니다.

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

체크포인트:

• EADDRINUSE 에러가 보인다면 이미 다른 Gateway 인스턴스가 해당 포트를 사용 중인 것입니다.
• refusing to bind gateway ... without auth 로그는 토큰이나 비밀번호 없이 외부 접속을 시도할 때 발생합니다.

4. Cron 작업 또는 Heartbeat 미작동

예약된 작업이 실행되지 않거나 Heartbeat가 전달되지 않을 때 확인하세요.

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

체크포인트:

• cron: scheduler disabled 메시지가 있다면 Cron 설정 자체가 비활성화된 상태입니다.
• heartbeat skipped와 reason=quiet-hours가 보인다면 설정된 활동 시간 이외의 시간대라 건너뛴 것입니다.

5. Node 도구 및 Browser 실행 실패

Node가 페어링되었는데 도구가 실패하거나, Browser 제어가 안 되는 경우입니다.

# Node 점검
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>

# Browser 점검
openclaw browser status
openclaw doctor

체크포인트:

• SYSTEM_RUN_DENIED: approval required는 실행 승인이 대기 중임을 의미합니다.
• Browser의 경우 Failed to start Chrome CDP on port 로그가 보인다면 로컬 브라우저 실행 환경을 확인해야 합니다.

문제가 여전히 해결되지 않나요? AI Setup Assistant에게 질문하고 실시간으로 도움을 받아보세요.

다음 단계

• Gateway 상세 문제 해결 가이드
• 채널 설정 및 페어링 안내
• 자동화 작업 문제 해결
• Node 및 도구 트러블슈팅