Acceso remoto

OpenClaw ejecuta un Gateway (el principal) en un host y conecta todos los clientes a él. El Gateway administra las sesiones, los perfiles de autenticación, los canales y el estado; todo lo demás es un cliente.

• Operadores (usted o la aplicación de macOS): una conexión WebSocket directa por LAN/tailnet es la opción más sencilla cuando se puede acceder al Gateway; el túnel SSH es la alternativa universal.
• Nodes (iOS/Android y otros dispositivos): se conectan al WebSocket del Gateway (mediante LAN/tailnet o un túnel SSH).

La idea central

De forma predeterminada, el WebSocket del Gateway se vincula a loopback en el puerto 18789 (gateway.port). Para usarlo de forma remota, expóngalo mediante Tailscale Serve o una vinculación de LAN/tailnet de confianza, o reenvíe el puerto de loopback mediante SSH.

Opciones de topología

Para las configuraciones de Gateway siempre activo y portátil, es preferible mantener gateway.bind: "loopback" y usar Tailscale Serve para la interfaz de control, o una vinculación de LAN/tailnet de confianza con gateway.remote.transport: "direct". El túnel SSH es la alternativa que funciona desde cualquier máquina.

Flujo de comandos (qué se ejecuta y dónde)

Un Gateway administra el estado y los canales; los Nodes son periféricos. Ejemplo (mensaje de Telegram dirigido a una herramienta de Node):

1. El mensaje de Telegram llega al Gateway.
2. El Gateway ejecuta el agente, que decide si debe llamar a una herramienta de Node.
3. El Gateway llama al Node mediante el WebSocket del Gateway (RPC node.invoke).
4. El Node devuelve el resultado; el Gateway responde a Telegram.

Los Nodes no ejecutan el servicio Gateway. Solo debe ejecutarse un Gateway por host, salvo que ejecute intencionadamente perfiles aislados (consulte Varios gateways). El «modo Node» de la aplicación de macOS es simplemente un cliente Node que usa el WebSocket del Gateway.

Túnel SSH (CLI + herramientas)

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

Con el túnel activo, openclaw health y openclaw status --deep acceden al Gateway remoto mediante ws://127.0.0.1:18789. openclaw gateway status, openclaw gateway health, openclaw gateway probe y openclaw gateway call también pueden apuntar a una URL reenviada mediante --url.

Valores remotos predeterminados de la CLI

Guarde un destino remoto para que los comandos de la CLI lo usen de forma predeterminada:

{  gateway: {    mode: "remote",    remote: {      url: "ws://127.0.0.1:18789",      token: "your-token",    },  },}

Cuando el Gateway solo use loopback, mantenga la URL como ws://127.0.0.1:18789 y abra primero el túnel SSH. En el transporte mediante túnel SSH de la aplicación de macOS, el nombre de host del Gateway detectado se especifica en gateway.remote.sshTarget (user@host o user@host:port); gateway.remote.url conserva la URL del túnel local. Si el puerto remoto es distinto del local, configure gateway.remote.remotePort.

La verificación de la clave del host es estricta de forma predeterminada (gateway.remote.sshHostKeyPolicy: "strict"). Establézcala en "openssh" para delegarla en su configuración efectiva de OpenSSH; revise la configuración SSH del usuario y del sistema antes de habilitar esta opción.

Para un Gateway al que ya se pueda acceder mediante una LAN o tailnet de confianza, use el modo directo:

{  gateway: {    mode: "remote",    remote: {      transport: "direct",      url: "ws://192.168.0.202:18789",      token: "your-token",    },  },}

Precedencia de credenciales

La resolución de credenciales del Gateway sigue un contrato compartido en las rutas de llamada, sondeo y estado, así como en la supervisión de aprobaciones de ejecución de Discord. El host de Node usa el mismo contrato con una excepción para el modo local (ignora gateway.remote.*).

• Las credenciales explícitas (--token, --password o el gatewayToken de una herramienta) siempre tienen prioridad en las rutas de llamada que aceptan autenticación explícita.
• Seguridad de la sustitución de URL:
  • --url de la CLI nunca reutiliza credenciales implícitas de la configuración o del entorno.
  • OPENCLAW_GATEWAY_URL del entorno solo puede usar credenciales del entorno (OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD).
• Valores predeterminados del modo local:
  • token: OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token -> gateway.remote.token (solo se recurre al valor remoto cuando no se ha establecido el token local)
  • contraseña: OPENCLAW_GATEWAY_PASSWORD -> gateway.auth.password -> gateway.remote.password (solo se recurre al valor remoto cuando no se ha establecido la contraseña local)
• Valores predeterminados del modo remoto:
  • token: gateway.remote.token -> OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token
  • contraseña: OPENCLAW_GATEWAY_PASSWORD -> gateway.remote.password -> gateway.auth.password
• Excepción del modo local del host de Node: se ignoran gateway.remote.token / gateway.remote.password.
• Las comprobaciones del token de sondeo y estado remotos son estrictas de forma predeterminada: al apuntar al modo remoto, solo usan gateway.remote.token (sin recurrir al token local).
• Las sustituciones del entorno del Gateway solo usan OPENCLAW_GATEWAY_*.

Acceso remoto a la interfaz de chat

WebChat no tiene un puerto HTTP independiente; la interfaz de chat de SwiftUI se conecta directamente al WebSocket del Gateway.

