Node troubleshooting
기준일: 2026-07-26
공식 기준: Node troubleshooting
Node troubleshooting 문서는 OpenClaw 공식 문서(nodes/troubleshooting)를 한국어로 정리한 가이드입니다. Troubleshoot node pairing, foreground requirements, permissions, and tool failures 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.
핵심 요약
Troubleshoot node pairing, foreground requirements, permissions, and tool failures
한국어 가이드 범위: nodes/troubleshooting 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.
문서 구성
공식 문서의 주요 섹션은 다음과 같습니다.
- Command ladder
- Foreground requirements
- Permissions matrix
- Pairing versus approvals
- Common node error codes
- Fast recovery loop
- 관련 문서
상세 내용
본문
Use this page when a node is visible in status but node tools fail.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
Command ladder
주요 항목:
- Node is connected and paired for role
node. nodes describeincludes the capability you're calling.- Exec approvals show the expected mode/allowlist.
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
Foreground requirements
canvas.*, camera.*, and screen.* are foreground-only on iOS/Android nodes.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
openclaw nodes describe --node <idOrNameOrIp>
openclaw nodes canvas snapshot --node <idOrNameOrIp>
openclaw logs --follow
Permissions matrix
| Capability | iOS | Android | macOS node app | Typical failure code |
|---|---|---|---|---|
camera.snap, camera.clip |
Camera (+ mic for clip audio) | Camera (+ mic for clip audio) | Camera (+ mic for clip audio) | *_PERMISSION_REQUIRED |
screen.record |
Screen Recording (+ mic optional) | Screen capture prompt (+ mic optional) | Screen Recording | *_PERMISSION_REQUIRED |
computer.act |
n/a | n/a | Accessibility + Screen Recording | COMPUTER_DISABLED, ACCESSIBILITY_REQUIRED |
location.get |
While Using or Always (depends on mode) | Foreground/Background location based on mode | Location permission | LOCATION_PERMISSION_REQUIRED |
system.run |
n/a (node host path) | n/a (node host path) | Exec approvals required | SYSTEM_RUN_DENIED |
Pairing versus approvals
Three separate gates control whether a node command succeeds:
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
주요 항목:
- Pairing missing: approve the node device first.
nodes describemissing a command: check the gateway node command policy and whether the node actually declared that command on connect.- Pairing fine but
system.runfails: fix exec approvals/allowlist on that node.
openclaw devices list
openclaw nodes status
openclaw approvals get --node <idOrNameOrIp>
openclaw approvals allowlist add --node <idOrNameOrIp> "/usr/bin/uname"
Common node error codes
| Code | Meaning |
|---|---|
NODE_BACKGROUND_UNAVAILABLE |
App is backgrounded; bring it to the foreground. |
CAMERA_DISABLED |
Camera toggle disabled in node settings. |
*_PERMISSION_REQUIRED |
OS permission missing/denied. |
LOCATION_DISABLED |
Location mode is off. |
LOCATION_PERMISSION_REQUIRED |
Requested location mode not granted. |
LOCATION_BACKGROUND_UNAVAILABLE |
App is backgrounded but only While Using permission exists. |
COMPUTER_DISABLED |
Enable Allow Computer Control in the macOS app, then approve the pairing update. |
ACCESSIBILITY_REQUIRED |
Grant Accessibility to the current OpenClaw app bundle in macOS System Settings. |
SYSTEM_RUN_DENIED: approval required |
Exec request needs explicit approval. |
SYSTEM_RUN_DENIED: allowlist miss |
Command blocked by allowlist mode. On Windows node hosts, shell-wrapper forms like cmd.exe /c ... are treated as allowlist misses in allowlist mode unless approved via the ask flow. |
Fast recovery loop
For computer control, also verify that a vision-capable agent exposes the computer tool, screen.snapshot succeeds with Screen Recording permission, and /phone status shows the temporary or persistent gateway authorization you intended. A gateway.nodes.commands.deny entry always overrides gateway.nodes.commands.allow.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
주요 항목:
- Re-approve device pairing.
- Re-open the node app (foreground).
- Re-grant OS permissions.
- Recreate/adjust the exec approval policy.
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
openclaw logs --follow
관련 문서
주요 항목:
- Nodes overview
- Camera nodes
- Location command
- Computer use
- Exec approvals
- Gateway pairing
- Gateway troubleshooting
- Channel troubleshooting
실습 체크리스트
- 공식 문서와 로컬 버전을 대조합니다:
https://docs.openclaw.ai/nodes/troubleshooting - 관련 CLI는
openclaw --help및 하위 명령--help로 옵션을 확인합니다. - 설정 변경 시
openclaw config/openclaw doctor로 유효성을 검사합니다. - Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.
자주 쓰는 명령·설정 예시
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
openclaw nodes describe --node <idOrNameOrIp>
openclaw nodes canvas snapshot --node <idOrNameOrIp>
openclaw logs --follow
openclaw devices list
openclaw nodes status
openclaw approvals get --node <idOrNameOrIp>
openclaw approvals allowlist add --node <idOrNameOrIp> "/usr/bin/uname"
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
openclaw logs --follow
관련 링크
이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.