Saltar para o conteúdo principal

​
Acesso remoto (SSH, túneis e tailnets)

Este repositório oferece suporte a “remoto via SSH” mantendo um único Gateway (o mestre) em execução em um host dedicado (desktop/servidor) e conectando clientes a ele.
  • Para operadores (você / o app macOS): o tunelamento SSH é o fallback universal.
  • Para nós (iOS/Android e dispositivos futuros): conectar ao WebSocket do Gateway (LAN/tailnet ou túnel SSH conforme necessário).

​
A ideia central

  • O WebSocket do Gateway se liga ao loopback na porta configurada (padrão 18789).
  • Para uso remoto, você encaminha essa porta de loopback via SSH (ou usa uma tailnet/VPN e reduz a necessidade de túneis).

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

Pense no host do Gateway como “onde o agente vive”. Ele é dono de sessões, perfis de autenticação, canais e estado. Seu laptop/desktop (e nós) se conectam a esse host.

​
1. Gateway sempre ligado na sua tailnet (VPS ou servidor doméstico)

Execute o Gateway em um host persistente e acesse-o via Tailscale ou SSH.
  • Melhor UX: mantenha gateway.bind: "loopback" e use Tailscale Serve para a UI de Controle.
  • 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).
Isso é ideal quando seu laptop entra em repouso com frequência, mas você quer o agente sempre ativo.

​
2. Desktop de casa executa o Gateway, laptop é controle remoto

O laptop não executa o agente. Ele se conecta remotamente:
  • Use o modo Remote over SSH do app macOS (Ajustes → Geral → “OpenClaw runs”).
  • O app abre e gerencia o túnel, então WebChat + verificações de saúde “simplesmente funcionam”.
Runbook: acesso remoto no macOS.

​
3. Laptop executa o Gateway, acesso remoto a partir de outras máquinas

Mantenha o Gateway local, mas exponha-o com segurança:
  • Túnel SSH para o laptop a partir de outras máquinas, ou
  • Tailscale Serve para a UI de Controle e mantenha o Gateway apenas em loopback.
Guia: Tailscale e Visão geral da Web.

​
Fluxo de comandos (o que roda onde)

Um serviço de gateway é dono de estado + canais. Nós são periféricos. Exemplo de fluxo (Telegram → nó):
  • 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ó via WebSocket do Gateway (RPC node.*).
  • O nó retorna o resultado; o Gateway responde de volta ao Telegram.
Notas:
  • Nós não executam o serviço de gateway. Apenas um gateway deve rodar por host, a menos que você execute intencionalmente perfis isolados (veja Múltiplos gateways).
  • O “modo nó” do app macOS é apenas um cliente de nó via WebSocket do Gateway.

​
Túnel SSH (CLI + ferramentas)

Crie um túnel local para o WS remoto do Gateway: 
ssh -N -L 18789:127.0.0.1:18789 user@host
Com o túnel ativo:
  • openclaw health e openclaw status --deep agora alcançam o gateway remoto via ws://127.0.0.1:18789.
  • openclaw gateway {status,health,send,agent,call} também pode apontar para a URL encaminhada via --url quando necessário.
Nota: substitua 18789 pelo seu gateway.port configurado (ou --port/OPENCLAW_GATEWAY_PORT). Nota: ao passar --url, a CLI não faz fallback para credenciais de configuração ou de ambiente. Inclua --token ou --password explicitamente. A ausência de credenciais explícitas é um erro.

​
Padrões remotos da CLI

Você pode persistir um destino remoto para que os comandos da CLI o usem por padrão: 
{
  gateway: {
    mode: "remote",
    remote: {
      url: "ws://127.0.0.1:18789",
      token: "your-token",
    },
  },
}
Quando o gateway é apenas loopback, mantenha a URL em ws://127.0.0.1:18789 e abra o túnel SSH primeiro.

​
UI de chat via SSH

O WebChat não usa mais uma porta HTTP separada. A UI de chat em SwiftUI conecta-se diretamente ao WebSocket do Gateway.
  • Encaminhe 18789 via SSH (veja acima) e, em seguida, 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 macOS “Remote over SSH”

O app da barra de menus do macOS pode conduzir a mesma configuração de ponta a ponta (verificações de status remoto, WebChat e encaminhamento de Voice Wake). Runbook: acesso remoto no macOS.

​
Regras de segurança (remoto/VPN)

Versão curta: mantenha o Gateway apenas em loopback a menos que você tenha certeza de que precisa de um bind.
  • Loopback + SSH/Tailscale Serve é o padrão mais seguro (sem exposição pública).
  • Binds não-loopback (lan/tailnet/custom, ou auto quando loopback não está disponível) devem usar tokens/senhas de autenticação.
  • gateway.remote.token é apenas para chamadas remotas da CLI — não habilita autenticação local.
  • gateway.remote.tlsFingerprint fixa o certificado TLS remoto ao usar wss://.
  • Tailscale Serve pode autenticar via cabeçalhos de identidade quando gateway.auth.allowTailscale: true. Defina como false se você quiser tokens/senhas em vez disso.
  • Trate o controle pelo navegador como acesso de operador: apenas tailnet + pareamento deliberado de nós.
Aprofundamento: Segurança.