Controle remoto

Este fluxo permite que o aplicativo para macOS atue como um controle remoto completo de um Gateway do OpenClaw executado em outro host (desktop/servidor). O aplicativo se conecta diretamente a URLs confiáveis do Gateway na LAN/Tailnet ou gerencia um túnel SSH quando o Gateway remoto está disponível apenas via local loopback. As verificações de integridade, o encaminhamento do Voice Wake e o Web Chat reutilizam a mesma configuração remota de Settings -> General.

Modos

• Local (este Mac): tudo é executado no laptop; não há envolvimento de SSH.
• Remoto via SSH (padrão): os comandos do OpenClaw são executados no host remoto. O aplicativo abre uma conexão SSH com -o BatchMode, a identidade/chave escolhida e um encaminhamento de porta local.
• Remoto direto (ws/wss): sem túnel SSH; o aplicativo se conecta diretamente à URL do Gateway (LAN, Tailscale, Tailscale Serve ou um proxy reverso HTTPS público).

Transportes remotos

• Túnel SSH (padrão): usa ssh -N -L ... para encaminhar a porta do Gateway para o localhost. O Gateway vê o IP do Node como 127.0.0.1 porque o túnel usa local loopback.
• Direto (ws/wss): conecta-se diretamente à URL do Gateway. O Gateway vê o IP real do cliente.

O aplicativo desativa a multiplexação de conexões SSH e a execução em segundo plano após a autenticação em seus próprios processos SSH para poder monitorar e reiniciar o processo exato, mesmo que o alias selecionado habilite ControlMaster ou ForkAfterAuthentication.

A verificação da chave de host SSH é rigorosa por padrão, pois as credenciais do Gateway trafegam por esse túnel. Para aceitar o comportamento de confiança próprio de um alias SSH gerenciado, defina --ssh-host-key-policy openssh por meio de openclaw-mac configure-remote ou defina gateway.remote.sshHostKeyPolicy diretamente como "openssh". Revise o alias e qualquer configuração correspondente de Host * ou do sistema antes de aceitar. Alterar o destino SSH (no aplicativo ou por meio de configure-remote) redefine a política como strict, a menos que você a habilite explicitamente outra vez para o novo destino.

