Soluciona errores de nodos en OpenClaw: Guía rápida

Es frustrante cuando un nodo aparece en el status pero se niega a ejecutar comandos. A veces los permisos o la configuración del Gateway se interponen en el camino y no sabes por dónde empezar a depurar.

Para que no pierdas tiempo revisando logs sin rumbo, aquí tienes los pasos directos para diagnosticar y arreglar problemas en tus nodos de forma efectiva.

Solución de problemas de nodos

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

Escalera de comandos

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

Luego ejecuta comprobaciones 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 llamando.
Las aprobaciones de ejecución (exec approvals) muestran el modo o la allowlist esperada.

Requisitos de primer plano

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

Comprobació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, pon la app del nodo en primer plano e inténtalo de nuevo.

Matriz de permisos

Capacidad	iOS	Android	macOS node app	Código de fallo típico
`camera.snap`, `camera.clip`	Camera (+ mic para audio de clip)	Camera (+ mic para audio de clip)	Camera (+ mic para audio de clip)	`*_PERMISSION_REQUIRED`
`screen.record`	Screen Recording (+ mic opcional)	Screen capture prompt (+ mic opcional)	Screen Recording	`*_PERMISSION_REQUIRED`
`location.get`	While Using o Always (depende del modo)	Foreground/Background location según el modo	Permiso de Location	`LOCATION_PERMISSION_REQUIRED`
`system.run`	n/a (ruta del host del nodo)	n/a (ruta del host del nodo)	Requiere exec approvals	`SYSTEM_RUN_DENIED`

Vinculación frente a aprobaciones

Son puertas de acceso diferentes:

Device pairing: ¿puede este nodo conectarse al Gateway?
Gateway node command policy: ¿el comando RPC está permitido por gateway.nodes.allowCommands / denyCommands y los valores por defecto de la plataforma?
Exec approvals: ¿puede este nodo ejecutar un comando de shell específico localmente?

Comprobaciones 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 (pairing), aprueba primero el dispositivo del nodo. Si a nodes describe le falta un comando, revisa la política de comandos del Gateway y si el nodo declaró ese comando al conectarse. Si la vinculación está bien pero system.run falla, arregla las aprobaciones de ejecución o la allowlist en ese nodo.

La vinculación del nodo es una puerta de identidad y confianza, no una superficie de aprobación por comando. Para system.run, la política por nodo vive en el archivo de aprobaciones de ejecución de ese nodo (openclaw approvals get --node ...), no en el registro de vinculación del Gateway.

Códigos de error comunes de los nodos

NODE_BACKGROUND_UNAVAILABLE → la app está en segundo plano; ponla en primer plano.
CAMERA_DISABLED → el interruptor de la cámara está desactivado en los ajustes del nodo.
*_PERMISSION_REQUIRED → falta el permiso del OS o ha sido denegado.
LOCATION_DISABLED → el modo de ubicación está apagado.
LOCATION_PERMISSION_REQUIRED → el modo de ubicación solicitado no ha sido otorgado.
LOCATION_BACKGROUND_UNAVAILABLE → la app está en segundo plano pero solo tiene permiso “While Using”.
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 allowlist. En hosts de nodos Windows, las formas de shell-wrapper como cmd.exe /c ... se tratan como fallos de allowlist en modo allowlist a menos que se aprueben mediante el flujo de consulta (ask flow).

Ciclo de recuperación rápida

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

Si sigues atascado:

Vuelve a aprobar la vinculación del dispositivo.
Vuelve a abrir la app del nodo (primer plano).
Vuelve a otorgar los permisos del OS.
Recrea o ajusta la política de aprobación de ejecución.

Siguientes pasos

AI Setup Assistant

OpenClaw Expert

Sigues atascado?

Si esta pagina no resolvio tu caso, pregunta a OpenClaw Expert para pasos concretos.