• Reenvíe 18789 mediante SSH (consulte la sección anterior) y conecte después los clientes a ws://127.0.0.1:18789.
• Para el modo directo mediante LAN/tailnet, conecte los clientes a la URL privada ws:// o segura wss:// configurada.
• En macOS, el modo remoto de la aplicación administra automáticamente el transporte seleccionado.

Modo remoto de la aplicación de macOS

La aplicación de la barra de menús de macOS gestiona la misma configuración de principio a fin: comprobaciones del estado remoto, WebChat y reenvío de Activación por voz. Guía operativa: acceso remoto de macOS.

Reglas de seguridad (acceso remoto/VPN)

Mantenga el Gateway solo en loopback, salvo que esté seguro de que necesita una vinculación.

• Loopback + SSH/Tailscale Serve es la opción predeterminada más segura (sin exposición pública).
• Se acepta ws:// sin cifrar para loopback, redes privadas/LAN (RFC 1918), direcciones de vínculo local, CGNAT y hosts .local y .ts.net. Los hosts remotos públicos deben usar wss://.
• Las vinculaciones que no sean de loopback (lan/tailnet/custom, o auto cuando loopback no esté disponible) deben usar la autenticación del Gateway: token, contraseña o un proxy inverso con reconocimiento de identidad y gateway.auth.mode: "trusted-proxy".
• gateway.remote.token / .password son fuentes de credenciales del cliente; no configuran por sí mismas la autenticación del servidor.
• Las rutas de llamada locales solo pueden recurrir a gateway.remote.* cuando gateway.auth.* no esté configurado.
• Si gateway.auth.token / gateway.auth.password se configura explícitamente mediante SecretRef y no se puede resolver, la resolución falla de forma cerrada (sin que un valor remoto alternativo oculte el problema).
• gateway.remote.tlsFingerprint fija el certificado TLS remoto para wss://, incluido el modo directo de macOS. Sin una huella almacenada, macOS solo la fija en el primer uso después de superar la validación de confianza normal del sistema; los Gateways autofirmados o con una CA privada necesitan una huella explícita o Remote over SSH.
• Tailscale Serve puede autenticar el tráfico de la interfaz de control/WebSocket mediante encabezados de identidad cuando gateway.auth.allowTailscale: true. Los puntos de conexión de la API HTTP no usan esa autenticación por encabezado y, en su lugar, siguen el modo normal de autenticación HTTP del Gateway. Este flujo sin token presupone que el host del Gateway es de confianza; establézcalo en false para usar autenticación mediante secreto compartido en todas partes.
• La autenticación mediante proxy de confianza espera de forma predeterminada un proxy con reconocimiento de identidad que no use loopback. Los proxies inversos de loopback en el mismo host requieren gateway.auth.trustedProxy.allowLoopback = true de forma explícita.
• Trate el control mediante navegador como acceso de operador: solo mediante tailnet y con un emparejamiento intencionado del Node.

Información detallada: Seguridad.

macOS: túnel SSH persistente mediante LaunchAgent

Para los clientes de macOS, la configuración persistente más sencilla usa una entrada LocalForward en la configuración de SSH, junto con un LaunchAgent que mantiene el túnel activo tras reinicios y fallos.

Paso 1: añadir la configuración de SSH

Edite ~/.ssh/config:

Host remote-gateway    HostName <REMOTE_IP>    User <REMOTE_USER>    LocalForward 18789 127.0.0.1:18789    IdentityFile ~/.ssh/id_rsa

Sustituya <REMOTE_IP> y <REMOTE_USER> por sus valores.

Paso 2: copiar la clave SSH (una sola vez)

ssh-copy-id -i ~/.ssh/id_rsa <REMOTE_USER>@<REMOTE_IP>

Paso 3: configurar el token del Gateway

openclaw config set gateway.remote.token "<your-token>"

Use gateway.remote.password en su lugar si el Gateway remoto utiliza autenticación mediante contraseña. OPENCLAW_GATEWAY_TOKEN sigue siendo válido como sustitución en el entorno del shell, pero la configuración persistente del cliente remoto es gateway.remote.token / gateway.remote.password.

Paso 4: crear el LaunchAgent

Guárdelo como ~/Library/LaunchAgents/ai.openclaw.ssh-tunnel.plist:

<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"><plist version="1.0"><dict>    <key>Label</key>    <string>ai.openclaw.ssh-tunnel</string>    <key>ProgramArguments</key>    <array>        <string>/usr/bin/ssh</string>        <string>-N</string>        <string>remote-gateway</string>    </array>    <key>KeepAlive</key>    <true/>    <key>RunAtLoad</key>    <true/></dict></plist>

Paso 5: cargar el LaunchAgent

launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.openclaw.ssh-tunnel.plist

El túnel se inicia automáticamente al iniciar sesión, se reinicia si falla y mantiene activo el puerto reenviado.

Solución de problemas

# Check if the tunnel is runningps aux | grep "ssh -N remote-gateway" | grep -v greplsof -i :18789 # Restart the tunnellaunchctl kickstart -k gui/$UID/ai.openclaw.ssh-tunnel # Stop the tunnellaunchctl bootout gui/$UID/ai.openclaw.ssh-tunnel

Contenido relacionado

• Tailscale
• Autenticación
• Configuración de un Gateway remoto