Nodos

Un Node es un dispositivo complementario (macOS/iOS/watchOS/Android/sin interfaz gráfica) que se conecta al Gateway con role: "node" y expone una superficie de comandos (p. ej., canvas.*, camera.*, device.*, notifications.*, system.*) mediante node.invoke. La mayoría de los Node usan el WebSocket del Gateway en el puerto del operador. El Node directo opcional de Apple Watch usa sondeo HTTPS firmado en ese mismo puerto porque watchOS bloquea las redes genéricas de bajo nivel para las aplicaciones normales. Detalles del protocolo: Protocolo del Gateway.

Transporte heredado: Protocolo Bridge (JSONL sobre TCP; solo histórico para los Node actuales).

macOS también puede ejecutarse en modo Node: la aplicación de la barra de menús se conecta al servidor WS del Gateway como un Node (por lo que openclaw nodes … funciona con este Mac). La aplicación añade comandos nativos de Canvas, cámara, pantalla, notificaciones y control del equipo a la misma superficie de comandos del host de Node que usa openclaw node run. No se debe iniciar un segundo Node de CLI en ese Mac; la aplicación ejecuta el entorno de ejecución de host de Node de CLI correspondiente como proceso interno y sigue siendo la única conexión al Gateway y la única identidad de Node.

Los Node son periféricos, no gateways: no ejecutan el servicio del Gateway, y los mensajes de canales (Telegram, WhatsApp, etc.) llegan al Gateway, no a los Node.

Guía de resolución de problemas: /nodes/troubleshooting

Emparejamiento y estado

Los Node usan emparejamiento de dispositivos. Un Node presenta una identidad de dispositivo firmada durante la conexión; el Gateway crea una solicitud de emparejamiento de dispositivo para role: node. Se aprueba mediante la CLI de dispositivos (o la interfaz de usuario). La configuración directa de Apple Watch usa un código de configuración de corta duración, acuñado por un administrador y exclusivo para Node, para aprobar su superficie fija de comandos de bajo riesgo; cualquier ampliación posterior de capacidades sigue requiriendo la aprobación normal.

openclaw devices listopenclaw devices approve <requestId>openclaw devices reject <requestId>openclaw nodes statusopenclaw nodes describe --node <idOrNameOrIp>

Las solicitudes de emparejamiento pendientes caducan 5 minutos después del último reintento del dispositivo: un dispositivo que sigue reconectándose mantiene activa su única solicitud pendiente (y su requestId) en lugar de generar una nueva solicitud cada pocos minutos; consulte Emparejamiento de Node para conocer el ciclo completo de solicitud y aprobación. Si un Node vuelve a intentarlo con datos de autenticación distintos (rol/ámbitos/clave pública), la solicitud pendiente anterior queda reemplazada y se crea un nuevo requestId; los clientes reciben un evento device.pair.resolved para la solicitud reemplazada y se debe volver a ejecutar openclaw devices list antes de aprobarla.

• nodes status marca un Node como emparejado cuando su rol de emparejamiento de dispositivo incluye node.
• Un Mac nativo conectado con permiso de Accesibilidad puede informar de actividad consolidada de entrada física. El Gateway marca el Mac válido con la actividad más reciente como active, proporciona al agente una indicación estable del identificador del Node y dirige allí las alertas de conexión de Node antes de recurrir a una alternativa retrasada. Consulte Presencia del equipo activo para obtener información sobre la configuración, la privacidad, los tiempos y la resolución de problemas.
• El registro de emparejamiento del dispositivo es el contrato duradero de roles aprobados. La rotación de tokens permanece dentro de ese contrato; no puede elevar un Node emparejado a un rol que nunca se concedió en la aprobación del emparejamiento.
• node.pair.* (CLI: openclaw nodes pending/approve/reject/remove/rename) es un almacén independiente de emparejamientos de Node, propiedad del Gateway, que mantiene la superficie aprobada de comandos y capacidades del Node entre reconexiones. No controla la autenticación del transporte; de ello se encarga el emparejamiento de dispositivos.
• openclaw nodes remove --node <id|name|ip> elimina un emparejamiento de Node. En un Node respaldado por un dispositivo, revoca el rol node del dispositivo en el almacén de dispositivos emparejados y desconecta las sesiones con rol de Node de ese dispositivo: un dispositivo con varios roles conserva su fila y solo pierde el rol node, mientras que se elimina la fila de un dispositivo que solo tiene el rol de Node. También borra cualquier entrada coincidente del almacén independiente de emparejamientos de Node. operator.pairing puede eliminar filas de Node que no sean de operador en otros dispositivos; un emisor con token de dispositivo que revoque su propio rol de Node en un dispositivo con varios roles necesita además operator.admin.
• El ámbito de aprobación depende de los comandos declarados en la solicitud pendiente:
  • solicitud sin comandos: operator.pairing
  • comandos de Node que no sean de ejecución: operator.pairing + operator.write
  • system.run / system.run.prepare / system.which: operator.pairing + operator.admin

