Configura nodos OpenClaw: Guía de conexión y emparejamiento

Emparejamiento y estado

Los nodes de WS usan el emparejamiento de dispositivos. Los nodes presentan una identidad de dispositivo durante el connect; el Gateway crea una solicitud de emparejamiento de dispositivo para role: node. Apruébala a través de la CLI de dispositivos (o la interfaz de usuario).

CLI rápida:

openclaw devices list
openclaw devices approve <requestId>
openclaw devices reject <requestId>
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>

Si un node reintenta la conexión con detalles de autenticación distintos (role/scopes/public key), la solicitud pendiente anterior se reemplaza y se crea un nuevo requestId. Ejecuta de nuevo openclaw devices list antes de aprobar.

Notas:

• nodes status marca un node como paired cuando su rol de emparejamiento de dispositivo incluye node.
• node.pair.* (CLI: openclaw nodes pending/approve/reject) es un almacén de emparejamiento de nodes independiente propiedad del Gateway; no bloquea el handshake de connect de WS.

Host de node remoto (system.run)

Usa un host de node cuando tu Gateway se ejecute en una máquina y quieras que los comandos se ejecuten en otra distinta. El modelo sigue comunicándose con el gateway; el Gateway reenvía las llamadas exec al host de node cuando se selecciona host=node.

Qué se ejecuta en cada lugar

• Host del Gateway: recibe mensajes, ejecuta el modelo y enruta las llamadas a herramientas.
• Host del node: ejecuta system.run/system.which en la máquina del node.
• Aprobaciones: se aplican en el host del node mediante ~/.openclaw/exec-approvals.json.

Nota sobre aprobaciones:

• Las ejecuciones de nodes respaldadas por aprobación vinculan el contexto exacto de la solicitud.
• Para ejecuciones directas de archivos de shell o runtime, OpenClaw también intenta vincular un operando de archivo local concreto y deniega la ejecución si ese archivo cambia antes de ejecutarse.
• Si OpenClaw no puede identificar exactamente un archivo local concreto para un comando de intérprete o runtime, la ejecución respaldada por aprobación se deniega en lugar de simular una cobertura completa del runtime. Usa sandboxing, hosts separados o una lista de permitidos confiable para semánticas de intérprete más amplias.

Iniciar un host de node (primer plano)

En la máquina del node:

openclaw node run --host <gateway-host> --port 18789 --display-name "Build Node"

Gateway remoto mediante túnel SSH (loopback bind)

Si el Gateway se vincula a loopback (gateway.bind=loopback, por defecto en modo local), los hosts de nodes remotos no pueden conectarse directamente. Crea un túnel SSH y apunta el host del node al extremo local del túnel.

Ejemplo (host del node -> host del gateway):

# Terminal A (keep running): forward local 18790 -> gateway 127.0.0.1:18789
ssh -N -L 18790:127.0.0.1:18789 user@gateway-host

# Terminal B: export the gateway token and connect through the tunnel
export OPENCLAW_GATEWAY_TOKEN="<gateway-token>"
openclaw node run --host 127.0.0.1 --port 18790 --display-name "Build Node"

Notas:

• openclaw node run admite autenticación por token o contraseña.
• Se prefieren las variables de entorno: OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD.
• La configuración de respaldo es gateway.auth.token / gateway.auth.password.
• En modo local, el host del node ignora intencionadamente gateway.remote.token / gateway.remote.password.
• En modo remoto, gateway.remote.token / gateway.remote.password son elegibles según las reglas de precedencia remota.
• Si las SecretRefs activas de gateway.auth.* locales están configuradas pero no resueltas, la autenticación del host del node falla por seguridad.
• La resolución de autenticación del host del node solo respeta las variables de entorno OPENCLAW_GATEWAY_*.

Iniciar un host de node (servicio)

openclaw node install --host <gateway-host> --port 18789 --display-name "Build Node"
openclaw node restart

