Solución de problemas de nodos

Use esta página cuando un nodo sea visible en el estado pero las herramientas del nodo fallen.

Escalera de comandos

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

A continuación, ejecute comprobaciones específicas del nodo:

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

Señales de funcionamiento correcto:

El nodo está conectado y emparejado para el rol node.
nodes describe incluye la capacidad que está llamando.
Las aprobaciones de ejecución muestran el modo/lista blanca esperados.

Requisitos en primer plano

canvas.*, camera.* y screen.* funcionan solo en primer plano en nodos iOS/Android.

Verificación y solución rápida:

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

Si ve NODE_BACKGROUND_UNAVAILABLE, traiga la aplicación del nodo al primer plano y reintente.

Matriz de permisos

Capacidad	iOS	Android	Aplicación de nodo macOS	Código de error típico
`camera.snap`, `camera.clip`	Cámara (+ micrófono para audio de clip)	Cámara (+ micrófono para audio de clip)	Cámara (+ micrófono para audio de 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`
`location.get`	Mientras se usa o siempre (depende del modo)	Ubicación en primer plano/segundo plano basada en el modo	Permiso de ubicación	`LOCATION_PERMISSION_REQUIRED`
`system.run`	n/a (ruta del host del nodo)	n/a (ruta de host del nodo)	Aprobaciones de ejecución requeridas	`SYSTEM_RUN_DENIED`

Emparejamiento frente a aprobaciones

Estas son diferentes puertas:

Emparejamiento de dispositivos: ¿puede este nodo conectarse a la puerta de enlace?
Política de comandos del nodo de puerta de enlace: ¿está permitido el ID de comando RPC por gateway.nodes.allowCommands / denyCommands y los valores predeterminados de la plataforma?
Aprobaciones de ejecución: ¿puede este nodo ejecutar un comando de shell específico localmente?

Verificaciones rápidas:

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

Si falta el emparejamiento, apruebe primero el dispositivo del nodo. Si a nodes describe le falta un comando, verifique la política de comandos del nodo de puerta de enlace y si el nodo declaró ese comando al conectarse. Si el emparejamiento es correcto pero system.run falla, corrija las aprobaciones/listas blancas de ejecución en ese nodo.

El emparejamiento de nodos es una puerta de identidad/confianza, no una superficie 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 de la puerta de enlace.

Para ejecuciones de host=node respaldadas por aprobación, la puerta de enlace también vincula la ejecución al systemRunPlan canónico preparado. Si un llamador posterior muta el comando/directorio de trabajo o los metadatos de la sesión antes de que se reenvíe la ejecución aprobada, la puerta de enlace rechaza la ejecución como una discrepancia de aprobación en lugar de confiar en la carga útil editada.

Códigos de error comunes de nodos

NODE_BACKGROUND_UNAVAILABLE → la aplicación está en segundo plano; póngala en primer plano.
CAMERA_DISABLED → el interruptor de la cámara está deshabilitado en la configuración del nodo.
*_PERMISSION_REQUIRED → falta o se denegó el permiso del SO.
LOCATION_DISABLED → el modo de ubicación está desactivado.
LOCATION_PERMISSION_REQUIRED → no se otorgó el modo de ubicación solicitado.
LOCATION_BACKGROUND_UNAVAILABLE → la aplicación está en segundo plano pero solo existe el permiso “Mientras se usa”.
SYSTEM_RUN_DENIED: approval required → la solicitud de ejecución necesita aprobación explícita.
SYSTEM_RUN_DENIED: allowlist miss → comando bloqueado por el modo de lista permitida. En los hosts de nodos de Windows, los formularios de contenedor de shell como cmd.exe /c ... se tratan como fallos de la lista permitida en el modo de lista permitida a menos que se aprueben mediante el flujo de solicitud (ask flow).

Bucle de recuperación rápida

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

Si sigue atascado:

Volver a aprobar el emparejamiento del dispositivo.
Volver a abrir la aplicación del nodo (en primer plano).
Volver a otorgar permisos del SO.
Recrear/ajustar la política de aprobación de ejecución.