Desfase de versiones y orden de actualización

El WebSocket del Gateway acepta clientes Node autenticados dentro de una ventana de protocolo N-1. Por lo tanto, el Gateway v4 actual acepta Node v3 cuando la conexión declara tanto role: "node" como client.mode: "node". Las sesiones de operador y de la interfaz de usuario deben seguir usando el protocolo actual.

Para actualizaciones escalonadas de una flota, se actualiza primero el Gateway y después cada Node. Un Node N-1 permanece visible y administrable mientras se actualiza; el Gateway registra legacy node protocol accepted junto con una recomendación de actualización. El emparejamiento, la autenticación de dispositivos, las listas de comandos permitidos y las aprobaciones de ejecución siguen siendo aplicables. Las capacidades y los comandos propiedad de plugins permanecen ocultos hasta que el Node se actualiza al protocolo actual. Los Node anteriores a N-1 requieren una actualización fuera de banda antes de volver a conectarse.

El transporte HTTPS directo de watchOS requiere la versión actual del protocolo; se debe actualizar la aplicación del reloj junto con el Gateway antes de activar el modo directo.

Host de Node remoto (system.run)

Se usa un host de Node cuando el Gateway se ejecuta en una máquina y se desea ejecutar comandos en otra. El modelo sigue comunicándose con el Gateway; el Gateway reenvía las llamadas de exec al host de Node cuando se selecciona host=node.

Nota sobre las aprobaciones:

• Las ejecuciones de Node respaldadas por aprobación vinculan el contexto exacto de la solicitud. La ruta de ejecución prepara un systemRunPlan canónico antes de la aprobación; una vez concedida, el Gateway reenvía ese plan almacenado, no los campos de comando/cwd/sesión que el emisor pueda modificar posteriormente, y vuelve a validar el directorio de trabajo antes de ejecutar.
• Para ejecuciones directas de archivos de shell o del entorno de ejecución, OpenClaw también intenta vincular un único operando de archivo local concreto y rechaza 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 entorno de ejecución, se rechaza la ejecución respaldada por aprobación en lugar de simular una cobertura completa del entorno de ejecución. Para una semántica de intérprete más amplia, se debe usar aislamiento, hosts separados o un flujo de trabajo completo o una lista explícita de elementos permitidos de confianza.

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"

node run también acepta --context-path (ruta de contexto del WS del Gateway), --tls, --tls-fingerprint <sha256> y --node-id (reemplaza el identificador heredado de instancia del cliente; esto no restablece el emparejamiento).

Gateway remoto mediante túnel SSH (enlace a loopback)

Si el Gateway está enlazado a loopback (gateway.bind=loopback, valor predeterminado en modo local), los hosts de Node remotos no pueden conectarse directamente. Se crea un túnel SSH y se dirige el host de Node al extremo local del túnel.

Ejemplo (host de Node -> host del Gateway):

# Terminal A (mantener en ejecución): reenviar 18790 local -> Gateway 127.0.0.1:18789ssh -N -L 18790:127.0.0.1:18789 user@gateway-host # Terminal B: exportar el token del Gateway y conectarse a través del túnelexport 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 mediante 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 de Node ignora intencionadamente gateway.remote.token / gateway.remote.password.
• En modo remoto, gateway.remote.token / gateway.remote.password se pueden usar según las reglas de precedencia remota.
• Si se configuran SecretRefs locales activos de gateway.auth.* pero no se resuelven, la autenticación del host de Node falla de forma cerrada.
• La resolución de autenticación del host de Node solo admite 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 startopenclaw node restart

node install también acepta --context-path, --tls, --tls-fingerprint, --node-id (solo el identificador heredado de instancia del cliente), --runtime <node|bun> (valor predeterminado: node) y --force para reinstalar. También están disponibles node status, node stop y node uninstall.

Emparejar y asignar un nombre

En el host del Gateway:

openclaw devices listopenclaw devices approve <requestId>openclaw nodes status