Emparejar y nombrar

En el host del gateway:

openclaw devices list
openclaw devices approve <requestId>
openclaw nodes status

Si el node reintenta con detalles de autenticación cambiados, vuelve a ejecutar openclaw devices list y aprueba el requestId actual.

Opciones de nombre:

• --display-name en openclaw node run / openclaw node install (persiste en ~/.openclaw/node.json en el node).
• openclaw nodes rename --node <id|name|ip> --name "Build Node" (sobrescritura desde el gateway).

Lista de permitidos para los comandos

Las aprobaciones de ejecución son por host de node. Añade entradas a la lista de permitidos desde el gateway:

openclaw approvals allowlist add --node <id|name|ip> "/usr/bin/uname"
openclaw approvals allowlist add --node <id|name|ip> "/usr/bin/sw_vers"

Las aprobaciones residen en el host del node en ~/.openclaw/exec-approvals.json.

Apuntar exec al node

Configura los valores por defecto (configuración del gateway):

openclaw config set tools.exec.host node
openclaw config set tools.exec.security allowlist
openclaw config set tools.exec.node "<id-or-name>"

O por sesión:

/exec host=node security=allowlist node=<id-or-name>

Una vez configurado, cualquier llamada a exec con host=node se ejecuta en el host del node (sujeto a la lista de permitidos y aprobaciones del node).

Relacionado:

• CLI del host de node
• Herramienta exec
• Aprobaciones de exec

Invocar comandos

Nivel bajo (RPC sin procesar):

openclaw nodes invoke --node <idOrNameOrIp> --command canvas.eval --params '{"javaScript":"location.href"}'

Existen asistentes de nivel superior para los flujos de trabajo comunes de “entregar un adjunto MEDIA al agente”.

Capturas de pantalla (canvas snapshots)

Si el node está mostrando el Canvas (WebView), canvas.snapshot devuelve { format, base64 }.

Asistente de CLI (escribe en un archivo temporal e imprime MEDIA:<path>):

openclaw nodes canvas snapshot --node <idOrNameOrIp> --format png
openclaw nodes canvas snapshot --node <idOrNameOrIp> --format jpg --max-width 1200 --quality 0.9

Controles del Canvas

openclaw nodes canvas present --node <idOrNameOrIp> --target https://example.com
openclaw nodes canvas hide --node <idOrNameOrIp>
openclaw nodes canvas navigate https://example.com --node <idOrNameOrIp>
openclaw nodes canvas eval --node <idOrNameOrIp> --js "document.title"

Notas:

• canvas present acepta URLs o rutas de archivos locales (--target), además de --x/--y/--width/--height opcionales para el posicionamiento.
• canvas eval acepta JS en línea (--js) o un argumento posicional.

A2UI (Canvas)

openclaw nodes canvas a2ui push --node <idOrNameOrIp> --text "Hello"
openclaw nodes canvas a2ui push --node <idOrNameOrIp> --jsonl ./payload.jsonl
openclaw nodes canvas a2ui reset --node <idOrNameOrIp>

Notas:

• Solo se admite A2UI v0.8 JSONL (v0.9/createSurface se rechaza).

Fotos y videos (cámara del node)

Capturar fotos (jpg) con tus nodes es muy directo:

openclaw nodes camera list --node <idOrNameOrIp>
openclaw nodes camera snap --node <idOrNameOrIp>            # default: both facings (2 MEDIA lines)
openclaw nodes camera snap --node <idOrNameOrIp> --facing front

También puedes grabar clips de video (mp4):

openclaw nodes camera clip --node <idOrNameOrIp> --duration 10s
openclaw nodes camera clip --node <idOrNameOrIp> --duration 3000 --no-audio

Notas:

• El node debe estar en primer plano (foregrounded) para usar canvas.* y camera.*; si las llamadas se hacen en segundo plano, el sistema devuelve NODE_BACKGROUND_UNAVAILABLE.
• La duración de los clips está limitada (actualmente <= 60s) para evitar que los payloads en base64 sean demasiado pesados.

