OpenClaw 노드 문제 해결: 5분 만에 오류 진단 및 복구

Node가 상태 창에는 분명히 떠 있는데, 막상 도구를 실행하면 작동하지 않아 당황스러웠던 적 있으시죠? 연결은 된 것 같은데 명령만 내리면 에러가 발생하는 상황은 개발자를 참 힘들게 합니다. 이럴 때 빠르게 문제를 진단하고 해결할 수 있는 가이드를 준비했습니다.

Node troubleshooting

Node가 상태 창에는 보이지만 Node 관련 도구가 작동하지 않을 때 이 페이지를 참고하세요.

커맨드 단계별 확인

먼저 전체적인 상태를 확인해 보세요.

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

그 다음, 특정 Node에 대한 체크를 실행합니다.

openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>

정상적인 신호는 다음과 같습니다:

• Node가 node 역할로 연결 및 페어링되어 있습니다.
• nodes describe 결과에 호출하려는 capability가 포함되어 있습니다.
• Exec approvals가 예상된 mode 및 allowlist를 보여줍니다.

포그라운드 실행 요구사항

iOS 및 Android Node에서 canvas.*, camera.*, screen.* 기능은 포그라운드 상태에서만 작동합니다.

빠르게 확인하고 수정하는 방법입니다:

openclaw nodes describe --node <idOrNameOrIp>
openclaw nodes canvas snapshot --node <idOrNameOrIp>
openclaw logs --follow

만약 NODE_BACKGROUND_UNAVAILABLE 에러가 보인다면, Node 앱을 포그라운드로 전환하고 다시 시도하세요.

권한 매트릭스

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
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

페어링과 승인의 차이

이 둘은 서로 다른 관문입니다:

1. Device pairing: 이 Node가 Gateway에 연결할 수 있나요?
2. Gateway node command policy: RPC 명령 ID가 gateway.nodes.allowCommands / denyCommands 및 플랫폼 기본값에 의해 허용되었나요?
3. Exec approvals: 이 Node가 로컬에서 특정 쉘 명령을 실행할 수 있나요?

빠른 확인 방법:

openclaw devices list
openclaw nodes status
openclaw approvals get --node <idOrNameOrIp>
openclaw approvals allowlist add --node <idOrNameOrIp> "/usr/bin/uname"

페어링이 되어 있지 않다면 Node 장치를 먼저 승인하세요. nodes describe에서 명령어가 빠져 있다면, Gateway의 Node 명령 정책과 Node가 연결될 때 해당 명령을 실제로 선언했는지 확인하세요. 페어링은 정상이지만 system.run이 실패한다면, 해당 Node의 exec approvals 및 allowlist를 수정해야 합니다.

Node 페어링은 ID와 신뢰를 확인하는 관문이지, 개별 명령을 승인하는 곳이 아닙니다. system.run의 경우, Node별 정책은 Gateway 페어링 기록이 아니라 해당 Node의 exec approvals 파일(openclaw approvals get --node ...)에서 관리됩니다.

주요 Node 에러 코드

• NODE_BACKGROUND_UNAVAILABLE → 앱이 백그라운드에 있습니다. 포그라운드로 전환하세요.
• CAMERA_DISABLED → Node 설정에서 카메라 토글이 꺼져 있습니다.
• *_PERMISSION_REQUIRED → OS 권한이 없거나 거부되었습니다.
• LOCATION_DISABLED → 위치 모드가 꺼져 있습니다.
• LOCATION_PERMISSION_REQUIRED → 요청한 위치 모드 권한이 부여되지 않았습니다.
• LOCATION_BACKGROUND_UNAVAILABLE → 앱이 백그라운드에 있지만 ‘앱 사용하는 동안만 허용’ 권한만 있습니다.
• SYSTEM_RUN_DENIED: approval required → 실행 요청에 명시적인 승인이 필요합니다.
• SYSTEM_RUN_DENIED: allowlist miss → allowlist 모드에 의해 명령이 차단되었습니다. Windows Node 호스트에서 cmd.exe /c ...와 같은 쉘 래퍼 형태는 ask flow를 통해 승인되지 않는 한 allowlist 모드에서 누락된 것으로 처리됩니다.

빠른 복구 루프

openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
openclaw logs --follow

여전히 문제가 해결되지 않는다면:

• 장치 페어링을 다시 승인하세요.
• Node 앱을 다시 여세요 (포그라운드).
• OS 권한을 다시 부여하세요.
• Exec approval 정책을 다시 생성하거나 조정하세요.

다음 단계:

• /nodes/index
• /nodes/camera
• /nodes/location-command
• /tools/exec-approvals
• /gateway/pairing

AI Setup Assistant