노드 문제 해결

노드가 상태에서 보이지만 노드 도구가 실패할 때 이 페이지를 사용하세요.

명령어 단계

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>

정상 신호:

노드가 연결되었고 node 역할로 페어링됨.
nodes describe에 호출하려는 기능이 포함되어 있음.
실행 승인에 예상된 모드/허용 목록이 표시됨.

포그라운드 요구사항

canvas.*, camera.*, screen.*은 iOS/Android 노드에서 포그라운드 전용입니다.

빠른 확인 및 수정:

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

NODE_BACKGROUND_UNAVAILABLE이 표시되면, 노드 앱을 포그라운드로 가져온 후 다시 시도하세요.

권한 매트릭스

기능	iOS	Android	macOS 노드 앱	일반적인 실패 코드
`camera.snap`, `camera.clip`	카메라 (+ 클립 오디오용 마이크)	카메라 (+ 클립 오디오용 마이크)	카메라 (+ 클립 오디오용 마이크)	`*_PERMISSION_REQUIRED`
`screen.record`	화면 기록 (+ 마이크 선택사항)	화면 캡처 프롬프트 (+ 마이크 선택사항)	화면 기록	`*_PERMISSION_REQUIRED`
`location.get`	사용 중 또는 항상 (모드에 따라)	모드에 따른 포그라운드/백그라운드 위치	위치 권한	`LOCATION_PERMISSION_REQUIRED`
`system.run`	해당 없음 (노드 호스트 경로)	해당 없음 (노드 호스트 경로)	실행 승인 필요	`SYSTEM_RUN_DENIED`

페어링 vs 승인

이 둘은 다른 게이트입니다:

디바이스 페어링: 이 노드가 게이트웨이에 연결할 수 있는가?
실행 승인: 이 노드가 특정 셸 명령어를 실행할 수 있는가?

빠른 확인:

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

페어링이 없으면 먼저 노드 디바이스를 승인하세요. 페어링은 정상이지만 system.run이 실패하면 실행 승인/허용 목록을 수정하세요.

일반적인 노드 오류 코드

NODE_BACKGROUND_UNAVAILABLE → 앱이 백그라운드 상태입니다. 포그라운드로 가져오세요.
CAMERA_DISABLED → 노드 설정에서 카메라 토글이 비활성화되어 있습니다.
*_PERMISSION_REQUIRED → OS 권한이 없거나 거부되었습니다.
LOCATION_DISABLED → 위치 모드가 꺼져 있습니다.
LOCATION_PERMISSION_REQUIRED → 요청된 위치 모드가 부여되지 않았습니다.
LOCATION_BACKGROUND_UNAVAILABLE → 앱이 백그라운드이지만 “사용 중” 권한만 있습니다.
SYSTEM_RUN_DENIED: approval required → 실행 요청에 명시적 승인이 필요합니다.
SYSTEM_RUN_DENIED: allowlist miss → 허용 목록 모드에 의해 명령어가 차단되었습니다. Windows 노드 호스트에서 cmd.exe /c ...와 같은 셸 래퍼 형태는 ask 흐름을 통해 승인되지 않는 한 허용 목록 모드에서 허용 목록 미스로 처리됩니다.

빠른 복구 루프

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

여전히 문제가 있으면:

디바이스 페어링을 다시 승인하세요.
노드 앱을 다시 열어 포그라운드로 가져오세요.
OS 권한을 다시 부여하세요.
실행 승인 정책을 재생성/조정하세요.