Nodos

Un nodo es un dispositivo complementario (macOS/iOS/Android/sin cabeza) que se conecta al WebSocket de la puerta de enlace (Gateway) (mismo puerto que los operadores) con role: "node" y expone una superficie de comandos (por ejemplo, canvas.*, camera.*, device.*, notifications.*, system.*) a través de node.invoke. Detalles del protocolo: Gateway protocol.

Transporte heredado: Bridge protocol (TCP JSONL; histórico solo para los nodos actuales).

macOS también puede ejecutarse en modo nodo: la aplicación de la barra de menú se conecta al servidor WS de la Gateway y expone sus comandos locales de canvas/cámara como un nodo (así, openclaw nodes … funciona contra este Mac). En el modo de puerta de enlace remota, la automatización del navegador es manejada por el host de nodo CLI (openclaw node run o el servicio de nodo instalado), no por el nodo de la aplicación nativa.

Notas:

• Los nodos son periféricos, no gateways. No ejecutan el servicio de puerta de enlace.
• Los mensajes de Telegram/WhatsApp/etc. llegan a la gateway, no a los nodos.
• Manual de resolución de problemas: /nodes/troubleshooting

Emparejamiento + estado

Los nodos WS utilizan el emparejamiento de dispositivos. Los nodos presentan una identidad de dispositivo durante connect; la Gateway crea una solicitud de emparejamiento de dispositivo para role: node. Apruebe a través de la CLI de dispositivos (o 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 nodo reintenta con detalles de autenticación cambiados (rol/alcaves/clave pública), la solicitud pendiente anterior es reemplazada y se crea un nuevo requestId. Vuelva a ejecutar openclaw devices list antes de aprobar.

Notas:

• nodes status marca un nodo como emparejado cuando su rol de emparejamiento de dispositivos incluye node.
• El registro de emparejamiento de dispositivos es el contrato duradero de rol aprobado. La rotación de tokens permanece dentro de ese contrato; no puede actualizar un nodo emparejado a un rol diferente que la aprobación de emparejamiento nunca otorgó.
• node.pair.* (CLI: openclaw nodes pending/approve/reject/remove/rename) es un almacén de emparejamiento de nodos separado propiedad de la gateway; no limita el saludo (handshake) WS connect.
• openclaw nodes remove --node <id|name|ip> elimina las entradas obsoletas de ese almacén de emparejamiento de nodos propiedad separada de la puerta de enlace.
• El alcance de la aprobación sigue los comandos declarados de la solicitud pendiente:
  • solicitud sin comandos: operator.pairing
  • comandos de nodo sin ejecución: operator.pairing + operator.write
  • system.run / system.run.prepare / system.which: operator.pairing + operator.admin

Host de nodo remoto (system.run)

Use un host de nodo cuando su puerta de enlace se ejecute en una máquina y desee que los comandos se ejecuten en otra. El modelo aún habla con la puerta de enlace; la puerta de enlace reenvía las llamadas exec al host de nodo cuando se selecciona host=node.

Qué se ejecuta dónde

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

Nota sobre aprobaciones:

• Las ejecuciones de nodos respaldadas por aprobaciones vinculan el contexto exacto de la solicitud.
• Para ejecuciones directas de archivos de shell/runtime, OpenClaw también vincula, con el mejor esfuerzo posible, un operando de archivo local concreto y niega la ejecución si ese archivo cambia antes de la ejecución.
• Si OpenClaw no puede identificar exactamente un archivo local concreto para un comando de intérprete/runtime, la ejecución respaldada por aprobación se deniega en lugar de fingir una cobertura completa del runtime. Utilice sandboxing, hosts separados o una lista de permitidos (allowlist) explícita y confiable/flujo de trabajo completo para semánticas de intérprete más amplias.

Iniciar un host de nodo (primer plano)

En la máquina del nodo:

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

Gateway remoto a través de túnel SSH (vinculación de loopback)

Si la puerta de enlace se enlaza al loopback (gateway.bind=loopback, valor predeterminado en modo local), los hosts de nodos remotos no pueden conectarse directamente. Cree un túnel SSH y apunte el host del nodo al extremo local del túnel.

Ejemplo (host del nodo -> 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 alternativa de configuración es gateway.auth.token / gateway.auth.password.
• En modo local, el host del nodo ignora intencionalmente 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 se configuran SecretRefs gateway.auth.* locales activos pero no resueltos, la autenticación del host del nodo falla de forma cerrada.
• La resolución de autenticación del host del nodo solo respeta las variables de entorno OPENCLAW_GATEWAY_*.

Iniciar un host de nodo (servicio)

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

Emparejar + nombrar

En el host del gateway:

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

Si el nodo reintentas con detalles de autenticación cambiados, vuelva a ejecutar openclaw devices list y apruebe el requestId actual.

Opciones de nomenclatura:

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

Permitir los comandos (Allowlist)

Las aprobaciones de ejecución son por host de nodo. Agregue entradas a la lista de permitidos (allowlist) 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 nodo en ~/.openclaw/exec-approvals.json.

Dirigir exec al nodo

Configurar valores predeterminados (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 exec con host=node se ejecuta en el host del nodo (sujeto a la lista de permitidos/aprobaciones del nodo).

host=auto no elegirá implícitamente el nodo por sí solo, pero se permite una solicitud explícita host=node por llamada desde auto. Si desea que la ejecución en el nodo sea el valor predeterminado de la sesión, establezca tools.exec.host=node o /exec host=node ... explícitamente.

Relacionado:

• Node host CLI
• Exec tool
• Exec approvals

Invocar comandos

De bajo nivel (RPC sin procesar):

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

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

Política de comandos

Los comandos de nodo deben pasar dos filtros antes de poder invocarse:

1. El nodo debe declarar el comando en su lista WebSocket connect.commands.
2. La política de plataforma de la puerta de enlace debe permitir el comando declarado.

Los nodos complementarios de Windows y macOS permiten comandos declarados seguros como canvas.*, camera.list, location.get y screen.snapshot de forma predeterminada. Los nodos de confianza que anuncian la capacidad talk o declaran comandos talk.* también permiten comandos declarados de pulsar para hablar (talk.ptt.start, talk.ptt.stop, talk.ptt.cancel, talk.ptt.once) de forma predeterminada, independientemente de la etiqueta de la plataforma. Los comandos peligrosos o con alta carga de privacidad, como camera.snap, camera.clip y screen.record, todavía requieren una aceptación explícita con gateway.nodes.allowCommands. gateway.nodes.denyCommands siempre tiene prioridad sobre los valores predeterminados y las entradas adicionales de la lista blanca.

Los comandos de nodo propiedad del complemento pueden añadir una política de invocación de nodo de Gateway. Dicha política se ejecuta después de la verificación de la lista blanca y antes de reenviar al nodo, por lo que node.invoke sin procesar, los auxiliares de CLI y las herramientas de agente dedicadas comparten el mismo límite de permisos del complemento. Los comandos de nodo de complemento peligrosos todavía requieren una aceptación explícita de gateway.nodes.allowCommands.

Después de que un nodo cambie su lista de comandos declarados, rechace el emparejamiento del dispositivo antiguo y apruebe la nueva solicitud para que la puerta de enlace almacene la instantánea de comandos actualizada.

Capturas de pantalla (instantáneas del lienzo)

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

Auxiliar de CLI (escribe en un archivo temporal e imprime la ruta guardada):

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 URL o rutas de archivos locales (--target), además de --x/--y/--width/--height opcional 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 (se rechaza v0.9/createSurface).

Fotos + vídeos (cámara del nodo)

Fotos (jpg):

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

Clips de video (mp4):

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

Notas:

• El nodo debe estar en primer plano para canvas.* y camera.* (las llamadas en segundo plano devuelven NODE_BACKGROUND_UNAVAILABLE).
• La duración del clip está limitada (actualmente <= 60s) para evitar cargas útiles base64 demasiado grandes.
• Android solicitará permisos CAMERA/RECORD_AUDIO cuando sea posible; los permisos denegados fallarán con *_PERMISSION_REQUIRED.

Grabaciones de pantalla (nodos)

Los nodos compatibles exponen screen.record (mp4). 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 de la plataforma del nodo.
• Las grabaciones de pantalla están limitadas a <= 60s.
• --no-audio deshabilita la captura del micrófono en plataformas compatibles.
• Use --screen <index> para seleccionar una pantalla cuando hay varias pantallas disponibles.

Ubicación (nodos)

Los nodos exponen location.get cuando la ubicación está habilitada en la configuración.

Auxiliar de 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.
• “Siempre” requiere permiso del sistema; la obtención en segundo plano es de mejor esfuerzo.
• La respuesta incluye latitud/longitud, precisión (metros) y marca de tiempo.

SMS (nodos Android)

Los nodos Android pueden exponer sms.send cuando el usuario otorga el permiso de SMS y el dispositivo soporta telefonía.

Invocación de bajo nivel:

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

Notas:

• El prompt de permiso debe aceptarse en el dispositivo Android antes de que se anuncie la capacidad.
• Los dispositivos solo con Wi-Fi sin telefonía no anunciarán sms.send.

Dispositivo Android + comandos de datos personales

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

Familias disponibles:

• device.status, device.info, device.permissions, device.health
• device.apps cuando el uso compartido de aplicaciones instaladas está habilitado en la configuración de Android
• notifications.list, notifications.actions
• photos.latest
• contacts.search, contacts.add
• calendar.events, calendar.add
• callLog.search
• sms.search
• motion.activity, motion.pedometer

Ejemplos de invocaciones:

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

Notas:

• device.apps es opcional y devuelve las aplicaciones visibles en el lanzador de forma predeterminada.
• Los comandos de movimiento están restringidos por capacidades según los sensores disponibles.

Comandos del sistema (host de nodo / nodo mac)

El nodo de macOS expone system.run, system.notify y system.execApprovals.get/set. El host de nodo sin cabeza 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/código de salida en la carga útil (payload).
• La ejecución de Shell ahora se realiza a través de la herramienta exec con host=node; nodes sigue siendo la superficie de RPC directa para comandos de nodo explícitos.
• nodes invoke no expone system.run ni system.run.prepare; estos permanecen solo en la ruta de ejecución.
• La ruta de ejecución prepara un systemRunPlan canónico antes de la aprobación. Una vez que se concede una aprobación, el puerta de enlace reenvía ese plan almacenado, no ningún campo de comando/cwd/sesión editado posteriormente por el solicitante.
• system.notify respeta el estado del permiso de notificaciones en la aplicación de macOS.
• Los metadatos de nodo platform / deviceFamily no reconocidos utilizan una lista de permitidos predeterminada conservadora que excluye system.run y system.which. Si intencionalmente necesita esos comandos para una plataforma desconocida, agréguelos explícitamente a través de gateway.nodes.allowCommands.
• system.run admite --cwd, --env KEY=VAL, --command-timeout y --needs-screen-recording.
• Para los contenedores de shell (bash|sh|zsh ... -c/-lc), los valores --env con ámbito de solicitud se reducen a una lista de permitidos explícita (TERM, LANG, LC_*, COLORTERM, NO_COLOR, FORCE_COLOR).
• Para las decisiones de permitir siempre en el modo de lista de permitidos, los contenedores de envío conocidos (env, nice, nohup, stdbuf, timeout) persisten las rutas ejecutables internas en lugar de las rutas del contenedor. Si el desempaquetamiento no es seguro, no se persiste automáticamente ninguna entrada en la lista de permitidos.
• En los hosts de nodo de Windows en modo de lista de permitidos, las ejecuciones de contenedor de shell a través de cmd.exe /c requieren aprobación (la entrada en la lista de permitidos por sí sola no permite automáticamente la forma del contenedor).
• system.notify admite --priority <passive|active|timeSensitive> y --delivery <system|overlay|auto>.
• Los hosts de nodos ignoran las anulaciones de PATH y eliminan claves de inicio/shell peligrosas (DYLD_*, LD_*, NODE_OPTIONS, NODE_REDIRECT_WARNINGS, NODE_REPL_EXTERNAL_MODULE, NODE_REPL_HISTORY, NODE_V8_COVERAGE, PYTHON*, PERL*, RUBYOPT, SHELLOPTS, PS4). Si necesita entradas PATH adicionales, configure el entorno del servicio de host de nodos (o instale las herramientas en ubicaciones estándar) en lugar de pasar PATH a través de --env.
• En el modo de nodo macOS, system.run está limitado por las aprobaciones de ejecución en la aplicación macOS (Configuración → Aprobaciones de ejecución). Ask/allowlist/full se comportan igual que el host de nodos headless; las solicitudes denegadas devuelven SYSTEM_RUN_DENIED.
• En el host de nodos headless, system.run está limitado por aprobaciones de ejecución (~/.openclaw/exec-approvals.json).

Vinculación de nodo de ejecución

Cuando hay varios nodos disponibles, puede vincular la ejecución a un nodo específico. Esto establece el nodo predeterminado para exec host=node (y se puede anular por agente).

Predeterminado global:

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

Anulación por agente:

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

Desestablecer 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 permissions en node.list / node.describe, clave por nombre de permiso (ej. screenRecording, accessibility) con valores booleanos (true = concedido).

Host de nodos headless (multiplataforma)

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

Inícielo:

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

Notas:

• Aún se requiere el emparejamiento (el Gateway mostrará un mensaje de emparejamiento de dispositivo).
• El host de nodos almacena su id de nodo, token, nombre para mostrar e información de conexión del gateway en ~/.openclaw/node.json.
• Las aprobaciones de ejecución se aplican localmente a través de ~/.openclaw/exec-approvals.json (ver Exec approvals).
• En macOS, el host de nodo headless ejecuta system.run localmente de forma predeterminada. Establezca OPENCLAW_NODE_EXEC_HOST=app para enrutar system.run a través del host de ejecución de la aplicación complementaria; añada OPENCLAW_NODE_EXEC_FALLBACK=0 para requerir el host de la aplicación y fallar con cierre si no está disponible.
• Añada --tls / --tls-fingerprint cuando el WS del Gateway use TLS.

Modo de nodo Mac

• La aplicación de la barra de menús de macOS se conecta al servidor WS del Gateway como un nodo (por lo que openclaw nodes … funciona contra este Mac).
• En modo remoto, la aplicación abre un túnel SSH para el puerto del Gateway y se conecta a localhost.