Grabaciones de pantalla (nodes)

Los nodes compatibles exponen el comando screen.record (mp4). Aquí tienes un ejemplo:

openclaw nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10
openclaw nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10 --no-audio

Notas:

• La disponibilidad de screen.record depende totalmente de la plataforma del node.
• Las grabaciones de pantalla están limitadas a un máximo de 60 segundos.
• El flag --no-audio permite desactivar la captura del micrófono en las plataformas que lo soportan.
• Si tienes varias pantallas disponibles, usa --screen <index> para seleccionar la que prefieras.

Ubicación (nodes)

Tus nodes exponen location.get siempre que la ubicación esté activada en los ajustes del dispositivo.

Usa este helper de la CLI:

openclaw nodes location get --node <idOrNameOrIp>
openclaw nodes location get --node <idOrNameOrIp> --accuracy precise --max-age 15000 --location-timeout 10000

Notas:

• La ubicación está desactivada por defecto y el permiso “Siempre” requiere autorización del sistema.
• La respuesta que recibes incluye latitud, longitud, precisión (en metros) y el timestamp correspondiente.

SMS (nodes de Android)

Los nodes de Android pueden exponer sms.send si otorgas el permiso de SMS y el dispositivo cuenta con soporte de telefonía.

Invocación de bajo nivel:

openclaw nodes invoke --node <idOrNameOrIp> --command sms.send --params '{"to":"+15555550123","message":"Hello from OpenClaw"}'

Notas:

• Es necesario aceptar el aviso de permiso en el dispositivo Android antes de que la capacidad aparezca como disponible.
• Los dispositivos que solo funcionan con Wi-Fi y no tienen hardware de telefonía no mostrarán el comando sms.send.

AI Setup Assistant

Comandos de dispositivos Android y datos personales

Los nodos de Android pueden anunciar familias de comandos adicionales cuando activas las capacidades correspondientes.

Familias disponibles:

• device.status, device.info, device.permissions, device.health
• notifications.list, notifications.actions
• photos.latest
• contacts.search, contacts.add
• calendar.events, calendar.add
• callLog.search
• sms.search
• motion.activity, motion.pedometer

Ejemplos de ejecución:

openclaw nodes invoke --node <idOrNameOrIp> --command device.status --params '{}'
openclaw nodes invoke --node <idOrNameOrIp> --command notifications.list --params '{}'
openclaw nodes invoke --node <idOrNameOrIp> --command photos.latest --params '{"limit":1}'

Notas:

• Los comandos de movimiento están limitados por los sensores disponibles en el dispositivo.

Comandos del sistema (node host / mac node)

El nodo de macOS expone system.run, system.notify y system.execApprovals.get/set. El node host headless expone system.run, system.which y system.execApprovals.get/set.

Ejemplos:

openclaw nodes notify --node <idOrNameOrIp> --title "Ping" --body "Gateway ready"
openclaw nodes invoke --node <idOrNameOrIp> --command system.which --params '{"name":"git"}'

Notas:

