Saltar al contenido principal

Acceso remoto

Acceso Remoto

Este repositorio admite el "acceso remoto por SSH" manteniendo un único Gateway (el maestro) ejecutándose en un host dedicado (escritorio/servidor) y conectando clientes a él.

  • Para operadores (tú / la aplicación de macOS): el túnel SSH es el respaldo universal.
  • Para nodos (iOS/Android y dispositivos futuros): conéctate al WebSocket del Gateway (LAN/tailnet o túnel SSH según sea necesario).

La idea central​

  • El WebSocket del Gateway se vincula a loopback en el puerto configurado (por defecto 18789).
  • Para uso remoto, reenvías ese puerto loopback a través de SSH (o usas una tailnet/VPN y reduces el túnel).

Configuraciones comunes de VPN/tailnet (donde vive el agente)​

Piensa en el host del Gateway como "donde vive el agente". Es dueño de las sesiones, perfiles de autenticación, canales y estado. Tu portátil/escritorio (y los nodos) se conectan a ese host.

1) Gateway siempre activo en tu tailnet (VPS o servidor doméstico)​

Ejecuta el Gateway en un host persistente y accede a él a través de Tailscale o SSH.

  • Mejor experiencia de usuario: mantén gateway.bind: "loopback" y usa Tailscale Serve para la Interfaz de Control.
  • Respaldo: mantén loopback + túnel SSH desde cualquier máquina que necesite acceso.
  • Ejemplos: exe.dev (VM fácil) o Hetzner (VPS de producción).

Esto es ideal cuando tu portátil se suspende a menudo pero quieres que el agente esté siempre activo.

2) El escritorio doméstico ejecuta el Gateway, el portátil es control remoto​

El portátil no ejecuta el agente. Se conecta de forma remota:

  • Usa el modo Remoto por SSH de la aplicación de macOS (Configuración → General → "OpenClaw runs").
  • La aplicación abre y gestiona el túnel, por lo que WebChat + comprobaciones de estado "simplemente funcionan".

Procedimiento: Acceso remoto en macOS.

3) El portátil ejecuta el Gateway, acceso remoto desde otras máquinas​

Mantén el Gateway local pero exponlo de forma segura:

  • Túnel SSH al portátil desde otras máquinas, o
  • Usa Tailscale Serve para la Interfaz de Control y mantén el Gateway solo en loopback.

Guía: Tailscale y Vista general web.

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

Un servicio de gateway posee el estado + canales. Los nodos son periféricos. Ejemplo de flujo (Telegram → nodo):

  • El mensaje de Telegram llega al Gateway.
  • El Gateway ejecuta el agente y decide si llamar a una herramienta del nodo.
  • El Gateway llama al nodo a través del WebSocket del Gateway (RPC node.*).
  • El nodo devuelve el resultado; el Gateway responde de vuelta a Telegram.

Notas:

  • Los nodos no ejecutan el servicio de gateway. Solo un gateway debe ejecutarse por host a menos que ejecutes perfiles aislados intencionalmente (ver Múltiples gateways).
  • El "modo nodo" de la aplicación de macOS es solo un cliente nodo sobre el WebSocket del Gateway.

Túnel SSH (CLI + herramientas)​

Crea un túnel local al WebSocket del Gateway remoto:

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

Con el túnel activo:

  • openclaw health y openclaw status --deep ahora alcanzan el gateway remoto a través de ws://127.0.0.1:18789.
  • openclaw gateway {status,health,send,agent,call} también pueden apuntar a la URL reenviada mediante --url cuando sea necesario.

Nota: reemplaza 18789 con tu gateway.port configurado (o --port/OPENCLAW_GATEWAY_PORT). Nota: cuando pasas --url, la CLI no recurre a las credenciales de configuración o entorno. Incluye --token o --password explícitamente. La falta de credenciales explícitas es un error.

Valores predeterminados remotos de la CLI​

Puedes persistir un destino remoto para que los comandos de la CLI lo usen por defecto:

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

Cuando el gateway es solo loopback, mantén la URL en ws://127.0.0.1:18789 y abre primero el túnel SSH.

Precedencia de credenciales​

La resolución de credenciales para llamadas/sondeos del Gateway ahora sigue un contrato compartido:

  • Las credenciales explícitas (--token, --password, o gatewayToken de la herramienta) siempre ganan.
  • Valores predeterminados del modo local:
    • token: OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token -> gateway.remote.token
    • password: OPENCLAW_GATEWAY_PASSWORD -> gateway.auth.password -> gateway.remote.password
  • Valores predeterminados del modo remoto:
    • token: gateway.remote.token -> OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token
    • password: OPENCLAW_GATEWAY_PASSWORD -> gateway.remote.password -> gateway.auth.password
  • Las comprobaciones de token para sondeos/estado remotos son estrictas por defecto: usan solo gateway.remote.token (sin recurrir al token local) cuando se apunta al modo remoto.
  • Las variables de entorno heredadas CLAWDBOT_GATEWAY_* solo son usadas por rutas de llamada de compatibilidad; la resolución de sondeo/estado/autenticación usa solo OPENCLAW_GATEWAY_*.

Interfaz de chat sobre SSH​

WebChat ya no usa un puerto HTTP separado. La interfaz de chat SwiftUI se conecta directamente al WebSocket del Gateway.

  • Reenvía 18789 a través de SSH (ver arriba), luego conecta clientes a ws://127.0.0.1:18789.
  • En macOS, prefiere el modo "Remoto por SSH" de la aplicación, que gestiona el túnel automáticamente.

Aplicación de macOS "Remoto por SSH"​

La aplicación de la barra de menús de macOS puede impulsar la misma configuración de extremo a extremo (comprobaciones de estado remotas, WebChat y reenvío de Voice Wake). Procedimiento: Acceso remoto en macOS.

Reglas de seguridad (remoto/VPN)​

Versión corta: mantén el Gateway solo en loopback a menos que estés seguro de que necesitas un enlace.

  • Loopback + SSH/Tailscale Serve es el valor predeterminado más seguro (sin exposición pública).
  • El texto plano ws:// es solo loopback por defecto. Para redes privadas confiables, establece OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 en el proceso cliente como medida de emergencia.
  • Los enlaces no loopback (lan/tailnet/custom, o auto cuando loopback no está disponible) deben usar tokens/contraseñas de autenticación.
  • gateway.remote.token / .password son fuentes de credenciales del cliente. Por sí solas no configuran la autenticación del servidor.
  • Las rutas de llamada local pueden usar gateway.remote.* como respaldo cuando gateway.auth.* no está establecido.
  • gateway.remote.tlsFingerprint fija el certificado TLS remoto cuando se usa wss://.
  • Tailscale Serve puede autenticar el tráfico de la Interfaz de Control/WebSocket a través de cabeceras de identidad cuando gateway.auth.allowTailscale: true; los endpoints de la API HTTP aún requieren autenticación por token/contraseña. Este flujo sin token asume que el host del gateway es confiable. Establécelo en false si quieres tokens/contraseñas en todas partes.
  • Trata el control del navegador como acceso de operador: solo tailnet + emparejamiento deliberado de nodos.

Profundización: Seguridad.

Descubrimiento BonjourConfiguración de Gateway Remoto