일반적인 오류 및 해결 방법

기준일: 2026-07-13 난이도: 초급 공식 기준: General troubleshooting, Install troubleshooting

오류 문구만 보고 설정 키를 추측하지 않습니다. 먼저 재현 범위를 확인하고, 공식 schema와 live status가 가리키는 계층만 수정합니다.

핵심 개념

증상	확인할 경계	공식 진단
openclaw 명령을 찾지 못함	설치와 PATH	openclaw --version, 설치 문서
설정 오류로 시작하지 못함	config schema	openclaw config validate
Gateway에 연결하지 못함	RPC target과 service	gateway probe, gateway status
채널만 응답하지 않음	channel transport·권한	channels status --probe
모델 호출만 실패함	provider auth·model id	models status
Skill 또는 plugin이 보이지 않음	eligibility·install policy	skills check, plugins doctor

선택 기준

• 진단 결과가 없으면 config를 직접 편집하지 않습니다.
• doctor --fix는 상태를 바꿀 수 있으므로 첫 명령으로 사용하지 않습니다.
• token은 CLI 인자, 로그, 이슈 본문에 노출하지 않습니다.
• channel별 복구는 해당 channel 공식 페이지의 필수 권한과 설정 경로를 다시 확인합니다.

실습

1. 명령을 찾지 못할 때

공식 설치 방법으로 설치한 뒤 새 터미널에서 확인합니다.

npm install -g openclaw@latest
openclaw --version
openclaw doctor

설치 스크립트, npm, pnpm 등 여러 방식을 겹쳐 설치했다면 PATH를 임의로 덧붙이기 전에 현재 실행 파일을 확인합니다.

command -v openclaw

2. 설정 오류

openclaw config file
openclaw config validate --json
openclaw config schema > openclaw.schema.json

schema에 없는 키는 삭제하거나 현재 공식 키로 이전합니다. Nix mode에서는 config writer가 거부되므로 Nix source를 수정해야 합니다.

3. Gateway 연결 오류

openclaw gateway probe --json
openclaw gateway status
openclaw logs --limit 500 --plain

probe가 가리키는 Gateway와 서비스가 실행하는 profile이 같은지 확인합니다. 포트를 바로 종료하기보다 --profile과 active config path를 먼저 비교합니다.

4. 채널 무응답

openclaw channels list --all
openclaw channels status --probe
openclaw channels logs --channel all --lines 200

연결 성공과 메시지 권한은 별개입니다. Discord, Slack, Telegram의 token과 권한은 각 공식 channel 문서에서 확인합니다.

5. 모델 또는 인증 오류

openclaw models status
openclaw models auth list
openclaw models list

provider 인증을 추가하는 작업과 기본 모델을 변경하는 작업을 섞지 않습니다. local OpenAI-compatible backend가 직접 호출에서는 성공하지만 agent turn에서만 실패하면 공식 troubleshooting의 compatibility 항목을 확인합니다.

6. Skills와 plugins

openclaw skills list --eligible
openclaw skills check
openclaw plugins doctor

plugin update 뒤 blocked by install policy가 보이면 security.installPolicy와 plugin의 OpenClaw 호환 버전을 함께 검토합니다. 정책을 영구적으로 우회하지 않습니다.

도구에 입력할 프롬프트

이 오류를 OpenClaw 공식 진단 순서로 분석해줘.
현재 버전, config validate, gateway probe/status, channels status --probe,
models status, skills check 결과 중 실제 증거가 있는 원인만 채택해줘.
설정 키는 live config schema에 존재할 때만 제안해줘.

체크리스트

• 현재 실행 파일과 버전을 확인했다.
• config schema validation 결과를 확보했다.
• Gateway, 채널, 모델 오류를 분리했다.
• token과 개인 메시지를 로그에서 제거했다.
• 수정 후 같은 진단 명령으로 재검증했다.

다음 단계

• 디버깅에서 진단 결과를 체계적으로 수집합니다.
• Configuration에서 live schema 기반 변경을 연습합니다.