트러블슈팅 개요
기준일: 2026-07-13 난이도: 초급 공식 기준: General troubleshooting, Doctor, Logs
OpenClaw 공식 트러블슈팅 문서는 먼저 60초 진단 사다리를 실행하도록 안내합니다. 한 번에 설정을 고치기보다 어느 계층에서 실패하는지 좁히는 것이 핵심입니다.
핵심 개념
설치/설정 → Gateway → 채널 → 모델 → Skills/도구
status는 전체 상태 요약입니다.gateway probe와gateway status는 RPC 대상과 서비스 상태를 구분합니다.channels status --probe는 실제 채널 연결을 확인합니다.doctor는 알려진 설정·상태 문제를 진단합니다.logs --follow는 진단 결과와 같은 시점의 런타임 증거를 보여줍니다.
선택 기준
| 상황 | 먼저 실행할 명령 |
|---|---|
| 무엇이 문제인지 모름 | openclaw status --all |
| Gateway 연결 실패 | openclaw gateway probe |
| 백그라운드 서비스 문제 | openclaw gateway status |
| 특정 채널 무응답 | openclaw channels status --probe |
| 설정·업그레이드 후 이상 | openclaw doctor |
| 재현 순간 확인 | openclaw logs --follow |
실습
공식 진단 사다리를 순서대로 실행합니다.
openclaw status
openclaw status --all
openclaw gateway probe
openclaw gateway status
openclaw doctor
openclaw channels status --probe
openclaw logs --follow
자동화나 CI처럼 상태 변경을 피해야 할 때는 다음 읽기 전용 점검을 사용합니다.
openclaw config validate --json
openclaw doctor --lint --json
openclaw status --all
repair가 필요하다면 먼저 검증된 백업을 만듭니다.
openclaw backup create --verify
doctor --fix, config writer, Gateway 재시작은 원인이 확인된 뒤 별도 단계로 실행합니다.
도구에 입력할 프롬프트
아래 OpenClaw 진단 결과를 설치/설정, Gateway, 채널, 모델, Skills로 분류해줘.
증거가 없는 원인은 추측하지 말고 추가 확인 명령으로 남겨줘.
수정 명령은 읽기 전용 진단과 분리하고, 실행 전 backup 절차를 포함해줘.
체크리스트
- 공식 60초 진단 사다리를 순서대로 실행했다.
- Gateway RPC와 서비스 상태를 따로 확인했다.
- 채널 상태를 session 목록으로 추정하지 않았다.
- 로그에서 token과 사용자 메시지를 가렸다.
- repair 전에 검증된 backup을 만들었다.