Nodes and media
Node 문제 해결
상태에는 Node가 표시되지만 Node 도구가 실패할 때 이 페이지를 사용하세요.
명령 단계
openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe그런 다음 Node별 검사를 실행하세요.
openclaw nodes statusopenclaw nodes describe --node <idOrNameOrIp>openclaw approvals get --node <idOrNameOrIp>정상 신호:
- Node가 연결되어 있고
node역할로 페어링되어 있습니다. nodes describe에 호출하려는 기능이 포함되어 있습니다.- 실행 승인이 예상 모드/허용 목록을 표시합니다.
포그라운드 요구 사항
iOS/Android Node에서 canvas.*, camera.*, screen.*는 포그라운드에서만 사용할 수 있습니다.
빠른 확인 및 해결:
openclaw nodes describe --node <idOrNameOrIp>openclaw nodes canvas snapshot --node <idOrNameOrIp>openclaw logs --followNODE_BACKGROUND_UNAVAILABLE이 표시되면 Node 앱을 포그라운드로 전환한 후 다시 시도하세요.
권한 매트릭스
| 기능 | iOS | Android | macOS Node 앱 | 일반적인 실패 코드 |
|---|---|---|---|---|
camera.snap, camera.clip |
카메라(클립 오디오에는 마이크도 필요) | 카메라(클립 오디오에는 마이크도 필요) | 카메라(클립 오디오에는 마이크도 필요) | *_PERMISSION_REQUIRED |
screen.record |
화면 기록(마이크는 선택 사항) | 화면 캡처 프롬프트(마이크는 선택 사항) | 화면 기록 | *_PERMISSION_REQUIRED |
computer.act |
해당 없음 | 해당 없음 | 손쉬운 사용 + 화면 기록 | COMPUTER_DISABLED, ACCESSIBILITY_REQUIRED |
location.get |
앱을 사용하는 동안 또는 항상(모드에 따라) | 모드에 따른 포그라운드/백그라운드 위치 | 위치 권한 | LOCATION_PERMISSION_REQUIRED |
system.run |
해당 없음(Node 호스트 경로) | 해당 없음(Node 호스트 경로) | 실행 승인 필요 | SYSTEM_RUN_DENIED |
페어링과 승인 비교
Node 명령의 성공 여부는 서로 분리된 세 가지 게이트에 의해 제어됩니다.
- 기기 페어링: 이 Node가 Gateway에 연결할 수 있습니까?
- Gateway Node 명령 정책:
gateway.nodes.allowCommands/denyCommands와 플랫폼 기본값에서 해당 RPC 명령 ID를 허용합니까? - 실행 승인: 이 Node가 특정 셸 명령을 로컬에서 실행할 수 있습니까?
Node 페어링은 ID/신뢰 게이트이며 명령별 승인 인터페이스가 아닙니다. system.run의 경우 Node별 정책은 Gateway 페어링 레코드가 아니라 해당 Node의 실행 승인 파일(openclaw approvals get --node ...)에 있습니다.
빠른 확인:
openclaw devices listopenclaw nodes statusopenclaw approvals get --node <idOrNameOrIp>openclaw approvals allowlist add --node <idOrNameOrIp> "/usr/bin/uname"- 페어링 누락: 먼저 Node 기기를 승인하세요.
nodes describe에 명령이 누락됨: Gateway Node 명령 정책과 Node가 연결할 때 실제로 해당 명령을 선언했는지 확인하세요.- 페어링은 정상이지만
system.run실패: 해당 Node의 실행 승인/허용 목록을 수정하세요.
승인 기반 host=node 실행의 경우 Gateway는 실행을 준비된 정규 systemRunPlan에도 바인딩합니다. 승인된 실행이 전달되기 전에 후속 호출자가 명령, cwd 또는 세션 메타데이터를 변경하면 Gateway는 편집된 페이로드를 신뢰하지 않고 승인 불일치로 실행을 거부합니다.
일반적인 Node 오류 코드
| 코드 | 의미 |
|---|---|
NODE_BACKGROUND_UNAVAILABLE |
앱이 백그라운드에 있습니다. 포그라운드로 전환하세요. |
CAMERA_DISABLED |
Node 설정에서 카메라 토글이 비활성화되어 있습니다. |
*_PERMISSION_REQUIRED |
OS 권한이 없거나 거부되었습니다. |
LOCATION_DISABLED |
위치 모드가 꺼져 있습니다. |
LOCATION_PERMISSION_REQUIRED |
요청한 위치 모드가 허용되지 않았습니다. |
LOCATION_BACKGROUND_UNAVAILABLE |
앱이 백그라운드에 있지만 ‘앱을 사용하는 동안’ 권한만 있습니다. |
COMPUTER_DISABLED |
macOS 앱에서 Allow Computer Control을 활성화한 다음 페어링 업데이트를 승인하세요. |
ACCESSIBILITY_REQUIRED |
macOS System Settings에서 현재 OpenClaw 앱 번들에 Accessibility 권한을 부여하세요. |
SYSTEM_RUN_DENIED: approval required |
실행 요청에 명시적인 승인이 필요합니다. |
SYSTEM_RUN_DENIED: allowlist miss |
허용 목록 모드에서 명령이 차단되었습니다. Windows Node 호스트에서는 cmd.exe /c ...와 같은 셸 래퍼 형식이 질문 흐름을 통해 승인되지 않는 한 허용 목록 모드에서 허용 목록 불일치로 처리됩니다. |
빠른 복구 절차
openclaw nodes statusopenclaw nodes describe --node <idOrNameOrIp>openclaw approvals get --node <idOrNameOrIp>openclaw logs --follow그래도 해결되지 않는 경우:
- 기기 페어링을 다시 승인하세요.
- Node 앱을 다시 여세요(포그라운드).
- OS 권한을 다시 부여하세요.
- 실행 승인 정책을 다시 만들거나 조정하세요.
컴퓨터 제어의 경우 비전 기능을 지원하는 에이전트가 computer 도구를 노출하는지, 화면 기록 권한으로 screen.snapshot이 성공하는지, /phone status에 의도한 임시 또는 영구 Gateway 권한 부여가 표시되는지도 확인하세요. gateway.nodes.denyCommands 항목은 항상 allowCommands보다 우선합니다.
