OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Start here

일반 문제 해결

트리아지 시작점입니다. 2분 안에 진단한 다음 심층 페이지로 이동하세요.

첫 60초

다음 단계를 순서대로 실행하세요.

bash
openclaw statusopenclaw status --allopenclaw gateway probeopenclaw gateway statusopenclaw doctoropenclaw channels status --probeopenclaw logs --follow

정상 출력은 각각 다음과 같습니다.

  • openclaw status에 구성된 채널이 표시되고 인증 오류가 없습니다.
  • openclaw status --all이 공유 가능한 전체 보고서를 생성합니다.
  • openclaw gateway probe에 Reachable: yes가 표시됩니다. Capability: ...는 프로브로 확인된 인증 수준입니다. Read probe: limited - missing scope: operator.read는 연결 실패가 아니라 진단 기능 저하를 의미합니다.
  • openclaw gateway status에 Runtime: running, Connectivity probe: ok, 합당한 Capability: ...가 표시됩니다. 읽기 범위 RPC 증명도 요구하려면 --require-rpc를 추가하세요.
  • openclaw doctor가 차단을 유발하는 구성/서비스 오류를 보고하지 않습니다.
  • Gateway에 연결할 수 있으면 openclaw channels status --probe가 계정별 실시간 전송 상태 (works / audit ok)를 반환하고, 연결할 수 없으면 구성 전용 요약으로 대체됩니다.
  • openclaw logs --follow에 지속적인 활동이 표시되고 반복되는 치명적 오류가 없습니다.

어시스턴트의 기능이 제한적이거나 도구가 누락된 경우

실제로 적용되는 도구 프로필을 확인하세요.

bash
openclaw statusopenclaw status --allopenclaw doctor

일반적인 원인은 다음과 같습니다.

  • tools.profile: "minimal"은 session_status만 허용합니다.
  • tools.profile: "messaging"은 채팅 전용 에이전트를 위한 제한적인 프로필입니다.
  • tools.profile: "coding"은 새 로컬 구성의 기본값입니다(저장소, 파일, 셸 및 런타임 작업).
  • tools.profile: "full"은 프로필 제한을 제거합니다. 신뢰할 수 있고 운영자가 제어하는 에이전트에만 사용하세요.
  • 에이전트별 agents.list[].tools 재정의는 특정 에이전트 하나에 대해 루트 프로필을 축소하거나 확장합니다.

프로필을 변경하고 Gateway를 다시 시작하거나 다시 로드한 다음 openclaw status --all로 다시 확인하세요. 전체 프로필/그룹 표: 도구 프로필.

Anthropic 긴 컨텍스트 429

HTTP 429: rate_limit_error: Extra usage is required for long context requests → Anthropic 429: 긴 컨텍스트에 추가 사용량 필요.

로컬 OpenAI 호환 백엔드는 직접 호출하면 작동하지만 OpenClaw에서는 실패하는 경우

로컬/자체 호스팅 /v1 백엔드는 직접 /v1/chat/completions 프로브에 응답하지만 openclaw infer model run 또는 일반 에이전트 턴에서 실패합니다.

  1. 문자열이 필요한 messages[].content를 오류에서 언급하면 models.providers.<provider>.models[].compat.requiresStringContent: true로 설정하세요.
  2. 여전히 OpenClaw 에이전트 턴에서만 실패하면 models.providers.<provider>.models[].compat.supportsTools: false로 설정하고 다시 시도하세요.
  3. 소규모 직접 호출은 작동하지만 더 큰 OpenClaw 프롬프트가 백엔드를 중단시키면 OpenClaw 버그가 아니라 업스트림 모델/서버의 제한입니다. 로컬 OpenAI 호환 백엔드는 직접 프로브를 통과하지만 에이전트 실행은 실패함에서 계속 확인하세요.

openclaw 확장이 없어 Plugin 설치가 실패하는 경우

