디버깅
기준일: 2026-07-13 난이도: 고급 공식 기준: Doctor, Status, Logs, Channels
OpenClaw 문제는 설정 오류, Gateway lifecycle, channel transport, provider auth, Skill dependency를 분리해야 빠르게 찾을 수 있습니다. 첫 단계에서는 상태를 바꾸지 않는 명령만 실행하고, repair는 증거와 backup이 준비된 뒤 수행합니다.
핵심 개념
| 질문 | 읽기 전용 진단 |
|---|---|
| 설정이 schema에 맞는가 | openclaw config validate --json |
| 설치 전반에 알려진 문제가 있는가 | openclaw doctor --lint --json |
| Gateway target과 service가 정상인가 | openclaw gateway status, gateway probe |
| 채널이 실제 연결되는가 | openclaw channels status --probe |
| provider 인증과 기본 모델이 맞는가 | openclaw models status |
| Skill dependency가 준비됐는가 | openclaw skills check |
선택 기준
- CI와 자동 점검에는 절대 수정하지 않는
doctor --lint를 사용합니다. - 사람이 대화형으로 원인을 찾을 때는
doctor를 사용합니다. doctor --fix는 설정과 state를 바꿀 수 있으므로 진단 명령이 아닙니다.- 채널 연결 상태는 sessions 목록이 아니라 channel probe로 판단합니다.
- 민감한 config나 log 원문 전체를 이슈에 붙이지 않습니다.
실습
1. 설정과 install health
openclaw config validate --json
openclaw doctor --lint --json
doctor --lint의 exit code는 선택한 severity threshold에 해당하는 finding 존재 여부를 나타냅니다. 더 좁은 CI gate가 필요하면 공식 --severity-min, --only, --skip 옵션을 검토합니다.
2. Gateway와 전체 상태
openclaw gateway status
openclaw gateway probe --json
openclaw status --all
status --all은 security audit, plugin compatibility, memory probe를 포함한 읽기 전용 진단입니다. 실제 채널 live probe까지 필요하면 status --deep을 사용합니다.
3. 로그 확인
openclaw logs --limit 500 --plain
openclaw logs --follow
현재 공식 Logs CLI는 --limit, --max-bytes, --follow, --json, --plain, --utc 등을 제공합니다. 문서에 없는 --level, --path 옵션이나 임의 출력 예시를 전제로 진단하지 않습니다.
4. 채널 분리 진단
openclaw channels list --all
openclaw channels status --probe
openclaw channels logs --channel all --lines 200
Discord처럼 target 권한이 중요한 채널은 capability probe를 추가합니다.
openclaw channels capabilities --channel discord --target channel:123
5. 모델과 Skills
openclaw models status
openclaw models auth list
openclaw skills list --eligible
openclaw skills check
모델 문제를 해결할 때 auth profile 추가와 기본 모델 변경을 섞지 않습니다. Skills는 존재 여부뿐 아니라 eligible 상태와 dependency check를 함께 봅니다.
6. 복구가 필요한 경우
읽기 전용 진단으로 원인이 확인된 뒤에만 repair를 실행합니다.
openclaw backup create --verify
openclaw doctor --fix
openclaw config validate
openclaw status --all
Gateway service 정의가 문제라면 doctor --fix가 항상 service를 재설치한다고 가정하지 말고 Gateway CLI의 install/start/restart 동작을 확인합니다.
도구에 입력할 프롬프트
OpenClaw 문제를 읽기 전용으로 진단해줘.
config validate --json, doctor --lint --json, gateway probe --json,
status --all, channels status --probe, models status 결과를
설정/Gateway/채널/모델/Skill로 분류해줘.
증거가 없는 원인은 추측하지 말고 추가 확인 명령으로 남겨줘.
repair 명령은 backup 절차와 함께 별도 섹션에만 제시해줘.
체크리스트
- 읽기 전용 명령으로 재현 범위를 좁혔다.
- schema 오류와 runtime 오류를 분리했다.
- Gateway target과 channel transport를 따로 확인했다.
- logs에서 token, config, 사용자 메시지를 가렸다.
- 공식 CLI에 존재하지 않는 옵션을 사용하지 않았다.
- repair 전에 검증된 backup을 만들었다.
다음 단계
- 일반적인 오류에서 증상별 복구 흐름을 확인합니다.
- Gateway 운영에서 service lifecycle을 봅니다.
- 보안에서 audit 결과와 Gateway 노출을 점검합니다.