Si el Node vuelve a intentarlo con datos de autenticación distintos, se debe volver a ejecutar openclaw devices list y aprobar el requestId actual.

Opciones de nomenclatura:

• --display-name en openclaw node run / openclaw node install (se conserva en ~/.openclaw/node.json en el Node, junto con el identificador de instancia del cliente y los metadatos de conexión al Gateway).
• openclaw nodes rename --node <id|name|ip> --name "Build Node" (reemplazo en el Gateway).

Servidores MCP alojados en Node

Los servidores MCP se configuran en openclaw.json en la máquina del Node, no en el Gateway:

{  nodeHost: {    mcp: {      servers: {        localDocs: {          command: "npx",          args: ["-y", "@modelcontextprotocol/server-filesystem", "/srv/docs"],          toolFilter: {            include: ["read_*", "search"],          },        },        internalApi: {          url: "https://mcp.internal.example/mcp",          transport: "streamable-http",          headers: {            Authorization: "Bearer ${INTERNAL_MCP_TOKEN}",          },        },      },    },  },}

El host de Node sin interfaz gráfica inicia estos servidores, enumera sus herramientas y publica los descriptores después de conectarse. Las llamadas a herramientas regresan a ese Node mediante mcp.tools.call.v1; el Gateway no necesita una configuración MCP coincidente ni un plugin de JS. Los servidores MCP con OAuth no son compatibles con esta ruta v1 alojada en Node.

Los hosts de Node actuales declaran la familia de comandos integrada mcp.tools.call.v1 durante su emparejamiento inicial, incluso cuando no hay ningún servidor MCP configurado. Un Node emparejado con una versión anterior de OpenClaw puede solicitar una actualización puntual de la superficie de comandos después de actualizar el host de Node. Añadir, eliminar o filtrar servidores después de eso no requiere volver a emparejar porque la familia de comandos aprobada no cambia. Se debe reiniciar openclaw node run o ejecutar openclaw node restart para aplicar los cambios de configuración MCP del Node; el host de Node no supervisa esta configuración.

Los operadores del Gateway pueden ignorar todas las herramientas visibles para agentes publicadas por los Node emparejados, incluidas las herramientas MCP alojadas en Node, mediante gateway.nodes.pluginTools.enabled: false. Las denegaciones exactas de comandos, como gateway.nodes.denyCommands: ["mcp.tools.call.v1"], también bloquean la ejecución.

Skills alojadas en Node

Las Skills se instalan en el directorio activo de Skills de OpenClaw de la máquina del Node, ~/.openclaw/skills de forma predeterminada. OPENCLAW_HOME, OPENCLAW_STATE_DIR y OPENCLAW_CONFIG_PATH trasladan ese perfil activo. OPENCLAW_STATE_DIR tiene precedencia para las Skills; de lo contrario, skills/ se encuentra junto a la ruta mostrada por openclaw config file. El host de Node sin interfaz gráfica publica los archivos SKILL.md válidos después de conectarse, y el Gateway los añade a las instantáneas de Skills del agente solo mientras ese Node permanece conectado. El nombre del directorio de cada Skill debe coincidir con el campo name del frontmatter para que el localizador abstracto del Node se asocie a una sola entrada sin añadir otro campo al protocolo.

El emparejamiento inicial con rol de Node aprueba la publicación de Skills. Añadir, eliminar o cambiar Skills no requiere otro emparejamiento ni modificar la configuración del Gateway. Se debe reiniciar openclaw node run o ejecutar openclaw node restart después de modificar los archivos de Skills del Node; el host de Node no supervisa el directorio de Skills.

Las entradas de Skills alojadas en Node identifican su Node y llevan su ubicación de ejecución. Los archivos de Skills, las rutas relativas referenciadas y los binarios permanecen en ese Node. El agente lee la ubicación node://.../SKILL.md anunciada con la herramienta read normal. file_fetch acepta rutas absolutas del Node aprobadas por el operador, no localizadores de Skills del Node; en su lugar, los entornos de ejecución sin la herramienta de lectura normal pueden ejecutar cat SKILL.md mediante exec host=node node=<node-id> con el directorio node://.../skills/<name> anunciado como workdir. Los archivos y binarios referenciados usan el mismo destino de ejecución y directorio de trabajo. El host del Node resuelve ese localizador con respecto a su directorio de estado activo de OpenClaw, por lo que las rutas relativas se resuelven en el Node y no en el equipo del Gateway. El Node que publica debe tener aprobado system.run, y la política de ejecución del agente debe permitir host=node; de lo contrario, la Skill queda fuera de la instantánea de ese agente.

