Nodes and media
Solución de problemas de Node
Use esta página cuando un nodo sea visible en el estado, pero las herramientas del nodo fallen.
Secuencia de comandos
openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probeA continuación, ejecute las comprobaciones específicas del nodo:
openclaw nodes statusopenclaw nodes describe --node <idOrNameOrIp>openclaw approvals get --node <idOrNameOrIp>Indicadores de funcionamiento correcto:
- El nodo está conectado y emparejado para el rol
node. nodes describeincluye la capacidad que se está invocando.- Las aprobaciones de ejecución muestran el modo o la lista de permitidos esperados.
Requisitos de primer plano
canvas.*, camera.* y screen.* solo funcionan en primer plano en nodos iOS/Android.
Comprobación y solución rápidas:
openclaw nodes describe --node <idOrNameOrIp>openclaw nodes canvas snapshot --node <idOrNameOrIp>openclaw logs --followSi aparece NODE_BACKGROUND_UNAVAILABLE, lleve la aplicación del nodo al primer plano y vuelva a intentarlo.
Matriz de permisos
| Capacidad | iOS | Android | Aplicación de nodo 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 disponible | No disponible | Accesibilidad + Grabación de pantalla | COMPUTER_DISABLED, ACCESSIBILITY_REQUIRED |
location.get |
While Using o Always (depende del modo) | Ubicación en primer o segundo plano según el modo | Permiso de ubicación | LOCATION_PERMISSION_REQUIRED |
system.run |
No disponible (ruta del host del nodo) | No disponible (ruta del host del nodo) | Se requieren aprobaciones de ejecución | SYSTEM_RUN_DENIED |
Emparejamiento frente a aprobaciones
Tres controles independientes determinan si un comando de nodo se ejecuta correctamente:
- Emparejamiento del dispositivo: ¿puede este nodo conectarse al Gateway?
- Política de comandos de nodo del Gateway: ¿permiten
gateway.nodes.commands.allow/gateway.nodes.commands.denyy los valores predeterminados de la plataforma el identificador del comando RPC? - Aprobaciones de ejecución: ¿puede este nodo ejecutar localmente un comando de shell específico?
El emparejamiento de nodos es un control de identidad y confianza, no una interfaz de aprobación por comando. Para system.run, la política por nodo reside en el archivo de aprobaciones de ejecución de ese nodo (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 nodo.
- A
nodes describele falta un comando: compruebe la política de comandos de nodo del Gateway y si el nodo declaró realmente ese comando al conectarse. - El emparejamiento es correcto, pero
system.runfalla: corrija las aprobaciones de ejecución o la lista de permitidos en ese nodo.
Para las ejecuciones de host=node respaldadas por aprobación, el Gateway también vincula la ejecución al systemRunPlan canónico preparado. Si posteriormente un invocador modifica el comando, el directorio de trabajo o los metadatos de la sesión antes de reenviar la ejecución aprobada, el Gateway rechaza la ejecución por discrepancia con la aprobación en lugar de confiar en la carga útil modificada.
Códigos de error habituales de los nodos
| Código | Significado |
|---|---|
NODE_BACKGROUND_UNAVAILABLE |
La aplicación está en segundo plano; llévela al primer plano. |
CAMERA_DISABLED |
El selector de la cámara está desactivado en la configuración del nodo. |
*_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 existe el permiso While Using. |
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 Accessibility al paquete actual de la aplicación OpenClaw en macOS System Settings. |
SYSTEM_RUN_DENIED: approval required |
La solicitud de ejecución requiere aprobación explícita. |
SYSTEM_RUN_DENIED: allowlist miss |
El modo de lista de permitidos bloqueó el comando. En los hosts de nodo Windows, las formas de envoltorio de shell como cmd.exe /c ... se consideran ausentes de la lista de permitidos en ese modo, salvo que se aprueben mediante el flujo de solicitud. |
Bucle 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 nodo en primer plano.
- Vuelva a conceder los permisos del sistema operativo.
- Vuelva a crear o ajuste la política de aprobación de ejecución.
Para el control del equipo, verifique también que un agente con capacidad de visión exponga la herramienta computer, que screen.snapshot se ejecute correctamente con el permiso Grabación de pantalla y que /phone status muestre la autorización temporal o persistente del Gateway prevista. Una entrada gateway.nodes.commands.deny siempre prevalece sobre gateway.nodes.commands.allow.
