Un Node es un dispositivo complementario (macOS/iOS/Android/headless) que se conecta al WebSocket del Gateway (el mismo puerto que usan 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 (por ejemplo canvas.*, camera.*, device.*, notifications.*, system.*) mediante node.invoke. Detalles del protocolo: Protocolo del Gateway.
Transporte heredado: Protocolo Bridge (TCP JSONL;
solo histórico para los Nodes actuales).
macOS también puede ejecutarse en modo Node: la app de barra de menús se conecta al
servidor WS del Gateway y expone sus comandos locales de canvas/camera como un Node (por lo que
openclaw nodes … funciona contra este Mac). En modo de gateway remoto, la
automatización del navegador la gestiona el host CLI del Node (openclaw node run o el
servicio Node instalado), no el Node de la app nativa.
Notas:
- Los Nodes son periféricos, no gateways. No ejecutan el servicio de gateway.
- Los mensajes de Telegram/WhatsApp/etc. llegan al gateway, no a los Nodes.
- Runbook de resolución de problemas: /nodes/troubleshooting
Emparejamiento + estado
Los Nodes WS usan emparejamiento de dispositivos. Los Nodes 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 Node como emparejado cuando su rol de emparejamiento de dispositivo incluyenode.- El registro de emparejamiento del dispositivo es el contrato duradero de roles aprobados. La rotación del token permanece dentro de ese contrato; no puede convertir un Node emparejado en un rol diferente que la aprobación de emparejamiento nunca concedió.
node.pair.*(CLI:openclaw nodes pending/approve/reject/rename) es un almacén de emparejamiento de Node independiente y propiedad del gateway; no controla el handshake WSconnect.- El alcance de aprobación sigue los comandos declarados en la solicitud pendiente:
- solicitud sin comandos:
operator.pairing - comandos de Node sin exec:
operator.pairing+operator.write system.run/system.run.prepare/system.which:operator.pairing+operator.admin
- solicitud sin comandos:
Host remoto de Node (system.run)
Usa un host de Node 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 llamadas exec al host de Node cuando se selecciona host=node.
Qué se ejecuta dónde
- Host del Gateway: recibe mensajes, ejecuta el modelo, enruta llamadas a herramientas.
- Host de Node: ejecuta
system.run/system.whichen la máquina del Node. - Aprobaciones: se aplican en el host de Node mediante
~/.openclaw/exec-approvals.json.
- Las ejecuciones de Node respaldadas por aprobación vinculan el contexto exacto de la solicitud.
- Para ejecuciones directas de shell/archivos de runtime, OpenClaw también intenta vincular, en la medida de lo posible, un único operando concreto de archivo local y deniega la ejecución si ese archivo cambia antes de ejecutarse.
- Si OpenClaw no puede identificar exactamente un único 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. Usa sandboxing, hosts separados o una allowlist explícita de confianza/un flujo completo para una semántica más amplia de intérpretes.
Iniciar un host de Node (primer plano)
En la máquina del Node:Gateway remoto mediante túnel SSH (bind loopback)
Si el Gateway se vincula a loopback (gateway.bind=loopback, predeterminado en modo local),
los hosts remotos de Node no pueden conectarse directamente. Crea un túnel SSH y apunta el
host de Node al extremo local del túnel.
Ejemplo (host de Node -> 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 en config 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.passwordson candidatos según las reglas de precedencia remota. - Si hay SecretRef activos locales
gateway.auth.*configurados pero sin resolver, la autenticación del host de Node falla en modo cerrado. - La resolución de autenticación del host de Node solo respeta las variables de entorno
OPENCLAW_GATEWAY_*.
Iniciar un host de Node (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(se conserva en~/.openclaw/node.jsonen el Node).openclaw nodes rename --node <id|name|ip> --name "Build Node"(anulación del gateway).
Añadir los comandos a la allowlist
Las aprobaciones de exec son por host de Node. Añade entradas a la allowlist desde el gateway:~/.openclaw/exec-approvals.json.
Apuntar exec al Node
Configura valores predeterminados (configuración del gateway):exec con host=node se ejecuta en el host de Node (sujeta a la
allowlist/aprobaciones del Node).
host=auto no elegirá implícitamente el Node por sí solo, pero una solicitud explícita por llamada host=node sí está permitida desde auto. Si quieres que exec en Node sea el valor predeterminado de la sesión, configura tools.exec.host=node o /exec host=node ... explícitamente.
Relacionado:
Invocar comandos
Bajo nivel (RPC sin procesar):Capturas de pantalla (instantáneas de canvas)
Si el Node está mostrando 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 URL o rutas de archivo 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 (camera del Node)
Fotos (jpg):
mp4):
- El Node 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 cargas útiles base64 demasiado grandes. - Android solicitará permisos
CAMERA/RECORD_AUDIOcuando sea posible; los permisos denegados fallan con*_PERMISSION_REQUIRED.
Grabaciones de pantalla (Nodes)
Los Nodes compatibles exponenscreen.record (mp4). Ejemplo:
- La disponibilidad de
screen.recorddepende de la plataforma del Node. - Las grabaciones de pantalla se limitan a
<= 60s. --no-audiodesactiva la captura de micrófono en las plataformas compatibles.- Usa
--screen <index>para seleccionar una pantalla cuando haya varias disponibles.
Ubicación (Nodes)
Los Nodes exponenlocation.get cuando la ubicación está habilitada en la configuración.
Helper de CLI:
- La ubicación está desactivada de forma predeterminada.
- “Always” 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 (Nodes Android)
Los Nodes 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 se anuncie la capacidad.
- Los dispositivos solo con Wi‑Fi y sin telefonía no anunciarán
sms.send.
Comandos de dispositivo Android + datos personales
Los Nodes 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 limitados por capacidad según los sensores disponibles.
Comandos del sistema (host de Node / Node de Mac)
El Node de macOS exponesystem.run, system.notify y system.execApprovals.get/set.
El host de Node headless 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 explícitos de Node. nodes invokeno exponesystem.runnisystem.run.prepare; ambos permanecen solo en la ruta de exec.- La ruta de 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 posterior de comando/cwd/sesión editado por el emisor. system.notifyrespeta el estado de permiso de notificaciones en la app de macOS.- La metadata
platform/deviceFamilyde Node no reconocida usa una allowlist predeterminada conservadora que excluyesystem.runysystem.which. Si intencionadamente necesitas esos comandos para una plataforma desconocida, añádelos explícitamente mediantegateway.nodes.allowCommands. system.runadmite--cwd,--env KEY=VAL,--command-timeouty--needs-screen-recording.- Para wrappers de shell (
bash|sh|zsh ... -c/-lc), los valores--envcon 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) conservan rutas de ejecutables internos en lugar de rutas del wrapper. Si no es seguro desempaquetar, no se conserva automáticamente ninguna entrada en la allowlist. - En hosts de Node Windows en modo allowlist, las ejecuciones con wrapper de shell mediante
cmd.exe /crequieren aprobación (una entrada en allowlist por sí sola no permite automáticamente la forma wrapper). system.notifyadmite--priority <passive|active|timeSensitive>y--delivery <system|overlay|auto>.- Los hosts de Node ignoran anulaciones de
PATHy eliminan claves peligrosas de arranque/shell (DYLD_*,LD_*,NODE_OPTIONS,PYTHON*,PERL*,RUBYOPT,SHELLOPTS,PS4). Si necesitas entradas adicionales en PATH, configura el entorno del servicio del host de Node (o instala herramientas en ubicaciones estándar) en lugar de pasarPATHmediante--env. - En modo Node de macOS,
system.runestá controlado por aprobaciones de exec en la app de macOS (Configuración → Aprobaciones de exec). Ask/allowlist/full se comportan igual que en el host de Node headless; los prompts denegados devuelvenSYSTEM_RUN_DENIED. - En el host de Node headless,
system.runestá controlado por aprobaciones de exec (~/.openclaw/exec-approvals.json).
Vinculación de exec a Node
Cuando hay varios Nodes disponibles, puedes vincular exec a un Node específico. Esto establece el Node predeterminado paraexec host=node (y puede anularse por agente).
Predeterminado global:
Mapa de permisos
Los Nodes 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 Node headless (multiplataforma)
OpenClaw puede ejecutar un host de Node headless (sin UI) que se conecta al WebSocket del Gateway y exponesystem.run / system.which. Esto resulta útil en Linux/Windows
o para ejecutar un Node mínimo junto a un servidor.
Inícialo:
- El emparejamiento sigue siendo obligatorio (el Gateway mostrará un prompt de emparejamiento de dispositivo).
- El host de Node almacena su id de Node, token, nombre visible e información de conexión del gateway en
~/.openclaw/node.json. - Las aprobaciones de exec se aplican localmente mediante
~/.openclaw/exec-approvals.json(consulta Aprobaciones de exec). - En macOS, el host de Node headless ejecuta
system.runlocalmente de forma predeterminada. ConfiguraOPENCLAW_NODE_EXEC_HOST=apppara enrutarsystem.runa través del host exec de la app complementaria; añadeOPENCLAW_NODE_EXEC_FALLBACK=0para exigir el host de la app y fallar en modo cerrado si no está disponible. - Añade
--tls/--tls-fingerprintcuando el WS del Gateway use TLS.
Modo Node de Mac
- La app de barra de menús de macOS se conecta al servidor WS del Gateway como un Node (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.