Establezca nodeHost.skills.enabled: false en el Node para detener la publicación. Los operadores del Gateway pueden ignorar las Skills de todos los Nodes emparejados con gateway.nodes.skills.enabled: false.

Estado de identidad sin interfaz

El Node sin interfaz mantiene tres archivos de estado separados:

• ~/.openclaw/node.json: el ID heredado de la instancia del cliente (almacenado como nodeId), el nombre para mostrar y los metadatos de conexión del Gateway.
• ~/.openclaw/identity/device.json: el par de claves firmado del dispositivo y el ID criptográfico derivado del dispositivo.
• ~/.openclaw/identity/device-auth.json: los tokens de autenticación de dispositivos emparejados, indexados por el ID criptográfico del dispositivo y el rol.

Para un Node firmado, el Gateway usa el ID criptográfico del dispositivo para el emparejamiento y el enrutamiento del Node. El ID de instancia del cliente solo son metadatos de conexión. Por lo tanto, cambiar --node-id o eliminar únicamente node.json no restablece el emparejamiento. Consulte Estado de identidad y emparejamiento para conocer el flujo compatible de revocación y nuevo emparejamiento, así como las notas de actualización.

Añadir los comandos a la lista de permitidos

Las aprobaciones de ejecución son por host de Node. Añada 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 se almacenan en el host del Node en ~/.openclaw/exec-approvals.json.

Dirigir la ejecución al Node

Configure los valores predeterminados (configuración del Gateway):

openclaw config set tools.exec.host nodeopenclaw config set tools.exec.security allowlistopenclaw 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 (sujeta a la lista de permitidos y las aprobaciones del Node).

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

Relacionado:

• CLI del host de Node
• Herramienta de ejecución
• Aprobaciones de ejecución

Inferencia de modelos locales

Un Node de escritorio o servidor puede exponer modelos con capacidad de chat desde un servidor Ollama que se ejecute en ese Node. Los agentes usan la herramienta node_inference del Plugin de Ollama para detectar los modelos instalados y ejecutar de forma remota un prompt acotado; el Gateway no necesita acceso directo por red a Ollama. Consulte Inferencia de Ollama local al Node para conocer la configuración, el filtrado de modelos y los comandos de verificación directa.

Sesiones y transcripciones de Codex

El Plugin oficial codex puede exponer sesiones de Codex no archivadas en un host de Node sin interfaz o en un Node nativo de macOS. El registro del catálogo ya no depende de supervision.enabled; esa opción controla las herramientas de supervisión disponibles para el agente. El Plugin debe seguir activo en ambos equipos, y la configuración del Node sigue siendo un consentimiento local: habilitar únicamente el Gateway no permite leer el estado de Codex de otro equipo.

El Node anuncia los comandos versionados de solo lectura codex.appServer.threads.list.v1 y codex.appServer.thread.turns.list.v1. Apruebe la actualización del emparejamiento del Node cuando esos comandos aparezcan por primera vez. El Gateway los invoca mediante la política normal del Node del Plugin y aísla los fallos por host.

Las filas de Nodes emparejados aparecen como un grupo Codex en la barra lateral normal de sesiones. Al seleccionar una fila, se abre el panel de chat normal y se lee su transcripción persistente mediante llamadas acotadas y paginadas por cursor a thread/turns/list con una proyección completa de los elementos. El transporte de invocación del Node es solo de solicitud/respuesta y no puede transportar los turnos en streaming, los eventos en directo ni las aprobaciones necesarias para continuar un hilo nativo mediante el entorno de Codex. Por lo tanto, Continuar y Archivar no están disponibles para las filas remotas. En el equipo del Gateway, las filas almacenadas e inactivas pueden iniciar una rama de chat independiente bloqueada al modelo. Cualquiera de ellas puede archivarse únicamente después de que el operador confirme que ningún otro cliente de Codex la está usando; la actividad en directo de una fila almacenada sigue siendo desconocida. Las filas activas no pueden ramificarse ni archivarse.

Consulte Supervisar sesiones de Codex para conocer la configuración, la paginación, la continuación local y el límite de seguridad de los metadatos.

Sesiones y transcripciones de Claude

El Plugin anthropic incluido detecta sesiones no archivadas de Claude CLI y Claude Desktop en el Gateway y en los Nodes emparejados. A diferencia de la supervisión de Codex, esto no requiere una activación independiente: un Node remoto de la aplicación de macOS anuncia anthropic.claude.sessions.list.v1 y anthropic.claude.sessions.read.v1 cuando el Plugin de Anthropic está habilitado y existe ~/.claude/projects/. Apruebe la actualización del emparejamiento del Node cuando esos comandos aparezcan por primera vez.