• system.run devuelve stdout/stderr/exit code en el payload.
• La ejecución de shell ahora se realiza a través de la herramienta exec con host=node; nodes se mantiene como la superficie de RPC directa para comandos explícitos del nodo.
• nodes invoke no expone system.run ni system.run.prepare; esos comandos permanecen exclusivamente en la ruta de exec.
• system.notify respeta el estado de los permisos de notificación en la aplicación de macOS.
• Los metadatos de platform / deviceFamily no reconocidos utilizan una allowlist predeterminada conservadora que excluye system.run y system.which. Si necesitas esos comandos para una plataforma desconocida, añádelos explícitamente mediante gateway.nodes.allowCommands.
• system.run admite --cwd, --env KEY=VAL, --command-timeout y --needs-screen-recording.
• Para wrappers de shell (bash|sh|zsh ... -c/-lc), los valores de --env con alcance de solicitud se reducen a una allowlist explícita (TERM, LANG, LC_*, COLORTERM, NO_COLOR, FORCE_COLOR).
• Para decisiones de “permitir siempre” en modo allowlist, los wrappers de despacho conocidos (env, nice, nohup, stdbuf, timeout) mantienen las rutas del ejecutable interno en lugar de las rutas del wrapper. Si el desempaquetado no es seguro, no se guarda ninguna entrada en la allowlist automáticamente.
• En node hosts de Windows en modo allowlist, las ejecuciones de shell-wrapper a través de cmd.exe /c requieren aprobación (la entrada en la allowlist por sí sola no autoriza automáticamente la forma del wrapper).
• system.notify admite --priority <passive|active|timeSensitive> y --delivery <system|overlay|auto>.
• Los node hosts ignoran los cambios en PATH y eliminan claves peligrosas de inicio o shell (DYLD_*, LD_*, NODE_OPTIONS, PYTHON*, PERL*, RUBYOPT, SHELLOPTS, PS4). Si necesitas entradas de PATH adicionales, te recomiendo configurar el entorno del servicio del node host o instalar las herramientas en ubicaciones estándar en lugar de pasar PATH mediante --env.
• En el modo de nodo de macOS, system.run está regulado por las aprobaciones de ejecución en la aplicación de macOS (Settings → Exec approvals). Las opciones Ask/allowlist/full se comportan igual que en el node host headless; las solicitudes denegadas devuelven SYSTEM_RUN_DENIED.
• En el node host headless, system.run está regulado por las aprobaciones de ejecución en ~/.openclaw/exec-approvals.json.

Vinculación de nodos de ejecución

Cuando tienes varios nodos disponibles, puedes vincular exec a un nodo específico. Esto establece el nodo por defecto para exec host=node, aunque puedes sobrescribirlo de forma individual para cada agente.

Configuración global por defecto:

openclaw config set tools.exec.node "node-id-or-name"

Sobrescribir por agente:

openclaw config get agents.list
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"

Eliminar la configuración para permitir cualquier nodo:

openclaw config unset tools.exec.node
openclaw config unset agents.list[0].tools.exec.node

Mapa de permisos

Los nodos pueden incluir un mapa de permissions en node.list / node.describe. Este mapa se organiza por el nombre del permiso (por ejemplo, screenRecording o accessibility) y utiliza valores booleanos donde true significa que el permiso ha sido concedido.

Host de node headless (multiplataforma)

OpenClaw puede ejecutar un host de node headless (sin interfaz gráfica) que se conecta al WebSocket del Gateway y expone system.run / system.which. Esto te resultará útil en Linux/Windows o para ejecutar un node mínimo junto a un servidor.

Inícialo así:

openclaw node run --host <gateway-host> --port 18789

Notas:

• El emparejamiento sigue siendo necesario (el Gateway mostrará un aviso de pairing del dispositivo).
• El host del node guarda su node id, token, nombre visible e información de conexión al gateway en ~/.openclaw/node.json.
• Las aprobaciones de ejecución se aplican localmente mediante ~/.openclaw/exec-approvals.json (consulta Exec approvals).
• En macOS, el host del node headless ejecuta system.run de forma local por defecto. Configura OPENCLAW_NODE_EXEC_HOST=app para dirigir system.run a través del host de ejecución de la companion app; añade OPENCLAW_NODE_EXEC_FALLBACK=0 para exigir el host de la app y fallar si no está disponible.
• Añade --tls / --tls-fingerprint cuando el WS del Gateway use TLS.

Modo de node para Mac

• La app de la barra de menú de macOS se conecta al servidor WS del Gateway como un node (así que openclaw nodes … funciona contra este Mac).
• En el modo remoto, la app abre un túnel SSH para el puerto del Gateway y se conecta a localhost.