No modo de túnel SSH, os nomes de host descobertos na LAN/Tailnet são salvos como gateway.remote.sshTarget. O aplicativo mantém gateway.remote.url no endpoint do túnel local (por exemplo, ws://127.0.0.1:18789) para que a CLI, o Web Chat e o serviço local de host do Node usem o mesmo transporte via local loopback. Quando a descoberta retorna tanto IPs brutos da Tailnet quanto nomes de host estáveis, o aplicativo prefere nomes do Tailscale MagicDNS ou da LAN para que as conexões resistam melhor a mudanças de endereço. Se a porta do túnel local for diferente da porta do Gateway remoto, defina gateway.remote.remotePort como a porta no host remoto.

A automação do navegador no modo remoto pertence ao host do Node da CLI, não ao Node nativo do aplicativo para macOS. O aplicativo inicia o serviço de host do Node instalado quando possível; para habilitar o controle do navegador a partir desse Mac, instale/inicie-o com openclaw node install ... e openclaw node start (ou execute openclaw node run ... em primeiro plano) e, em seguida, selecione esse Node com capacidade de navegador como destino.

Pré-requisitos no host remoto

1. Instale Node + pnpm e compile/instale a CLI do OpenClaw (pnpm install && pnpm build && pnpm link --global).
2. Verifique se openclaw está no PATH para shells não interativos (crie um link simbólico em /usr/local/bin ou /opt/homebrew/bin, se necessário).
3. Para o transporte SSH: configure a autenticação SSH baseada em chave. Recomendam-se IPs do Tailscale para manter a conectividade estável fora da LAN.

Configuração do aplicativo para macOS

Para pré-configurar o aplicativo sem o fluxo de boas-vindas, via SSH:

openclaw-mac configure-remote \  --ssh-target user@gateway-host \  --local-port 18789 \  --remote-port 18789 \  --token "$OPENCLAW_GATEWAY_TOKEN"

Ou, para um Gateway que já possa ser acessado em uma LAN ou Tailnet confiável, ignore completamente o SSH:

openclaw-mac configure-remote \  --direct-url ws://192.168.0.202:18789 \  --token "$OPENCLAW_GATEWAY_TOKEN"

Ambas as formas gravam ~/.openclaw/openclaw.json, marcam a integração inicial como concluída e permitem que o aplicativo controle o transporte selecionado na próxima inicialização. O padrão de --local-port/--remote-port é 18789. Outras opções: --password, --identity <path>, --ssh-host-key-policy <strict|openssh>, --project-root <path>, --cli-path <path>, --json. Execute openclaw-mac configure-remote --help para ver a referência completa.

Como alternativa, para configurar pela interface:

1. Abra Settings -> General.
2. Em OpenClaw runs, escolha Remote e defina:
   • Transport: SSH tunnel ou Direct (ws/wss).
   • SSH target: user@host (:port opcional). Se o Gateway estiver na mesma LAN e anunciar via Bonjour, selecione-o na lista descoberta para preencher este campo automaticamente.
   • Gateway URL (somente Direct): wss://gateway.example.ts.net (ou ws://... para local/LAN).
   • Identity file (avançado): caminho para sua chave.
   • Project root (avançado): caminho do checkout remoto usado para comandos.
   • CLI path (avançado): caminho opcional para um ponto de entrada/binário executável de openclaw (preenchido automaticamente quando anunciado).
3. Selecione Test remote. O sucesso significa que o comando remoto openclaw status --json foi executado corretamente. As falhas geralmente indicam problemas no PATH/CLI; o código de saída 127 significa que a CLI não foi encontrada remotamente.
4. As verificações de integridade e o Web Chat agora usam automaticamente o transporte selecionado.

Web Chat

• Túnel SSH: conecta-se ao Gateway pela porta de controle WebSocket encaminhada (padrão: 18789).
• Direto (ws/wss): conecta-se diretamente à URL configurada do Gateway.
• Não há um servidor HTTP separado para o Web Chat.

Permissões

• O host remoto precisa das mesmas aprovações do TCC que o local (Automation, Accessibility, Screen Recording, Microphone, Speech Recognition, Notifications). Execute a integração inicial nessa máquina uma vez para concedê-las.
• Os Nodes anunciam seu estado de permissões por meio de node.list / node.describe para que os agentes saibam o que está disponível.

Observações de segurança

• Prefira associações a local loopback no host remoto e conecte-se via SSH, Tailscale Serve ou uma URL direta confiável da Tailnet/LAN.
• Por padrão, o túnel SSH exige uma chave de host já confiável. Primeiro, confie na chave do host (adicione-a ao arquivo de hosts conhecidos configurado) ou defina explicitamente gateway.remote.sshHostKeyPolicy: "openssh" para um alias gerenciado cuja política de confiança do OpenSSH você aceite.
• Se você associar o Gateway a uma interface que não seja de local loopback, exija autenticação válida do Gateway: token, senha ou um proxy reverso com reconhecimento de identidade e gateway.auth.mode: "trusted-proxy".
• Consulte Segurança e Tailscale.

Fluxo de login do WhatsApp (remoto)

• Execute openclaw channels login --channel whatsapp --verbose no host remoto. Leia o código QR com o WhatsApp no seu telefone.
• Execute novamente o login nesse host se a autenticação expirar. A verificação de integridade indica problemas de vinculação.

Solução de problemas

Sons de notificação

Escolha os sons de cada notificação nos scripts com openclaw nodes notify, por exemplo:

openclaw nodes notify --node <id> --title "Ping" --body "Remote gateway ready" --sound Glass

Não há uma opção global de som padrão no aplicativo; os chamadores escolhem um som (ou nenhum) para cada solicitação.

Relacionado

• Aplicativo para macOS
• Acesso remoto