El catálogo combina registros válidos del índice de proyectos de Claude CLI con un prefijo acotado de metadatos procedentes de los archivos JSONL actuales de sdk-cli. Los metadatos locales de Claude Desktop proporcionan los títulos y el estado de archivado de Desktop. Los metadatos de Desktop prevalecen cuando ambas fuentes hacen referencia al mismo ID de sesión de Claude Code; las transcripciones exclusivas de CLI siguen visibles porque la CLI no tiene una marca de archivado. Las lecturas de transcripciones usan cursores opacos de desplazamiento de bytes y lecturas de archivos hacia atrás acotadas, por lo que seleccionar una sesión grande o cargar una página anterior no incluye todo el historial JSONL en una única respuesta del Gateway.

Ambos comandos del Node son de solo lectura. Exponen los metadatos del catálogo y el contenido de las transcripciones únicamente mediante los métodos genéricos sessions.catalog.list y sessions.catalog.read a una conexión autenticada del operador con operator.write. Las filas de Nodes emparejados permanecen en modo de solo visualización. Una fila de Claude CLI local al Gateway puede adoptarse desde el compositor de chat normal: OpenClaw importa el historial visible acotado, lo reanuda con --fork-session en el primer turno y deja intacta la transcripción de origen. Las filas de Claude Desktop permanecen en modo de solo visualización.

Consulte Anthropic: sesiones de Claude entre equipos para conocer el comportamiento de la interfaz de control y las fuentes de almacenamiento.

Invocación de comandos

Bajo nivel (RPC sin procesar):

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

nodes invoke bloquea system.run y system.run.prepare; esos comandos solo se ejecutan mediante la herramienta exec con host=node (véase arriba). Existen ayudantes de nivel superior para los flujos de trabajo habituales de «proporcionar al agente un archivo adjunto MEDIA» (lienzo, cámara, pantalla, ubicación, a continuación).

Política de comandos

Los comandos del Node deben superar dos controles antes de poder invocarse:

1. El Node debe declarar el comando en sus metadatos de conexión autenticada (connect.commands).
2. La lista de permitidos del Gateway derivada de la plataforma y las aprobaciones debe incluir el comando declarado.

Listas de permitidos predeterminadas por plataforma (antes de los valores predeterminados de los Plugins y las anulaciones de allowCommands/denyCommands):

Estas filas describen el límite máximo de la política del Gateway, no los comandos implementados por cada aplicación de Node. Un comando solo puede usarse cuando el Node conectado también lo declara. En particular, la aplicación actual de macOS no declara las familias de datos personales y de dispositivos enumeradas en la fila de políticas de macOS.

Los comandos canvas.* (canvas.present, canvas.hide, canvas.navigate, canvas.eval, canvas.snapshot, canvas.a2ui.*) son un valor predeterminado del Plugin en iOS, Android, macOS, Windows y plataformas desconocidas (no en Linux); todos ellos están restringidos al primer plano en iOS.

talk.ptt.start, talk.ptt.stop, talk.ptt.cancel y talk.ptt.once se permiten de forma predeterminada para cualquier Node que anuncie la capacidad talk o declare comandos talk.*, independientemente de la etiqueta de plataforma.

Los comandos del host de escritorio (system.run, system.run.prepare, system.which, browser.proxy, mcp.tools.call.v1 y screen.snapshot en macOS/Windows) no forman parte de la tabla estática de valores predeterminados por plataforma anterior. Quedan disponibles cuando el operador aprueba una solicitud de emparejamiento que los declara; a partir de entonces, el conjunto de comandos aprobados del Node los mantiene en las reconexiones.

Los comandos peligrosos o con un impacto considerable en la privacidad siguen requiriendo una activación explícita mediante gateway.nodes.allowCommands, incluso si un Node los declara: camera.snap, camera.clip, screen.record, computer.act, contacts.add, calendar.add, reminders.add, sms.send, sms.search. gateway.nodes.denyCommands siempre prevalece sobre los valores predeterminados y las entradas adicionales de la lista de permitidos. Consulte Uso del ordenador para conocer los controles adicionales de macOS, la política de herramientas y la habilitación relacionados con la entrada de escritorio.

