openclaw/docs/gateway/tailscale.md

summary	read_when
Integrated Tailscale Serve/Funnel for the Gateway dashboard	Exposing the Gateway Control UI outside localhost Automating tailnet or public dashboard access

Tailscale (Gateway dashboard)

Clawdbot can auto-configure Tailscale Serve (tailnet) or Funnel (public) for the Gateway dashboard and WebSocket port. This keeps the Gateway bound to loopback while Tailscale provides HTTPS and routing.

Modes

• serve: Tailnet-only Serve via tailscale serve. The gateway stays on 127.0.0.1.
• funnel: Public HTTPS via tailscale funnel. Clawdbot requires a shared password.
• off: Default (no Tailscale automation).

Auth

Set gateway.auth.mode to control the handshake:

• token (default when CLAWDBOT_GATEWAY_TOKEN is set)
• password (shared secret via CLAWDBOT_GATEWAY_PASSWORD or config)

Tailscale Serve/Funnel do not replace Gateway auth. Always require a token or password, and keep gateway.auth.allowTailscale: false (legacy option).

Config examples

Tailnet-only (Serve)

{
  gateway: {
    bind: "loopback",
    tailscale: { mode: "serve" },
    auth: { mode: "token", token: "your-token", allowTailscale: false }
  }
}

Open: https://<magicdns>/ (or your configured gateway.controlUi.basePath)

Tailnet-only (bind to Tailnet IP)

Use this when you want the Gateway to listen directly on the Tailnet IP (no Serve/Funnel).

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

Connect from another Tailnet device:

• Control UI: http://<tailscale-ip>:18789/
• WebSocket: ws://<tailscale-ip>:18789

Note: loopback (http://127.0.0.1:18789) will not work in this mode.

Public internet (Funnel + shared password)

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

Prefer CLAWDBOT_GATEWAY_PASSWORD over committing a password to disk.

CLI examples

clawdbot gateway --tailscale serve
clawdbot gateway --tailscale funnel --auth password

Notes

• Tailscale Serve/Funnel requires the tailscale CLI to be installed and logged in.
• tailscale.mode: "funnel" refuses to start unless auth mode is password to avoid public exposure.
• Set gateway.tailscale.resetOnExit if you want Clawdbot to undo tailscale serve or tailscale funnel configuration on shutdown.
• gateway.bind: "tailnet" is a direct Tailnet bind (no HTTPS, no Serve/Funnel).
• gateway.bind: "auto" prefers loopback; use tailnet if you want Tailnet-only.
• Serve/Funnel only expose the Gateway control UI + WS. Nodes connect over the same Gateway WS endpoint, so Serve can work for node access.

Browser control server (remote Gateway + local browser)

If you run the Gateway on one machine but want to drive a browser on another machine, use a separate browser control server and publish it through Tailscale Serve (tailnet-only):

# on the machine that runs Chrome
clawdbot browser serve --bind 127.0.0.1 --port 18791 --token <token>
tailscale serve https / http://127.0.0.1:18791

Then point the Gateway config at the HTTPS URL:

{
  browser: {
    enabled: true,
    controlUrl: "https://<magicdns>/"
  }
}

And authenticate from the Gateway with the same token (prefer env):

export CLAWDBOT_BROWSER_CONTROL_TOKEN="<token>"

Avoid Funnel for browser control endpoints unless you explicitly want public exposure.

Tailscale prerequisites + limits

• Serve requires HTTPS enabled for your tailnet; the CLI prompts if it is missing.
• Serve injects Tailscale identity headers; Clawdbot does not use them for auth.
• Funnel requires Tailscale v1.38.3+, MagicDNS, HTTPS enabled, and a funnel node attribute.
• Funnel only supports ports 443, 8443, and 10000 over TLS.
• Funnel on macOS requires the open-source Tailscale app variant.

Learn more

• Tailscale Serve overview: https://tailscale.com/kb/1312/serve
• tailscale serve command: https://tailscale.com/kb/1242/tailscale-serve
• Tailscale Funnel overview: https://tailscale.com/kb/1223/tailscale-funnel
• tailscale funnel command: https://tailscale.com/kb/1311/tailscale-funnel