Un nodo es un dispositivo complementario (macOS/iOS/Android/sin interfaz) que se conecta al WebSocket del Gateway (el mismo puerto que los operadores) conDocumentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
role: "node" y expone una superficie de comandos (p. ej., canvas.*, camera.*, device.*, notifications.*, system.*) mediante node.invoke. Detalles del protocolo: protocolo del Gateway.
Transporte heredado: protocolo de Bridge (TCP JSONL;
solo histórico para los nodos actuales).
macOS también puede ejecutarse en modo de nodo: la app de la barra de menús se conecta al servidor
WS del Gateway y expone sus comandos locales de canvas/cámara como un nodo (de modo que
openclaw nodes … funciona contra este Mac). En modo de gateway remoto, la
automatización del navegador la gestiona el host de nodo de la CLI (openclaw node run o el
servicio de nodo instalado), no el nodo de la app nativa.
Notas:
- Los nodos son periféricos, no gateways. No ejecutan el servicio de gateway.
- Los mensajes de Telegram/WhatsApp/etc. llegan al gateway, no a los nodos.
- Guía de resolución de problemas: /nodes/troubleshooting
Emparejamiento + estado
Los nodos WS usan emparejamiento de dispositivo. Los nodos presentan una identidad de dispositivo duranteconnect; el Gateway
crea una solicitud de emparejamiento de dispositivo para role: node. Apruébala mediante la CLI de dispositivos (o la UI).
CLI rápida:
requestId. Vuelve a ejecutar
openclaw devices list antes de aprobar.
Notas:
nodes statusmarca un nodo como emparejado cuando su rol de emparejamiento de dispositivo incluyenode.- El registro de emparejamiento de dispositivo es el contrato duradero de rol aprobado. La rotación de tokens permanece dentro de ese contrato; no puede convertir un nodo emparejado en un rol distinto que la aprobación de emparejamiento nunca concedió.
node.pair.*(CLI:openclaw nodes pending/approve/reject/remove/rename) es un almacén de emparejamiento de nodos independiente, propiedad del gateway; no bloquea el handshakeconnectde WS.openclaw nodes remove --node <id|name|ip>elimina entradas obsoletas de ese almacén de emparejamiento de nodos independiente, propiedad del gateway.- El alcance de aprobación sigue los comandos declarados por la solicitud pendiente:
- solicitud sin comandos:
operator.pairing - comandos de nodo que no son de ejecución:
operator.pairing+operator.write system.run/system.run.prepare/system.which:operator.pairing+operator.admin
- solicitud sin comandos:
Host de nodo remoto (system.run)
Usa un host de nodo cuando tu Gateway se ejecuta en una máquina y quieres que los comandos se ejecuten en otra. El modelo sigue hablando con el gateway; el gateway reenvía las llamadasexec al host de nodo cuando se selecciona host=node.
Qué se ejecuta dónde
- Host del Gateway: recibe mensajes, ejecuta el modelo y enruta llamadas de herramientas.
- Host de nodo: ejecuta
system.run/system.whichen la máquina del nodo. - Aprobaciones: se aplican en el host de nodo mediante
~/.openclaw/exec-approvals.json.
- Las ejecuciones de nodo respaldadas por aprobación vinculan el contexto exacto de la solicitud.
- Para ejecuciones directas de archivos de shell/runtime, OpenClaw también intenta vincular un operando de archivo local concreto y deniega 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 simular cobertura completa del runtime. Usa sandboxing, hosts separados o una allowlist/workflow completo explícitamente confiable para semánticas de intérprete más amplias.
Iniciar un host de nodo (primer plano)
En la máquina del nodo:Gateway remoto mediante túnel SSH (enlace loopback)
Si el Gateway se enlaza a loopback (gateway.bind=loopback, predeterminado en modo local),
los hosts de nodo remotos no pueden conectarse directamente. Crea un túnel SSH y apunta el
host de nodo al extremo local del túnel.
Ejemplo (host de nodo -> host del gateway):
openclaw node runadmite 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 de nodo ignora intencionadamente
gateway.remote.token/gateway.remote.password. - En modo remoto,
gateway.remote.token/gateway.remote.passwordson elegibles según las reglas de precedencia remota. - Si se configuran SecretRefs
gateway.auth.*locales activos pero no resueltos, la autenticación del host de nodo falla de forma cerrada. - La resolución de autenticación del host de nodo solo respeta las variables de entorno
OPENCLAW_GATEWAY_*.
Iniciar un host de nodo (servicio)
Emparejar + nombrar
En el host del gateway:openclaw devices list
y aprueba el requestId actual.
Opciones de nombre:
--display-nameenopenclaw node run/openclaw node install(persiste en~/.openclaw/node.jsonen el nodo).openclaw nodes rename --node <id|name|ip> --name "Build Node"(anulación del gateway).
Añadir los comandos a la allowlist
Las aprobaciones de ejecución son por host de nodo. Añade entradas de allowlist desde el gateway:~/.openclaw/exec-approvals.json.
Apuntar exec al nodo
Configura los valores predeterminados (configuración del gateway):exec con host=node se ejecuta en el host de nodo (sujeta a la
allowlist/aprobaciones del nodo).
host=auto no elegirá implícitamente el nodo por sí solo, pero se permite una solicitud explícita por llamada host=node desde auto. Si quieres que la ejecución en nodo sea la predeterminada para la sesión, configura tools.exec.host=node o /exec host=node ... explícitamente.
Relacionado:
Invocar comandos
Bajo nivel (RPC sin procesar):Política de comandos
Los comandos de nodo deben pasar dos controles antes de poder invocarse:- El nodo debe declarar el comando en su lista WebSocket
connect.commands. - La política de plataforma del gateway debe permitir el comando declarado.
canvas.*, camera.list, location.get y screen.snapshot.
Los nodos confiables que anuncian la capacidad talk o declaran comandos talk.*
también permiten de forma predeterminada comandos push-to-talk declarados (talk.ptt.start, talk.ptt.stop,
talk.ptt.cancel, talk.ptt.once), independientemente de la etiqueta de plataforma.
Los comandos peligrosos o con fuerte impacto en privacidad, como camera.snap, camera.clip y
screen.record, siguen requiriendo opt-in explícito con
gateway.nodes.allowCommands. gateway.nodes.denyCommands siempre prevalece sobre
los valores predeterminados y las entradas adicionales de allowlist.
Los comandos de nodo propiedad de un Plugin pueden añadir una política de invocación de nodo del Gateway. Esa política
se ejecuta después de la comprobación de allowlist y antes de reenviar al nodo, por lo que node.invoke
sin procesar, los helpers de la CLI y las herramientas dedicadas del agente comparten el mismo
límite de permisos del Plugin. Los comandos de nodo peligrosos del Plugin siguen requiriendo opt-in explícito de
gateway.nodes.allowCommands.
Después de que un nodo cambie su lista de comandos declarados, rechaza el emparejamiento de dispositivo anterior
y aprueba la nueva solicitud para que el gateway almacene la instantánea de comandos actualizada.
Capturas de pantalla (instantáneas de canvas)
Si el nodo muestra el Canvas (WebView),canvas.snapshot devuelve { format, base64 }.
Helper de CLI (escribe en un archivo temporal e imprime MEDIA:<path>):
Controles de Canvas
canvas presentacepta URLs o rutas de archivos locales (--target), además de--x/--y/--width/--heightopcionales para posicionamiento.canvas evalacepta JS en línea (--js) o un argumento posicional.
A2UI (Canvas)
- Solo se admite A2UI v0.8 JSONL (v0.9/createSurface se rechaza).
Fotos + videos (cámara de nodo)
Fotos (jpg):
mp4):
- El nodo debe estar en primer plano para
canvas.*ycamera.*(las llamadas en segundo plano devuelvenNODE_BACKGROUND_UNAVAILABLE). - La duración del clip se limita (actualmente
<= 60s) para evitar payloads base64 demasiado grandes. - Android solicitará permisos
CAMERA/RECORD_AUDIOcuando sea posible; los permisos denegados fallan con*_PERMISSION_REQUIRED.
Grabaciones de pantalla (nodos)
Los nodos compatibles exponenscreen.record (mp4). Ejemplo:
- La disponibilidad de
screen.recorddepende de la plataforma del nodo. - Las grabaciones de pantalla se limitan a
<= 60s. --no-audiodesactiva la captura del micrófono en plataformas compatibles.- Usa
--screen <index>para seleccionar una pantalla cuando haya varias disponibles.
Ubicación (nodos)
Los nodos exponenlocation.get cuando Ubicación está habilitada en la configuración.
Helper de CLI:
- Ubicación está desactivada de forma predeterminada.
- “Siempre” requiere permiso del sistema; la obtención en segundo plano es de mejor esfuerzo.
- La respuesta incluye lat/lon, precisión (metros) y marca de tiempo.
SMS (nodos Android)
Los nodos Android pueden exponersms.send cuando el usuario concede permiso de SMS y el dispositivo admite telefonía.
Invocación de bajo nivel:
- La solicitud de permiso debe aceptarse en el dispositivo Android antes de que la capacidad se anuncie.
- Los dispositivos solo Wi-Fi sin telefonía no anunciarán
sms.send.
Comandos de dispositivo Android + datos personales
Los nodos Android pueden anunciar familias de comandos adicionales cuando las capacidades correspondientes están habilitadas. Familias disponibles:device.status,device.info,device.permissions,device.healthnotifications.list,notifications.actionsphotos.latestcontacts.search,contacts.addcalendar.events,calendar.addcallLog.searchsms.searchmotion.activity,motion.pedometer
- Los comandos de movimiento están restringidos por capacidad según los sensores disponibles.
Comandos del sistema (host de nodo / nodo Mac)
El nodo de macOS exponesystem.run, system.notify y system.execApprovals.get/set.
El host de nodo sin interfaz gráfica expone system.run, system.which y system.execApprovals.get/set.
Ejemplos:
system.rundevuelve stdout/stderr/código de salida en la carga útil.- La ejecución de shell ahora pasa por la herramienta
execconhost=node;nodessigue siendo la superficie RPC directa para comandos de nodo explícitos. nodes invokeno exponesystem.runnisystem.run.prepare; estos permanecen solo en la ruta exec.- La ruta exec prepara un
systemRunPlancanónico antes de la aprobación. Una vez que se concede una aprobación, el Gateway reenvía ese plan almacenado, no ningún campo de comando/cwd/session editado posteriormente por el invocador. system.notifyrespeta el estado del permiso de notificaciones en la app de macOS.- Los metadatos
platform/deviceFamilyde nodo no reconocidos usan una lista de permitidos predeterminada conservadora que excluyesystem.runysystem.which. Si necesitas intencionalmente esos comandos para una plataforma desconocida, agrégalos explícitamente mediantegateway.nodes.allowCommands. system.runadmite--cwd,--env KEY=VAL,--command-timeouty--needs-screen-recording.- Para envoltorios de shell (
bash|sh|zsh ... -c/-lc), los valores--envcon alcance de solicitud se reducen a una lista de permitidos explícita (TERM,LANG,LC_*,COLORTERM,NO_COLOR,FORCE_COLOR). - Para decisiones de permitir siempre en modo de lista de permitidos, los envoltorios de despacho conocidos (
env,nice,nohup,stdbuf,timeout) conservan las rutas de ejecutables internos en lugar de las rutas de los envoltorios. Si desenvolverlos no es seguro, no se conserva automáticamente ninguna entrada de lista de permitidos. - En hosts de nodo Windows en modo de lista de permitidos, las ejecuciones de envoltorio de shell mediante
cmd.exe /crequieren aprobación (una entrada de lista de permitidos por sí sola no permite automáticamente la forma de envoltorio). system.notifyadmite--priority <passive|active|timeSensitive>y--delivery <system|overlay|auto>.- Los hosts de nodo ignoran las anulaciones de
PATHy eliminan claves peligrosas de inicio/shell (DYLD_*,LD_*,NODE_OPTIONS,PYTHON*,PERL*,RUBYOPT,SHELLOPTS,PS4). Si necesitas entradas adicionales de PATH, configura el entorno del servicio del host de nodo (o instala las herramientas en ubicaciones estándar) en lugar de pasarPATHmediante--env. - En el modo de nodo macOS,
system.runestá restringido por aprobaciones exec en la app de macOS (Settings → Exec approvals). Preguntar/lista de permitidos/completo se comportan igual que el host de nodo sin interfaz gráfica; las solicitudes denegadas devuelvenSYSTEM_RUN_DENIED. - En el host de nodo sin interfaz gráfica,
system.runestá restringido por aprobaciones exec (~/.openclaw/exec-approvals.json).
Vinculación de nodo exec
Cuando hay varios nodos disponibles, puedes vincular exec a un nodo específico. Esto establece el nodo predeterminado paraexec host=node (y se puede anular por agente).
Predeterminado global:
Mapa de permisos
Los nodos pueden incluir un mapapermissions en node.list / node.describe, indexado por nombre de permiso (por ejemplo, screenRecording, accessibility) con valores booleanos (true = concedido).
Host de nodo sin interfaz gráfica (multiplataforma)
OpenClaw puede ejecutar un host de nodo sin interfaz gráfica (sin IU) que se conecta al WebSocket del Gateway y exponesystem.run / system.which. Esto es útil en Linux/Windows
o para ejecutar un nodo mínimo junto a un servidor.
Inícialo:
- El emparejamiento sigue siendo obligatorio (el Gateway mostrará una solicitud de emparejamiento de dispositivo).
- El host de nodo almacena su id de nodo, token, nombre visible e información de conexión del gateway en
~/.openclaw/node.json. - Las aprobaciones exec se aplican localmente mediante
~/.openclaw/exec-approvals.json(consulta Aprobaciones exec). - En macOS, el host de nodo sin interfaz gráfica ejecuta
system.runlocalmente de forma predeterminada. EstableceOPENCLAW_NODE_EXEC_HOST=apppara enrutarsystem.runa través del host exec de la app complementaria; agregaOPENCLAW_NODE_EXEC_FALLBACK=0para exigir el host de la app y fallar de forma cerrada si no está disponible. - Agrega
--tls/--tls-fingerprintcuando el WS del Gateway use TLS.
Modo de nodo Mac
- La app de barra de menús de macOS se conecta al servidor WS del Gateway como nodo (por lo que
openclaw nodes …funciona contra este Mac). - En modo remoto, la app abre un túnel SSH para el puerto del Gateway y se conecta a
localhost.