Resolución de problemas de nodos

Usa esta página cuando un nodo es visible en el estado pero las herramientas del nodo fallan.

Escalera de comandos

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

Luego ejecuta verificaciones específicas del nodo:

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

Señales de salud:

El nodo está conectado y vinculado para el rol node.
nodes describe incluye la capacidad que estás invocando.
Las aprobaciones exec muestran el modo/allowlist esperado.

Requisitos de primer plano

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

Verificación rápida y solución:

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

Si ves NODE_BACKGROUND_UNAVAILABLE, lleva la app del nodo a primer plano y reintenta.

Matriz de permisos

Capacidad	iOS	Android	App nodo macOS	Código de fallo típico
`camera.snap`, `camera.clip`	Cámara (+ mic para clip de audio)	Cámara (+ mic para clip de audio)	Cámara (+ mic para clip de audio)	`*_PERMISSION_REQUIRED`
`screen.record`	Grabación de pantalla (+ mic opcional)	Aviso de captura de pantalla (+ mic opcional)	Grabación de pantalla	`*_PERMISSION_REQUIRED`
`location.get`	Mientras se usa o Siempre (según modo)	Ubicación primer plano/segundo plano según modo	Permiso de ubicación	`LOCATION_PERMISSION_REQUIRED`
`system.run`	n/a (ruta de host de nodo)	n/a (ruta de host de nodo)	Aprobaciones exec requeridas	`SYSTEM_RUN_DENIED`

Vinculación versus aprobaciones

Son puertas diferentes:

Vinculación de dispositivo: ¿puede este nodo conectarse al gateway?
Aprobaciones exec: ¿puede este nodo ejecutar un comando shell específico?

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 la vinculación, aprueba primero el dispositivo del nodo. Si la vinculación está bien pero system.run falla, corrige las aprobaciones exec/allowlist.

Códigos de error comunes de nodos

NODE_BACKGROUND_UNAVAILABLE → la app está en segundo plano; llévala a primer plano.
CAMERA_DISABLED → el toggle de cámara está desactivado en los ajustes del nodo.
*_PERMISSION_REQUIRED → permiso del SO faltante/denegado.
LOCATION_DISABLED → el modo de ubicación está desactivado.
LOCATION_PERMISSION_REQUIRED → el modo de ubicación solicitado no está concedido.
LOCATION_BACKGROUND_UNAVAILABLE → la app está en segundo plano pero solo existe permiso “Mientras se usa”.
SYSTEM_RUN_DENIED: approval required → la solicitud exec necesita aprobación explícita.
SYSTEM_RUN_DENIED: allowlist miss → comando bloqueado por modo allowlist. En hosts de nodo Windows, las formas wrapper de shell como cmd.exe /c ... se tratan como fallos de allowlist en modo allowlist a menos que se aprueben mediante el flujo ask.

Bucle de recuperación rápida

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

Si sigues atascado:

Re-aprueba la vinculación del dispositivo.
Re-abre la app del nodo (primer plano).
Re-concede permisos del SO.
Recrea/ajusta la política de aprobación exec.

Relacionado: