Nodes and media
Solución de problemas de Node
Use esta página cuando un Node sea visible en el estado, pero las herramientas del Node fallen.
Secuencia de comandos
openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probeA continuación, ejecute comprobaciones específicas del Node:
openclaw nodes statusopenclaw nodes describe --node <idOrNameOrIp>openclaw approvals get --node <idOrNameOrIp>Indicadores de funcionamiento correcto:
- El Node está conectado y emparejado para el rol
node. nodes describeincluye la capacidad que intenta invocar.- Las aprobaciones de ejecución muestran el modo y la lista de permitidos esperados.
Requisitos de primer plano
canvas.*, camera.* y screen.* solo funcionan en primer plano en los Nodes iOS/Android.
Comprobación y solución rápidas:
openclaw nodes describe --node <idOrNameOrIp>openclaw nodes canvas snapshot --node <idOrNameOrIp>openclaw logs --followSi ve NODE_BACKGROUND_UNAVAILABLE, lleve la aplicación del Node al primer plano y vuelva a intentarlo.
Matriz de permisos
| Capacidad | iOS | Android | Aplicación de Node para macOS | Código de error habitual |
|---|---|---|---|---|
camera.snap, camera.clip |
Cámara (+ micrófono para el audio del clip) | Cámara (+ micrófono para el audio del clip) | Cámara (+ micrófono para el audio del clip) | *_PERMISSION_REQUIRED |
screen.record |
Grabación de pantalla (+ micrófono opcional) | Solicitud de captura de pantalla (+ micrófono opcional) | Grabación de pantalla | *_PERMISSION_REQUIRED |
computer.act |
no aplicable | no aplicable | Accesibilidad + grabación de pantalla | COMPUTER_DISABLED, ACCESSIBILITY_REQUIRED |
location.get |
Al usar la aplicación o siempre (depende del modo) | Ubicación en primer plano/segundo plano según el modo | Permiso de ubicación | LOCATION_PERMISSION_REQUIRED |
system.run |
no aplicable (ruta del host del Node) | no aplicable (ruta del host del Node) | Se requieren aprobaciones de ejecución | SYSTEM_RUN_DENIED |
Emparejamiento frente a aprobaciones
Tres controles independientes determinan si un comando del Node se ejecuta correctamente:
- Emparejamiento del dispositivo: ¿puede este Node conectarse al Gateway?
- Política de comandos de Nodes del Gateway: ¿las opciones
gateway.nodes.allowCommands/denyCommandsy los valores predeterminados de la plataforma permiten el identificador del comando RPC? - Aprobaciones de ejecución: ¿puede este Node ejecutar localmente un comando de shell específico?
El emparejamiento del Node es un control de identidad y confianza, no una superficie de aprobación por comando. Para system.run, la política específica de cada Node reside en el archivo de aprobaciones de ejecución de ese Node (openclaw approvals get --node ...), no en el registro de emparejamiento del Gateway.
Comprobaciones rápidas:
openclaw devices listopenclaw nodes statusopenclaw approvals get --node <idOrNameOrIp>openclaw approvals allowlist add --node <idOrNameOrIp> "/usr/bin/uname"- Falta el emparejamiento: apruebe primero el dispositivo del Node.
- Falta un comando en
nodes describe: compruebe la política de comandos de Nodes del Gateway y si el Node realmente declaró ese comando al conectarse. - El emparejamiento es correcto, pero
system.runfalla: corrija las aprobaciones de ejecución o la lista de permitidos de ese Node.
Para las ejecuciones host=node respaldadas por aprobaciones, el Gateway también vincula la ejecución al systemRunPlan canónico preparado. Si un llamador posterior modifica el comando, el directorio de trabajo o los metadatos de la sesión antes de que se reenvíe la ejecución aprobada, el Gateway rechaza la ejecución por una discrepancia de aprobación en lugar de confiar en la carga útil modificada.
Códigos de error habituales de los Nodes
| Código | Significado |
|---|---|
NODE_BACKGROUND_UNAVAILABLE |
La aplicación está en segundo plano; llévela al primer plano. |
CAMERA_DISABLED |
El interruptor de la cámara está desactivado en la configuración del Node. |
*_PERMISSION_REQUIRED |
Falta el permiso del sistema operativo o se ha denegado. |
LOCATION_DISABLED |
El modo de ubicación está desactivado. |
LOCATION_PERMISSION_REQUIRED |
No se ha concedido el modo de ubicación solicitado. |
LOCATION_BACKGROUND_UNAVAILABLE |
La aplicación está en segundo plano, pero solo dispone del permiso Al usar la aplicación. |
COMPUTER_DISABLED |
Active Allow Computer Control en la aplicación para macOS y, a continuación, apruebe la actualización del emparejamiento. |
ACCESSIBILITY_REQUIRED |
Conceda el permiso de accesibilidad al paquete actual de la aplicación OpenClaw en la configuración del sistema de macOS. |
SYSTEM_RUN_DENIED: approval required |
La solicitud de ejecución necesita aprobación explícita. |
SYSTEM_RUN_DENIED: allowlist miss |
El modo de lista de permitidos bloqueó el comando. En los hosts de Node con Windows, las formas con contenedor de shell como cmd.exe /c ... se consideran ausentes de la lista de permitidos, salvo que se aprueben mediante el flujo de consulta. |
Ciclo de recuperación rápida
openclaw nodes statusopenclaw nodes describe --node <idOrNameOrIp>openclaw approvals get --node <idOrNameOrIp>openclaw logs --followSi el problema persiste:
- Vuelva a aprobar el emparejamiento del dispositivo.
- Vuelva a abrir la aplicación del Node en primer plano.
- Vuelva a conceder los permisos del sistema operativo.
- Vuelva a crear o ajuste la política de aprobaciones de ejecución.
Para el control del ordenador, compruebe también que un agente con capacidad de visión exponga la herramienta computer, que screen.snapshot se ejecute correctamente con el permiso de grabación de pantalla y que /phone status muestre la autorización temporal o persistente del Gateway que pretendía usar. Una entrada de gateway.nodes.denyCommands siempre prevalece sobre allowCommands.
