Nodos

Un nodo es un dispositivo compañero (macOS/iOS/Android/headless) que conecta al WebSocket del Gateway (mismo puerto que operadores) con role: "node" y expone una superficie de comandos (ej. canvas.*, camera.*, system.*) vía node.invoke. Detalles de protocolo: Protocolo del Gateway.

Transporte legacy: Protocolo Bridge (TCP JSONL; deprecado/removido para nodos actuales).

macOS también puede correr en modo nodo: la app de barra de menú conecta al servidor WS del Gateway y expone sus comandos locales de canvas/cámara como un nodo (así openclaw nodes … funciona contra esta Mac).

Notas:

- Los nodos son periféricos, no gateways. No ejecutan servicio de gateway.

- Mensajes de Telegram/WhatsApp/etc. llegan al gateway, no a los nodos.

Los nodos WS usan emparejamiento de dispositivo. Los nodos presentan una identidad de dispositivo durante connect; el Gateway crea una solicitud de emparejamiento de dispositivo para role: node. Aprueba vía CLI de devices (o UI).

CLI rápido:

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

Notas:

- nodes status marca un nodo como emparejado cuando su rol de emparejamiento de dispositivo incluye node.

- node.pair.* (CLI: openclaw nodes pending/approve/reject) es un almacén de emparejamiento de nodo propiedad del gateway separado; no controla el handshake de connect WS.

Usa un node host cuando tu Gateway corre en una máquina y quieres que los comandos se ejecuten en otra. El modelo todavía habla al gateway; el gateway reenvía llamadas exec al node host cuando host=node está seleccionado.

#

- Host del Gateway: recibe mensajes, ejecuta el modelo, enruta llamadas de herramientas.

- Host del nodo: ejecuta system.run/system.which en la máquina del nodo.

- Aprobaciones: se aplican en el host del nodo vía ~/.openclaw/exec-approvals.json.

#

En la máquina del nodo:

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

#

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

Ejemplo (node host -> gateway host):

ssh -N -L 18790:127.0.0.1:18789 user@gateway-host


export OPENCLAW_GATEWAY_TOKEN="<gateway-token>"
openclaw node run --host 127.0.0.1 --port 18790 --display-name "Build Node"

Notas:

- El token es gateway.auth.token de la config del gateway (~/.openclaw/openclaw.json en el host del gateway).

- openclaw node run lee OPENCLAW_GATEWAY_TOKEN para auth.

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

#

En el host del gateway:

openclaw nodes pending
openclaw nodes approve <requestId>
openclaw nodes list

Opciones de nombrado:

- --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" (anulación del gateway).

#

Las aprobaciones de exec son por node host. Añade entradas de 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 viven en el node host en ~/.openclaw/exec-approvals.json.

#

Configura predeterminados (config 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 establecido, cualquier llamada exec con host=node corre en el node host (sujeto al allowlist/aprobaciones del nodo).

Relacionado:

- CLI de Node host

- Herramienta Exec

- Aprobaciones de exec

Bajo nivel (RPC crudo):

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

Existen helpers de alto nivel para los flujos comunes de "dar al agente un adjunto MEDIA".

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

Helper CLI (escribe a 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

#

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), más --x/--y/--width/--height opcional para posicionamiento.

- canvas eval acepta JS en línea (--js) o un argumento posicional.

#

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 A2UI v0.8 JSONL es soportado (v0.9/createSurface es rechazado).

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.* (llamadas en background retornan NODE_BACKGROUND_UNAVAILABLE).

- La duración del clip está limitada (actualmente <= 60s) para evitar payloads base64 demasiado grandes.

- Android mostrará prompt de permisos CAMERA/RECORD_AUDIO cuando sea posible; permisos denegados fallan con *_PERMISSION_REQUIRED.

Los nodos 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:

- screen.record requiere que la app del nodo esté en primer plano.

- Android mostrará prompt de captura de pantalla del sistema antes de grabar.

- Las grabaciones de pantalla están limitadas a <= 60s.

- --no-audio deshabilita captura de micrófono (soportado en iOS/Android; macOS usa audio de captura del sistema).

- Usa --screen <index> para seleccionar una pantalla cuando hay múltiples pantallas disponibles.

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

Helper CLI:

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

Notas:

- Ubicación está desactivada por defecto.

- "Siempre" requiere permiso del sistema; la obtención en background es best-effort.

- La respuesta incluye lat/lon, precisión (metros) y timestamp.

Los nodos Android pueden exponer sms.send cuando el usuario otorga 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 ser aceptado en el dispositivo Android antes de que la capacidad sea anunciada.

- Dispositivos solo Wi-Fi sin telefonía no anunciarán sms.send.

El nodo 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 run --node <idOrNameOrIp> -- echo "Hello from mac node"
openclaw nodes notify --node <idOrNameOrIp> --title "Ping" --body "Gateway ready"

Notas:

- system.run retorna stdout/stderr/código de salida en el payload.

- system.notify respeta el estado de permiso de notificación en la app macOS.

- system.run soporta --cwd, --env KEY=VAL, --command-timeout, y --needs-screen-recording.

- system.notify soporta --priority <passive|active|timeSensitive> y --delivery <system|overlay|auto>.

- Nodos macOS descartan sobreescrituras de PATH; node hosts headless solo aceptan PATH cuando antepone al PATH del node host.

- En modo nodo macOS, system.run está restringido por aprobaciones de exec en la app macOS (Settings → Exec approvals).

- Ask/allowlist/full se comportan igual que node host headless; prompts denegados retornan SYSTEM_RUN_DENIED.

- En node host headless, system.run está restringido por aprobaciones de exec (~/.openclaw/exec-approvals.json).

Cuando múltiples nodos están disponibles, puedes vincular exec a un nodo específico. Esto establece el nodo predeterminado para exec host=node (y puede anularse por agente).

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

Predeterminado global:

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

Anulación por agente:

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

Los nodos pueden incluir un mapa de permissions en node.list / node.describe, organizado por nombre de permiso (ej. screenRecording, accessibility) con valores booleanos (true = otorgado).

OpenClaw puede ejecutar un node host headless (sin UI) que 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ícialo:

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

Notas:

- El emparejamiento aún es requerido (el Gateway mostrará un prompt de aprobación de nodo).

- El node host almacena su node id, token, nombre para mostrar e info de conexión del gateway en ~/.openclaw/node.json.

- Las aprobaciones de exec se aplican localmente vía ~/.openclaw/exec-approvals.json (ver Aprobaciones de exec).

- En macOS, el node host headless prefiere el exec host de la app compañera cuando está alcanzable y recurre a ejecución local si la app no está disponible. Establece OPENCLAW_NODE_EXEC_HOST=app para requerir la app, o OPENCLAW_NODE_EXEC_FALLBACK=0 para deshabilitar el fallback.

- Agrega --tls / --tls-fingerprint cuando el WS del Gateway use TLS.

- La app de barra de menú de macOS conecta al servidor WS del Gateway como un nodo (así openclaw nodes … funciona contra esta Mac).

- En modo remoto, la app abre un tunnel SSH para el puerto del Gateway y conecta a localhost.