Acceso Remoto
Acceso remoto via túneles SSH (Gateway WS) y tailnet.
Este repositorio soporta "remoto sobre SSH" ejecutando un único gateway (servidor primario) en un host dedicado (desktop/servidor), con clientes conectándose a él.
- Para operadores (tú/app macOS): túnel SSH es el fallback universal.
- Para nodos (iOS/Android y dispositivos futuros): conectan al WebSocket del gateway (usando LAN/tailnet o túnel SSH según sea necesario).
Idea central
- El WebSocket del gateway se vincula a loopback en un puerto configurado (predeterminado 18789).
- Para uso remoto, puedes reenviar ese puerto loopback via SSH (o usar tailnet/VPN para reducir túneles).
Configuración común VPN/tailnet (donde vive el agente)
Piensa en el host del gateway como "donde vive el agente." Tiene sesiones, perfiles de auth, canales, y estado.
Laptops/desktops (y nodos) se conectan a ese host.
#
1) Gateway siempre en línea en tailnet (VPS o servidor casero)
Ejecuta el gateway en un host persistente y accede via Tailscale o SSH.
- ''Mejor UX:'' mantén ''gateway.bind: "loopback"'' y usa ''Tailscale Serve'' para la UI de control.
- Fallback: mantén loopback + túnel SSH desde máquinas que necesitan acceso.
- ''Ejemplos:'' ''exe.dev'' (VM simple) o ''Hetzner'' (VPS de producción).
Genial si tu laptop duerme a menudo pero quieres el agente siempre en línea.
#
2) Ejecutar gateway en desktop casero, control remoto desde laptop
La laptop no ejecuta el agente. Se conecta remotamente:
- Usa el modo Remoto sobre SSH de la app macOS (Configuración → General → "Donde se ejecuta OpenClaw").
- La app abre y gestiona el túnel para que WebChat + verificaciones de salud "simplemente funcionen."
Runbook: ''Acceso remoto macOS''.
#
3) Ejecutar gateway en laptop, acceso remoto desde otras máquinas
Mantén el gateway local pero expónlo de forma segura:
- Túnel SSH desde otras máquinas a la laptop, o
- Tailscale serve para UI de control y gateway solo loopback.
Guía: ''Tailscale'' y ''resumen de red''.
Flujo de comandos (qué se ejecuta dónde)
Un único servicio de gateway posee estado + canales. Los nodos son periféricos.
Flujo de ejemplo (Telegram → nodo):
- Mensaje de Telegram llega al gateway.
- El gateway ejecuta el agente, decide si invocar herramientas de nodo.
- El gateway invoca el ''nodo'' via WebSocket del gateway (''node.*'' RPC).
- El nodo retorna resultado. El gateway responde a Telegram.
Nota:
- ''Los nodos no ejecutan el servicio gateway.'' Un gateway por host a menos que deliberadamente ejecutes perfiles aislados (ver ''múltiples gateways'').
- El "modo nodo" de la app macOS es solo un cliente de nodo en el WebSocket del gateway.
Túnel SSH (CLI + herramientas)
Crea un túnel local a un gateway WS remoto:
ssh -N -L 18789:127.0.0.1:18789 user@host
Una vez establecido el túnel:
- ''openclaw health'' y ''openclaw status --deep'' alcanzan el gateway remoto via ''ws://127.0.0.1:18789''.
- openclaw gateway {status,health,send,agent,call}' también pueden apuntar a la URL reenviada via --url si es necesario.
Nota: Reemplaza ''18789'' con tu ''gateway.port'' configurado (o ''--port''/''OPENCLAW_GATEWAY_PORT'').
Predeterminados remotos de CLI
Puedes persistir un objetivo remoto para que los comandos CLI lo usen por defecto:
{
gateway: {
mode: "remote",
remote: {
url: "ws://127.0.0.1:18789",
token: "tu-token",
},
},
}Si el gateway es solo loopback, mantén la URL como ''ws://127.0.0.1:18789'' y abre el túnel SSH primero.
UI de Chat sobre SSH
WebChat ya no usa un puerto HTTP separado. La UI de chat SwiftUI se conecta directamente al WebSocket del gateway.
- Reenvía ''18789'' via SSH (ver arriba), luego conecta el cliente a ''ws://127.0.0.1:18789''.
- En macOS, prefiere el modo "Remoto sobre SSH" de la app que gestiona el túnel automáticamente.
App macOS "Remoto sobre SSH"
La app de barra de menú macOS puede manejar la misma configuración de extremo a extremo (verificaciones de salud remotas, WebChat, reenvío de activación por voz).
Runbook: ''Acceso remoto macOS''.
Reglas de seguridad (remoto/VPN)
TL;DR: mantén el gateway solo loopback a menos que necesites vincularlo de otra manera.
- Loopback + SSH/Tailscale Serve es el predeterminado más seguro (sin exposición pública).
- ''Vinculación no loopback'' (''lan''/''tailnet''/''custom'' o ''auto'' cuando loopback no está disponible) requiere token/contraseña de auth.
- ''gateway.remote.token'' es para llamadas CLI remotas ''solamente'' — no habilita auth local.
- Si usas ''wss://'', ''gateway.remote.tlsFingerprint'' fija el certificado TLS remoto.
- ''Tailscale Serve'' puede autenticar via headers de identidad si ''gateway.auth.allowTailscale: true''.
Establece en ''false'' si quieres que se requiera auth de token/contraseña.
- Trata el control del navegador como acceso de operador: solo tailnet + emparejamiento intencional de nodo.
Detalles: ''Seguridad''.