package.json missing openclaw.extensions는 Plugin 패키지가 OpenClaw에서 더 이상 허용하지 않는 형식을 사용한다는 의미입니다.

Plugin 패키지에서 다음과 같이 수정하세요.

  1. 빌드된 런타임 파일(일반적으로 ./dist/index.js)을 가리키는 openclaw.extensions를 package.json에 추가합니다.
  2. 다시 게시한 다음 openclaw plugins install <package>를 다시 실행합니다.
json
{  "name": "@openclaw/my-plugin",  "version": "1.2.3",  "openclaw": {    "extensions": ["./dist/index.js"]  }}

참고: Plugin 아키텍처

설치 정책이 Plugin 설치 또는 업데이트를 차단하는 경우

업데이트는 완료되지만 Plugin이 오래된 상태이거나 비활성화되거나 blocked by install policy, install policy failed closed, 또는 Disabled "<plugin>" after plugin update failure가 표시되면 security.installPolicy를 확인하세요.

설치 정책은 Plugin 설치 및 업데이트 시 실행됩니다. @openclaw/* Plugin 버전은 일반적으로 OpenClaw 릴리스와 함께 변경되므로 OpenClaw 업데이트 후 동기화 중에 그에 맞는 Plugin 업데이트가 필요할 수 있습니다.

일치하는 업그레이드 규칙도 관리하지 않는다면 다음 정책 형식을 피하세요.

  • OpenClaw 소유 Plugin을 정확히 하나의 이전 버전으로 고정하는 방식(예: @openclaw/*@2026.5.3만 허용).
  • 소스 종류만으로 차단하는 방식(모든 npm, 네트워크 또는 request.mode: "update" 요청).
  • 정책 명령을 선택 사항으로 취급하는 방식: security.installPolicy가 활성화되면 정책 실행 파일이 없거나, 느리거나, 읽을 수 없거나, 권한으로 차단될 경우 실패 시 차단됩니다.
  • 요청의 openclawVersion을 Plugin 후보 메타데이터와 비교하지 않고 버전을 승인하는 방식.

하나의 릴리스를 영구히 고정하는 대신 현재 호스트와 호환되는 신뢰할 수 있는 @openclaw/* 업데이트를 허용하는 규칙을 사용하세요. 기본적으로 npm을 차단한다면 사용하는 Plugin ID에만 적용되는 좁은 예외를 추가하고, 설치와 동일한 신뢰 규칙을 request.mode: "update"에도 적용하세요.

복구:

bash
openclaw doctor --deepopenclaw plugins update --allopenclaw status --all

정책이 의도적으로 엄격한 경우 신뢰할 수 있는 업그레이드 기간에만 정책을 완화하고 openclaw plugins update --all을 다시 실행한 다음 더 엄격한 규칙을 복원하세요. 업데이트 실패로 Plugin이 비활성화된 경우 다시 활성화하기 전에 검사하세요.

bash
openclaw plugins inspect <plugin-id> --runtime --jsonopenclaw plugins enable <plugin-id>

참고: 운영자 설치 정책

Plugin이 있지만 의심스러운 소유권 때문에 차단되는 경우

openclaw doctor, 설정 또는 시작 경고에 다음이 표시됩니다.

text
blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root)plugin present but blocked

Plugin 파일의 소유 Unix 사용자가 해당 파일을 로드하는 프로세스의 사용자와 다릅니다. Plugin 구성을 제거하지 마세요. 파일 소유권을 수정하거나 상태 디렉터리를 소유한 사용자로 OpenClaw를 실행하세요.

Docker 설치는 node(uid 1000)로 실행됩니다. 호스트 바인드 마운트를 수정하세요.

bash
sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspaceopenclaw doctor --fix

의도적으로 OpenClaw를 root로 실행하는 경우 대신 관리되는 Plugin 루트의 소유권을 수정하세요.

bash
sudo chown -R root:root /path/to/openclaw-config/npmopenclaw doctor --fix

심층 문서: 차단된 Plugin 경로 소유권, Docker: 권한 및 EACCES

의사 결정 트리

flowchart TD
  A[OpenClaw가 작동하지 않음] --> B{가장 먼저 문제가 발생하는 부분}
  B --> C[응답 없음]
  B --> D[대시보드 또는 Control UI가 연결되지 않음]
  B --> E[Gateway가 시작되지 않거나 서비스가 실행되지 않음]
  B --> F[채널은 연결되지만 메시지가 전달되지 않음]
  B --> G[Cron 또는 Heartbeat가 실행되지 않았거나 전달되지 않음]
  B --> H[Node가 페어링되었지만 카메라 캔버스 화면 실행이 실패함]
  B --> I[브라우저 도구가 실패함]

  C --> C1[/응답 없음 섹션/]
  D --> D1[/Control UI 섹션/]
  E --> E1[/Gateway 섹션/]
  F --> F1[/채널 흐름 섹션/]
  G --> G1[/자동화 섹션/]
  H --> H1[/Node 도구 섹션/]
  I --> I1[/브라우저 섹션/]
응답 없음
bash
openclaw statusopenclaw gateway statusopenclaw channels status --probeopenclaw pairing list --channel <channel> [--account <id>]openclaw logs --follow

정상 출력:

  • Runtime: running
  • Connectivity probe: ok
  • Capability: read-only, write-capable 또는 admin-capable
  • 채널 전송이 연결된 것으로 표시되고, 지원되는 경우 channels status --probe에 works 또는 audit ok가 표시됨
  • 발신자가 승인됨(또는 DM 정책이 공개/허용 목록 방식임)

로그 특징:

  • drop guild message (mention required → Discord 멘션 제한이 메시지를 차단했습니다.
  • pairing request → 발신자가 승인되지 않아 DM 페어링 승인을 기다리는 중입니다.
  • 채널 로그의 blocked / allowlist → 발신자, 대화방 또는 그룹이 필터링되었습니다.

심층 페이지: 응답 없음, 채널 문제 해결, 페어링

대시보드 또는 Control UI가 연결되지 않음
bash
openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

정상 출력:

  • openclaw gateway status에 Dashboard: http://...가 표시됨
  • Connectivity probe: ok
  • Capability: read-only, write-capable 또는 admin-capable
  • 로그에 인증 반복이 없음

로그 특징:

  • device identity required → HTTP/비보안 컨텍스트에서는 기기 인증을 완료할 수 없습니다.
  • origin not allowed → 브라우저 Origin이 Control UI Gateway 대상에 허용되지 않습니다.
  • canRetryWithDeviceToken=true가 포함된 AUTH_TOKEN_MISMATCH → 페어링된 토큰의 캐시된 범위를 재사용하여 신뢰할 수 있는 기기 토큰으로 한 번 자동 재시도할 수 있습니다.
  • 해당 재시도 후 반복되는 unauthorized → 잘못된 토큰/비밀번호, 인증 모드 불일치 또는 오래된 페어링 기기 토큰입니다.
  • too many failed authentication attempts (retry later) → 해당 브라우저 Origin에서 반복적으로 실패하여 일시적으로 잠겼습니다. 다른 localhost 출처에는 별도의 버킷이 적용됩니다. Tailscale Serve 동시 재시도 관련 세부 사항은 대시보드/Control UI 연결을 참조하세요.
  • gateway connect failed: → UI가 잘못된 URL/포트를 대상으로 하거나 Gateway에 연결할 수 없습니다.

심층 페이지: 대시보드/Control UI 연결, Control UI, 인증

Gateway가 시작되지 않거나 서비스가 설치되었지만 실행되지 않음
bash
openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

정상 출력:

  • Service: ... (loaded)
  • Runtime: running
  • Connectivity probe: ok
  • Capability: read-only, write-capable 또는 admin-capable

로그 특징:

  • Gateway start blocked: set gateway.mode=local 또는 existing config is missing gateway.mode → Gateway 모드가 원격이거나 구성에 로컬 모드 표시가 없어 복구가 필요합니다.
  • refusing to bind gateway ... without auth → 유효한 인증 경로(토큰/비밀번호 또는 구성된 경우 신뢰할 수 있는 프록시) 없이 비루프백 주소에 바인딩하려고 했습니다.
  • another gateway instance is already listening 또는 EADDRINUSE → 포트가 이미 사용 중입니다.

심층 페이지: Gateway 서비스가 실행되지 않음, 백그라운드 프로세스, 구성

채널은 연결되지만 메시지가 전달되지 않음
bash
openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

정상 출력:

  • 채널 전송이 연결됨.
  • 페어링/허용 목록 검사를 통과함.
  • 필요한 경우 멘션이 감지됨.

로그 특징:

  • mention required → 그룹 멘션 제한이 처리를 차단했습니다.
  • pairing / pending → DM 발신자가 아직 승인되지 않았습니다.
  • not_in_channel, missing_scope, Forbidden, 401/403 → 채널 권한 토큰 문제입니다.

심층 페이지: 채널은 연결되었지만 메시지가 전달되지 않음, 채널 문제 해결

Cron 또는 Heartbeat가 실행되지 않았거나 전달되지 않음
bash
openclaw statusopenclaw gateway statusopenclaw cron statusopenclaw cron listopenclaw cron runs --id <jobId> --limit 20openclaw logs --follow

정상 출력:

  • cron status에 스케줄러가 활성화되어 있고 다음 실행 시각이 표시됨.
  • cron runs에 최근 ok 항목이 표시됨.
  • Heartbeat가 활성화되어 있고 활성 시간 내에 있음.

로그 특징:

  • cron: scheduler disabled; jobs will not run automatically → Cron이 비활성화되어 있습니다.
  • heartbeat skipped 사유 quiet-hours → 구성된 활성 시간 외입니다.
  • heartbeat skipped 사유 empty-heartbeat-file → HEARTBEAT.md가 존재하지만 공백, 주석, 헤더, 펜스 또는 빈 체크리스트용 뼈대만 포함되어 있습니다.
  • heartbeat skipped 사유 no-tasks-due → 작업 모드가 활성화되어 있지만 아직 실행 시점이 된 작업 간격이 없습니다.
  • heartbeat skipped 사유 alerts-disabled → showOk, showAlerts, useIndicator가 모두 꺼져 있습니다.
  • requests-in-flight → 메인 레인이 사용 중이므로 Heartbeat 깨우기가 연기되었습니다.
  • unknown accountId → Heartbeat 전송 대상 계정이 존재하지 않습니다.

자세한 문서: Cron 및 Heartbeat 전송, 예약 작업: 문제 해결, Heartbeat

Node is paired but tool fails camera canvas screen exec
bash
openclaw statusopenclaw gateway statusopenclaw nodes statusopenclaw nodes describe --node <idOrNameOrIp>openclaw logs --follow

정상 출력:

  • Node가 node 역할로 연결 및 페어링된 것으로 표시됩니다.
  • 호출하려는 명령에 필요한 기능이 존재합니다.
  • 도구에 대한 권한 상태가 허용으로 표시됩니다.

로그 특징:

  • NODE_BACKGROUND_UNAVAILABLE → Node 앱을 포그라운드로 전환하세요.
  • *_PERMISSION_REQUIRED → 운영 체제 권한이 거부되었거나 누락되었습니다.
  • SYSTEM_RUN_DENIED: approval required → exec 승인이 대기 중입니다.
  • SYSTEM_RUN_DENIED: allowlist miss → 명령이 exec 허용 목록에 없습니다.

자세한 문서: Node가 페어링되었지만 도구가 실패하는 경우, Node 문제 해결, Exec 승인

Exec suddenly asks for approval
bash
openclaw config get tools.exec.hostopenclaw config get tools.exec.securityopenclaw config get tools.exec.askopenclaw gateway restart

변경된 사항:

  • 설정되지 않은 tools.exec.host의 기본값은 auto이며, 샌드박스 런타임이 활성화된 경우 sandbox로, 그렇지 않으면 gateway로 결정됩니다.
  • host=auto는 라우팅만 수행합니다. 프롬프트를 표시하지 않는 동작은 Gateway/Node에서 security=full과 ask=off를 함께 설정할 때 적용됩니다.
  • 설정되지 않은 tools.exec.security는 gateway/node에서 기본적으로 full입니다.
  • 설정되지 않은 tools.exec.ask의 기본값은 off입니다.
  • 승인이 표시된다면 호스트 로컬 정책이나 세션별 정책에서 exec 설정이 이러한 기본값보다 엄격하게 변경된 것입니다.

현재의 승인 불필요 기본값 복원:

bash
openclaw config set tools.exec.host gatewayopenclaw config set tools.exec.security fullopenclaw config set tools.exec.ask offopenclaw gateway restart

더 안전한 대안:

  • 안정적인 호스트 라우팅을 위해 tools.exec.host=gateway만 설정하세요.
  • 호스트 exec에서 허용 목록에 없는 명령을 검토하려면 security=allowlist와 ask=on-miss를 사용하세요.
  • 샌드박스 모드를 활성화하여 host=auto가 다시 sandbox로 결정되도록 하세요.

로그 특징:

  • Approval required. → 명령이 /approve ...를 기다리고 있습니다.
  • SYSTEM_RUN_DENIED: approval required → Node 호스트의 exec 승인이 대기 중입니다.
  • exec host=sandbox requires a sandbox runtime for this session → 샌드박스가 암시적 또는 명시적으로 선택되었지만 샌드박스 모드가 꺼져 있습니다.

자세한 문서: Exec, Exec 승인, 보안: 감사 검사 항목

Browser tool fails
bash
openclaw statusopenclaw gateway statusopenclaw browser statusopenclaw logs --followopenclaw doctor

정상 출력:

  • 브라우저 상태에 running: true와 선택된 브라우저/프로필이 표시됩니다.
  • openclaw 프로필이 시작되거나 user 프로필에서 로컬 Chrome 탭이 표시됩니다.

로그 특징:

  • unknown command "browser" → plugins.allow가 설정되어 있으며 browser가 제외되어 있습니다.
  • Failed to start Chrome CDP on port → 로컬 브라우저를 시작하지 못했습니다.
  • browser.executablePath not found → 구성된 바이너리 경로가 잘못되었습니다.
  • browser.cdpUrl must be http(s) or ws(s) → 구성된 CDP URL에서 지원되지 않는 스킴을 사용합니다.
  • browser.cdpUrl has invalid port → 구성된 CDP URL의 포트가 잘못되었거나 허용 범위를 벗어났습니다.
  • No Chrome tabs found for profile="user" → Chrome MCP 연결 프로필에 열려 있는 로컬 Chrome 탭이 없습니다.
  • Remote CDP for profile "<name>" is not reachable → 이 호스트에서 구성된 원격 CDP 엔드포인트에 연결할 수 없습니다.
  • Browser attachOnly is enabled ... not reachable → 연결 전용 프로필에 활성 CDP 대상이 없습니다.
  • 연결 전용 또는 원격 CDP 프로필에 오래된 뷰포트/다크 모드/로캘/오프라인 재정의가 남아 있는 경우 → Gateway를 다시 시작하지 않고 제어 세션을 닫고 에뮬레이션 상태를 해제하려면 openclaw browser stop --browser-profile <name>을 실행하세요.

자세한 문서: 브라우저 도구 실패, 브라우저 명령 또는 도구 누락, 브라우저: Linux 문제 해결, 브라우저: WSL2/Windows 원격 CDP 문제 해결

관련 문서

Was this useful?
On this page

On this page