Tailscale

O OpenClaw pode configurar automaticamente o Tailscale Serve (tailnet) ou Funnel (público) para o painel do Gateway e a porta WebSocket. Isso mantém o Gateway vinculado ao loopback, enquanto o Tailscale fornece HTTPS, roteamento e, no caso do Serve, cabeçalhos de identidade.

Modos

gateway.tailscale.mode:

A saída de status e auditoria usa exposição pelo Tailscale para esse modo Serve/Funnel do OpenClaw. off significa que o OpenClaw não está gerenciando o Serve nem o Funnel; não significa que o daemon local do Tailscale esteja parado ou com a sessão encerrada.

Exemplos de configuração

Somente na tailnet (Serve)

{  gateway: {    bind: "loopback",    tailscale: { mode: "serve" },  },}

Abra: https://<magicdns>/ (ou o gateway.controlUi.basePath configurado)

Para expor a interface de controle por meio de um Serviço Tailscale nomeado, em vez do nome de host do dispositivo, defina gateway.tailscale.serviceName como o nome do Serviço:

{  gateway: {    bind: "loopback",    tailscale: { mode: "serve", serviceName: "svc:openclaw" },  },}

A inicialização passa a informar a URL do Serviço como https://openclaw.<tailnet-name>.ts.net/, em vez do nome de host do dispositivo. Os Serviços Tailscale exigem que o host seja um Node com tag aprovado na sua tailnet — configure a tag e aprove o Serviço no Tailscale antes de habilitar essa opção; caso contrário, tailscale serve --service=... falhará durante a inicialização do Gateway.

Somente na tailnet (vinculação ao IP da tailnet)

Use esta opção para fazer o Gateway escutar diretamente no IP da tailnet, sem Serve/Funnel:

{  gateway: {    bind: "tailnet",    auth: { mode: "token", token: "your-token" },  },}

Conecte-se a partir de outro dispositivo da tailnet:

• Interface de controle: http://<tailscale-ip>:18789/
• WebSocket: ws://<tailscale-ip>:18789

Internet pública (Funnel + senha compartilhada)

{  gateway: {    bind: "loopback",    tailscale: { mode: "funnel" },    auth: { mode: "password", password: "replace-me" },  },}

Prefira OPENCLAW_GATEWAY_PASSWORD a gravar uma senha no disco.

Exemplos de CLI

openclaw gateway --tailscale serveopenclaw gateway --tailscale funnel --auth password

Autenticação

gateway.auth.mode controla o handshake:

Cabeçalhos de identidade do Tailscale (somente Serve)

Quando tailscale.mode: "serve" e gateway.auth.allowTailscale for true, a autenticação da interface de controle/WebSocket poderá usar cabeçalhos de identidade do Tailscale (tailscale-user-login) em vez de um token ou uma senha. O OpenClaw verifica o cabeçalho resolvendo o endereço x-forwarded-for da solicitação por meio do daemon local do Tailscale (tailscale whois) e comparando-o ao login no cabeçalho antes de aceitá-lo. Uma solicitação só se qualifica para esse caminho quando chega pelo loopback contendo os cabeçalhos x-forwarded-for, x-forwarded-proto e x-forwarded-host do Tailscale.

Esse fluxo sem token pressupõe que o host do Gateway seja confiável. Se código local não confiável puder ser executado no mesmo host, defina gateway.auth.allowTailscale: false e exija autenticação por token ou senha.

Escopo da dispensa:

• Aplica-se somente à superfície de autenticação WebSocket da interface de controle. Os endpoints da API HTTP (/v1/*, /tools/invoke, /api/channels/* etc.) nunca usam autenticação por cabeçalho de identidade do Tailscale; eles sempre seguem o modo normal de autenticação HTTP do Gateway.
• Para sessões de operador da interface de controle que já contenham a identidade do dispositivo no navegador, uma identidade verificada do Tailscale evita a etapa de ida e volta do emparelhamento por token de inicialização/código QR.
• Isso não dispensa a identidade do próprio dispositivo: clientes sem dispositivo ainda são rejeitados, e conexões com função de Node continuam passando pelas verificações normais de emparelhamento e autenticação.

Observações

• O Tailscale Serve/Funnel exige que a CLI tailscale esteja instalada e com uma sessão iniciada.
• tailscale.mode: "funnel" se recusará a iniciar, a menos que o modo de autenticação seja password, para evitar exposição pública.
• gateway.tailscale.serviceName aplica-se somente ao modo Serve e é passado para tailscale serve --service=<name>. O valor deve usar o formato svc:<dns-label> do Tailscale, por exemplo, svc:openclaw. O Tailscale exige que os hosts do Serviço sejam Nodes com tag, e o Serviço pode precisar de aprovação no console de administração antes que o Serve possa publicá-lo.
• gateway.tailscale.resetOnExit desfaz a configuração de tailscale serve/tailscale funnel no encerramento.
• gateway.tailscale.preserveFunnel: true mantém ativa entre reinicializações do Gateway uma rota tailscale funnel configurada externamente. Com mode: "serve", o OpenClaw verifica tailscale funnel status antes de reaplicar o Serve e não o reaplica quando uma rota do Funnel já cobre a porta do Gateway. A política do Funnel gerenciado pelo OpenClaw que permite somente senha permanece inalterada.
• gateway.bind: "tailnet" usa uma vinculação direta à tailnet (sem HTTPS e sem Serve/Funnel), além do 127.0.0.1 local obrigatório quando um IPv4 da tailnet está disponível; caso contrário, usa somente o loopback como alternativa.
• gateway.bind: "auto" prioriza o loopback; use tailnet para limitar a exposição de rede à tailnet, mantendo o acesso por loopback no mesmo host.
• Serve/Funnel expõe somente a interface de controle do Gateway + WS. Os Nodes se conectam pelo mesmo endpoint WS do Gateway, portanto o Serve também funciona para o acesso de Nodes.

Pré-requisitos e limitações do Tailscale

• O Serve exige que HTTPS esteja habilitado para a sua tailnet; a CLI solicitará a habilitação se estiver ausente.
• O Serve injeta cabeçalhos de identidade do Tailscale; o Funnel não.
• O Funnel exige Tailscale v1.38.3 ou posterior, MagicDNS, HTTPS habilitado e um atributo de Node do Funnel.
• O Funnel aceita somente as portas 443, 8443 e 10000 sobre TLS.
• No macOS, o Funnel exige a variante de código aberto do aplicativo Tailscale.

Controle do navegador (Gateway remoto + navegador local)

Para executar o Gateway em uma máquina e controlar um navegador em outra, execute um host de Node na máquina do navegador e mantenha ambas na mesma tailnet. O Gateway encaminha as ações do navegador ao Node; não é necessário um servidor de controle separado nem uma URL do Serve.

Evite o Funnel para controlar o navegador; trate o emparelhamento do Node como acesso de operador.

Saiba mais

• Visão geral do Tailscale Serve: https://tailscale.com/kb/1312/serve
• Comando tailscale serve: https://tailscale.com/kb/1242/tailscale-serve
• Visão geral do Tailscale Funnel: https://tailscale.com/kb/1223/tailscale-funnel
• Comando tailscale funnel: https://tailscale.com/kb/1311/tailscale-funnel

Relacionado

• Acesso remoto
• Descoberta
• Autenticação