openclaw node

Ejecuta un host de nodo headless que se conecta al WebSocket del Gateway y expone system.run / system.which en esta máquina.

¿Por qué usar un host de nodo?

Usa un host de nodo cuando quieras que los agentes ejecuten comandos en otras máquinas de tu red sin instalar la aplicación companion completa de macOS allí.

Casos de uso comunes:

• Ejecutar comandos en máquinas Linux/Windows remotas (servidores de compilación, máquinas de laboratorio, NAS).
• Mantener la ejecución en sandbox en el gateway, pero delegar ejecuciones aprobadas a otros hosts.
• Proporcionar un objetivo de ejecución headless y ligero para automatización o nodos de CI.

La ejecución sigue protegida por aprobaciones de ejecución y listas de permitidos por agente en el host de nodo, para que puedas mantener el acceso a comandos acotado y explícito.

Proxy de navegador (sin configuración)

Los hosts de nodo anuncian automáticamente un proxy de navegador si browser.enabled no está desactivado en el nodo. Esto permite que el agente use automatización de navegador en ese nodo sin configuración adicional.

Desactívalo en el nodo si es necesario:

{
  nodeHost: {
    browserProxy: {
      enabled: false,
    },
  },
}

Ejecutar (primer plano)

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

Opciones:

• --host <host>: host del WebSocket del Gateway (por defecto: 127.0.0.1)
• --port <port>: puerto del WebSocket del Gateway (por defecto: 18789)
• --tls: usar TLS para la conexión al gateway
• --tls-fingerprint <sha256>: huella digital esperada del certificado TLS (sha256)
• --node-id <id>: sustituir el id del nodo (borra el token de emparejamiento)
• --display-name <name>: sustituir el nombre visible del nodo

Autenticación del gateway para el host de nodo

openclaw node run y openclaw node install resuelven la autenticación del gateway desde la configuración/entorno (sin flags --token/--password en los comandos de nodo):

• Se comprueban primero OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD.
• Luego el fallback de configuración local: gateway.auth.token / gateway.auth.password.
• En modo local, el host de nodo intencionalmente no hereda gateway.remote.token / gateway.remote.password.
• Si gateway.auth.token / gateway.auth.password está configurado explícitamente mediante SecretRef y no se puede resolver, la resolución de autenticación del nodo falla de forma cerrada (sin fallback remoto enmascarado).
• En gateway.mode=remote, los campos del cliente remoto (gateway.remote.token / gateway.remote.password) también son elegibles según las reglas de precedencia remota.
• Las variables de entorno legacy CLAWDBOT_GATEWAY_* se ignoran para la resolución de autenticación del host de nodo.

Servicio (segundo plano)

Instala un host de nodo headless como servicio de usuario.

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

Opciones:

• --host <host>: host del WebSocket del Gateway (por defecto: 127.0.0.1)
• --port <port>: puerto del WebSocket del Gateway (por defecto: 18789)
• --tls: usar TLS para la conexión al gateway
• --tls-fingerprint <sha256>: huella digital esperada del certificado TLS (sha256)
• --node-id <id>: sustituir el id del nodo (borra el token de emparejamiento)
• --display-name <name>: sustituir el nombre visible del nodo
• --runtime <runtime>: runtime del servicio (node o bun)
• --force: reinstalar/sobrescribir si ya está instalado

Gestionar el servicio:

openclaw node status
openclaw node stop
openclaw node restart
openclaw node uninstall

Usa openclaw node run para un host de nodo en primer plano (sin servicio).

Los comandos de servicio aceptan --json para salida legible por máquinas.

Emparejamiento

La primera conexión crea una solicitud de emparejamiento pendiente (role: node) en el Gateway. Apruébala mediante:

openclaw devices list
openclaw devices approve <requestId>

El host de nodo almacena su id de nodo, token, nombre visible e información de conexión al gateway en ~/.openclaw/node.json.

Aprobaciones de ejecución

system.run está regulado por aprobaciones de ejecución locales:

• ~/.openclaw/exec-approvals.json
• Exec approvals
• openclaw approvals --node <id|name|ip> (editar desde el Gateway)