​

Acesso remoto (SSH, túneis e tailnets)

• Para operadores (você / o app do macOS): o tunelamento SSH é o fallback universal.
• Para nós (iOS/Android e dispositivos futuros): conecte-se ao WebSocket do Gateway (LAN/tailnet ou túnel SSH, conforme necessário).

​

A ideia central

• O WebSocket do Gateway faz bind em loopback na porta configurada (o padrão é 18789).
• Para uso remoto, você encaminha essa porta loopback por SSH (ou usa uma tailnet/VPN e depende menos de túneis).

​

Configurações comuns de VPN/tailnet (onde o agente fica)

​

1) Gateway sempre ativo na sua tailnet (VPS ou servidor doméstico)

• Melhor UX: mantenha gateway.bind: "loopback" e use Tailscale Serve para a Control UI.
• Fallback: mantenha loopback + túnel SSH a partir de qualquer máquina que precise de acesso.
• Exemplos: exe.dev (VM fácil) ou Hetzner (VPS de produção).

​

2) O desktop de casa executa o Gateway, o laptop é o controle remoto

• Use o modo Remote over SSH do app do macOS (Configurações → Geral → “Onde o OpenClaw é executado”).
• O app abre e gerencia o túnel, então WebChat + verificações de integridade “simplesmente funcionam”.

​

3) O laptop executa o Gateway, acesso remoto a partir de outras máquinas

• Túnel SSH para o laptop a partir de outras máquinas, ou
• Use Tailscale Serve para a Control UI e mantenha o Gateway apenas em loopback.

​

Fluxo de comando (o que é executado onde)

• A mensagem do Telegram chega ao Gateway.
• O Gateway executa o agente e decide se deve chamar uma ferramenta de nó.
• O Gateway chama o nó pelo WebSocket do Gateway (node.* RPC).
• O nó retorna o resultado; o Gateway responde de volta no Telegram.

• Nós não executam o serviço do gateway. Apenas um gateway deve ser executado por host, a menos que você esteja intencionalmente executando perfis isolados (consulte Multiple gateways).
• O “modo nó” do app do macOS é apenas um cliente de nó sobre o WebSocket do Gateway.

​

Túnel SSH (CLI + ferramentas)

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

• openclaw health e openclaw status --deep agora alcançam o gateway remoto via ws://127.0.0.1:18789.
• openclaw gateway status, openclaw gateway health, openclaw gateway probe e openclaw gateway call também podem apontar para a URL encaminhada via --url, quando necessário.

​

Padrões remotos da CLI

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

​

Precedência de credenciais

• Credenciais explícitas (--token, --password ou a ferramenta gatewayToken) sempre vencem em caminhos de call que aceitam autenticação explícita.
• Segurança em substituições de URL:
  • Substituições de URL da CLI (--url) nunca reutilizam credenciais implícitas de config/env.
  • Substituições de URL por env (OPENCLAW_GATEWAY_URL) podem usar apenas credenciais de env (OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD).
• Padrões do modo local:
  • token: OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token -> gateway.remote.token (o fallback remoto se aplica apenas quando a entrada local de token de autenticação não está definida)
  • senha: OPENCLAW_GATEWAY_PASSWORD -> gateway.auth.password -> gateway.remote.password (o fallback remoto se aplica apenas quando a entrada local de senha de autenticação não está definida)
• Padrões do modo remoto:
  • token: gateway.remote.token -> OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token
  • senha: OPENCLAW_GATEWAY_PASSWORD -> gateway.remote.password -> gateway.auth.password
• Exceção do host do nó no modo local: gateway.remote.token / gateway.remote.password são ignorados.
• As verificações de token em probe/status remotos são estritas por padrão: usam apenas gateway.remote.token (sem fallback para token local) ao apontar para o modo remoto.
• Substituições de env do Gateway usam apenas OPENCLAW_GATEWAY_*.

​

UI de chat via SSH

• Encaminhe 18789 por SSH (veja acima), depois conecte os clientes a ws://127.0.0.1:18789.
• No macOS, prefira o modo “Remote over SSH” do app, que gerencia o túnel automaticamente.

​

App do macOS “Remote over SSH”

​

Regras de segurança (remoto/VPN)

• Loopback + SSH/Tailscale Serve é o padrão mais seguro (sem exposição pública).
• ws:// em texto simples é apenas loopback por padrão. Para redes privadas confiáveis, defina OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 no processo cliente como break-glass.
• Binds fora de loopback (lan/tailnet/custom, ou auto quando loopback não está disponível) devem usar autenticação do gateway: token, senha ou um proxy reverso com reconhecimento de identidade com gateway.auth.mode: "trusted-proxy".
• gateway.remote.token / .password são fontes de credenciais do cliente. Eles não configuram autenticação do servidor por si só.
• Caminhos de chamada locais podem usar gateway.remote.* como fallback apenas quando gateway.auth.* não está definido.
• Se gateway.auth.token / gateway.auth.password estiver explicitamente configurado via SecretRef e não resolvido, a resolução falha em modo fechado (sem mascaramento por fallback remoto).
• gateway.remote.tlsFingerprint fixa o certificado TLS remoto ao usar wss://.
• Tailscale Serve pode autenticar tráfego da Control UI/WebSocket via cabeçalhos de identidade quando gateway.auth.allowTailscale: true; endpoints da API HTTP não usam essa autenticação por cabeçalho do Tailscale e, em vez disso, seguem o modo normal de autenticação HTTP do gateway. Esse fluxo sem token presume que o host do gateway é confiável. Defina como false se você quiser autenticação por segredo compartilhado em todos os lugares.
• A autenticação trusted-proxy é apenas para configurações fora de loopback com proxy reverso e reconhecimento de identidade. Proxies reversos loopback no mesmo host não satisfazem gateway.auth.mode: "trusted-proxy".
• Trate o controle pelo navegador como acesso de operador: somente tailnet + pairing deliberado de nós.

​

macOS: túnel SSH persistente via LaunchAgent

​

Etapa 1: adicionar configuração SSH

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

​

Etapa 2: copiar a chave SSH (uma vez)

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

​

Etapa 3: configurar o token do gateway

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

​

Etapa 4: criar o LaunchAgent

<?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>

​

Etapa 5: carregar o LaunchAgent

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

​

Solução de problemas

ps aux | grep "ssh -N remote-gateway" | grep -v grep
lsof -i :18789

launchctl kickstart -k gui/$UID/ai.openclaw.ssh-tunnel

launchctl bootout gui/$UID/ai.openclaw.ssh-tunnel