Los comandos de Node propiedad de plugins pueden añadir una política de invocación de Node del Gateway. Esa política se ejecuta después de comprobar la lista de permitidos y antes de reenviar al Node, por lo que node.invoke sin procesar, los auxiliares de la CLI y las herramientas específicas del agente comparten el mismo límite de permisos del plugin. Los comandos de Node peligrosos de plugins siguen requiriendo la inclusión explícita en gateway.nodes.allowCommands.

Después de que un Node cambie su lista de comandos declarada, rechace el emparejamiento anterior del dispositivo y apruebe la nueva solicitud para que el Gateway almacene la instantánea actualizada de comandos.

Configuración (openclaw.json)

Los ajustes relacionados con los Nodes se encuentran en gateway.nodes y tools.exec:

{  gateway: {    nodes: {      // Aprobar automáticamente el primer emparejamiento de un Node desde redes de confianza (lista CIDR).      // Está desactivado si no se configura. Solo se aplica a solicitudes iniciales role:node      // sin ámbitos solicitados; no aprueba automáticamente las actualizaciones.      pairing: {        autoApproveCidrs: ["192.168.1.0/24"],        // Aprobación automática verificada mediante SSH (predeterminado: activada). Aprueba el primer        // emparejamiento del Node si la clave de dispositivo leída mediante SSH coincide exactamente.        sshVerify: true,      },      // Confiar en las herramientas de plugins visibles para el agente publicadas por Nodes emparejados (predeterminado: true).      pluginTools: {        enabled: true,      },      // Habilitar explícitamente comandos de Node peligrosos o que afectan considerablemente a la privacidad (camera.snap, etc.).      allowCommands: ["camera.snap", "screen.record"],      // Bloquear nombres de comandos exactos aunque los valores predeterminados o allowCommands los incluyan.      denyCommands: ["camera.clip"],    },  },  tools: {    exec: {      // Host de ejecución predeterminado: "node" dirige todas las llamadas de ejecución a un Node emparejado.      host: "node",      // Modo de seguridad para la ejecución en el Node: permitir solo comandos aprobados o incluidos en la lista de permitidos.      security: "allowlist",      // Fijar la ejecución a un Node específico (id o nombre). Omitir para permitir cualquier Node.      node: "build-node",    },  },}

Use los nombres exactos de los comandos del Node. denyCommands elimina un comando incluso cuando un valor predeterminado de la plataforma o una entrada de allowCommands lo permitiría. De forma predeterminada, los Nodes emparejados pueden publicar descriptores de herramientas de plugins visibles para el agente, pero el comando de cada descriptor debe seguir formando parte de la superficie de comandos aprobada del Node. Establezca gateway.nodes.pluginTools.enabled: false para ignorar todos esos descriptores. Consulte la referencia de configuración del Gateway para obtener detalles sobre los campos de emparejamiento de Nodes y de política de comandos del Gateway.

Anulación del Node de ejecución por agente:

{  agents: {    list: [      {        id: "main",        tools: { exec: { node: "build-node" } },      },    ],  },}

Capturas de pantalla (instantáneas del lienzo)

Si el Node muestra el lienzo (WebView), canvas.snapshot devuelve { format, base64 }.

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

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

Controles del lienzo

openclaw nodes canvas present --node <idOrNameOrIp> --target https://example.comopenclaw 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 opcionales para el posicionamiento.
• canvas eval acepta JavaScript en línea (--js) o un argumento posicional.

A2UI (lienzo)

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

Notas:

• Los Nodes móviles usan una página A2UI incluida y propiedad de la aplicación para representar contenido con acciones.
• Solo se admite JSONL de A2UI v0.8 (se rechaza v0.9/createSurface).
• iOS y Android representan páginas remotas del lienzo del Gateway, pero las acciones de los botones de A2UI solo se envían desde la página A2UI incluida y propiedad de la aplicación. En esos clientes móviles, las páginas A2UI HTTP/HTTPS alojadas por el Gateway son únicamente de representación.
• macOS puede enviar acciones desde la página A2UI exacta del Gateway, limitada por capacidades, que selecciona la aplicación. Las demás páginas HTTP/HTTPS siguen siendo únicamente de representación.

Fotos y vídeos (cámara del Node)

Fotos (jpg):

openclaw nodes camera list --node <idOrNameOrIp>openclaw nodes camera snap --node <idOrNameOrIp>            # predeterminado: ambas cámaras (2 líneas MEDIA)openclaw nodes camera snap --node <idOrNameOrIp> --facing frontopenclaw nodes camera snap --node <idOrNameOrIp> --device-id <id> --max-width 1200 --quality 0.9 --delay-ms 2000

Clips de vídeo (mp4):

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

Notas:

• El Node debe estar en primer plano para canvas.* y camera.* (las llamadas en segundo plano devuelven NODE_BACKGROUND_UNAVAILABLE).
• Los Nodes limitan la duración de los clips para mantener manejable la carga útil base64 (consulte Captura de cámara para conocer los límites exactos de cada plataforma). Además, la herramienta de agente nodes limita el valor solicitado de durationMs a 300000 (5 minutos) antes de reenviar la llamada; el propio Node aplica el límite más estricto.
• Android solicitará los permisos CAMERA/RECORD_AUDIO cuando sea posible; los permisos denegados producen el error *_PERMISSION_REQUIRED.

Grabaciones de pantalla (Nodes)

Los Nodes compatibles exponen screen.record (mp4). Ejemplo:

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

Notas:

• La disponibilidad de screen.record depende de la plataforma del Node.
• La herramienta de agente nodes limita el valor solicitado de durationMs a 300000 (5 minutos); el Node puede aplicar un límite más estricto para acotar la carga útil devuelta.
• --no-audio desactiva la captura del micrófono en las plataformas compatibles.
• Use --screen <index> para seleccionar una pantalla cuando haya varias disponibles (0 = principal).

Ubicación (Nodes)

Los Nodes exponen location.get cuando la ubicación está activada en los ajustes.

Auxiliar 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 de forma predeterminada.
• "Always" requiere permiso del sistema; la obtención en segundo plano se realiza con el mejor esfuerzo.
• La respuesta incluye latitud/longitud, precisión (metros) y marca de tiempo.
• Forma completa de los parámetros y la respuesta, y códigos de error: Comando de ubicación.

SMS (Nodes Android)

Los Nodes Android pueden exponer sms.send y sms.search cuando el usuario concede el permiso SMS y el dispositivo admite telefonía. Ambos comandos son peligrosos de forma predeterminada: el operador del Gateway también debe añadirlos a gateway.nodes.allowCommands antes de que puedan invocarse (consulte Política de comandos).

Para habilitar explícitamente la búsqueda de SMS de solo lectura en openclaw.json:

{  gateway: {    nodes: {      allowCommands: ["sms.search"],    },  },}

Añada sms.send por separado solo cuando el Node también deba poder enviar mensajes. El permiso de Android y la autorización de comandos del Gateway son independientes; conceder el permiso del teléfono no modifica la política del Gateway.

Invocación de bajo nivel:

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

Notas:

• sms.search puede declararse antes de que se conceda READ_SMS para que una invocación pueda devolver un diagnóstico de permisos; la lectura de mensajes sigue requiriendo ese permiso de Android.
• Los dispositivos que solo tienen Wi-Fi y carecen de telefonía no anunciarán sms.send.
• Un error requires explicit gateway.nodes.allowCommands opt-in significa que el teléfono declaró el comando, pero el operador del Gateway no lo ha autorizado.

Comandos de datos personales y del dispositivo

Los Nodes iOS y Android anuncian de forma predeterminada varios comandos de datos de solo lectura (consulte la tabla de Política de comandos); Android también expone una familia más amplia controlada por sus propios ajustes dentro de la aplicación.

Familias disponibles:

• device.status, device.info — iOS, Android, Windows.
• device.permissions, device.health, device.apps — solo Android; device.apps requiere que el uso compartido de aplicaciones instaladas esté activado en Android Settings y devuelve de forma predeterminada las aplicaciones visibles en el iniciador.
• notifications.list, notifications.actions — solo Android.
• photos.latest — iOS, Android.
• contacts.search — iOS, Android (solo lectura de forma predeterminada); contacts.add es peligroso y requiere gateway.nodes.allowCommands.
• calendar.events — iOS, Android (solo lectura de forma predeterminada); calendar.add es peligroso y requiere gateway.nodes.allowCommands.
• reminders.list — iOS, Android (solo lectura de forma predeterminada); reminders.add es peligroso y requiere gateway.nodes.allowCommands.
• callLog.search — solo Android.
• motion.activity, motion.pedometer — iOS, Android; sujetos a las capacidades de los sensores disponibles.

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}'

Comandos del sistema (host del Node / Node de Mac)

El Node de macOS expone system.run, system.which, system.notify y system.execApprovals.get/set. El host de Node sin interfaz expone system.run.prepare, 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 '{"bins":["git"]}'

Notas:

• system.run devuelve stdout/stderr/el código de salida en la carga útil.
• La ejecución del shell ahora se realiza mediante la herramienta exec con host=node; nodes sigue siendo la superficie RPC directa para comandos explícitos de Node.
• nodes invoke no expone system.run ni system.run.prepare; estos permanecen únicamente en la ruta de exec.
• La ruta de exec prepara un systemRunPlan canónico antes de la aprobación. Una vez concedida la aprobación, el Gateway reenvía ese plan almacenado, no ningún campo de comando/cwd/sesión que el invocador edite posteriormente.
• system.notify respeta el estado del permiso de notificaciones en la aplicación para macOS; admite --priority <passive|active|timeSensitive> y --delivery <system|overlay|auto>.
• Los metadatos platform / deviceFamily de Node no reconocidos usan una lista de permitidos predeterminada conservadora que excluye system.run y system.which. Si se necesitan intencionadamente esos comandos para una plataforma desconocida, añádalos explícitamente mediante gateway.nodes.allowCommands.
• system.run admite --cwd, --env KEY=VAL, --command-timeout y --needs-screen-recording.
• Para los envoltorios de shell (bash|sh|zsh ... -c/-lc), los valores de --env limitados al ámbito de la 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 envoltorios de despacho conocidos (env, flock, nice, nohup, stdbuf, timeout) conservan las rutas de los ejecutables internos en lugar de las rutas de los envoltorios. Si no es seguro desenvolverlos, no se conserva automáticamente ninguna entrada en la lista de permitidos.
• En hosts Node de Windows en modo de lista de permitidos, las ejecuciones de envoltorios de shell mediante cmd.exe /c requieren aprobación (una entrada en la lista de permitidos por sí sola no permite automáticamente la forma con envoltorio).
• Los hosts Node ignoran las sustituciones de PATH en --env y eliminan un conjunto amplio y mantenido de variables de inicio de intérpretes/shells (por ejemplo, NODE_OPTIONS, PYTHONPATH, BASH_ENV, DYLD_*, LD_*) antes de ejecutar un comando. Si se necesitan entradas adicionales en PATH, configure el entorno del servicio del host Node (o instale las herramientas en ubicaciones estándar) en lugar de pasar PATH mediante --env.
• En el modo Node de macOS, system.run está sujeto a las aprobaciones de exec en la aplicación para macOS (Settings → Exec approvals). Los modos preguntar/lista de permitidos/completo se comportan igual que en el host Node sin interfaz; las solicitudes denegadas devuelven SYSTEM_RUN_DENIED.
• En el host Node sin interfaz, system.run está sujeto a las aprobaciones de exec (~/.openclaw/exec-approvals.json); específicamente en macOS, consulte más abajo las variables de entorno de enrutamiento del host de exec en Host Node sin interfaz.

Vinculación de Node para exec

Cuando hay varios Node disponibles, se puede vincular exec a uno específico. Esto establece el Node predeterminado para exec host=node (y puede sustituirse por agente).

Valor predeterminado global:

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

Sustitución por agente:

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

Desconfigure el valor para permitir cualquier Node:

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

Mapa de permisos

Los Node pueden incluir un mapa permissions en node.list / node.describe, indexado por nombre de permiso (por ejemplo, screenRecording, accessibility, location) con valores booleanos (true = concedido).

Host Node sin interfaz (multiplataforma)

OpenClaw puede ejecutar un host Node sin interfaz (sin IU) que se conecta al WebSocket del Gateway y expone system.run / system.which. Esto resulta útil en Linux/Windows o para ejecutar un Node mínimo junto con un servidor.

Inícielo:

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

Notas:

• El emparejamiento sigue siendo obligatorio (el Gateway mostrará una solicitud de emparejamiento del dispositivo).
• Los metadatos de la instancia del cliente, la identidad firmada del dispositivo y la autenticación de emparejamiento usan archivos independientes; consulte Estado de la identidad sin interfaz.
• Las aprobaciones de exec se aplican localmente mediante ~/.openclaw/exec-approvals.json (consulte Aprobaciones de exec).
• En macOS, el host Node sin interfaz ejecuta system.run localmente de forma predeterminada. Establezca OPENCLAW_NODE_EXEC_HOST=app para enrutar system.run mediante el host de exec de la aplicación complementaria; añada OPENCLAW_NODE_EXEC_FALLBACK=0 para exigir el host de la aplicación y aplicar un cierre seguro si no está disponible.
• Añada --tls / --tls-fingerprint cuando el WS del Gateway use TLS.

Modo Node de Mac

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