Tailscale

OpenClaw can automatically configure Tailscale Serve (tailnet) or Funnel (public) for the

Gateway dashboard and WebSocket port. This keeps the Gateway bound to loopback, and

Tailscale provides HTTPS, routing, and (for Serve) identity headers.

Tailnet-only via tailscale serve. Gateway stays on 127.0.0.1.

Public HTTPS via tailscale funnel. OpenClaw requires a shared password.

Default (no Tailscale automation).

Set gateway.auth.mode to control the handshake:

(default if OPENCLAW_GATEWAY_TOKEN is set)

(via OPENCLAW_GATEWAY_PASSWORD or shared secret in config)

If tailscale.mode = "serve" and gateway.auth.allowTailscale is true,

valid Serve proxy requests can authenticate via Tailscale identity headers

(tailscale-user-login) without providing a token/password. OpenClaw validates

by resolving the x-forwarded-for address via local Tailscale to identify the identity,

then matches it against the header using the daemon (tailscale whois) before accepting.

If a request arrives from loopback, OpenClaw only treats it as Serve if it has Tailscale's

x-forwarded-for, x-forwarded-proto, x-forwarded-host

headers.

To require explicit credentials, set gateway.auth.allowTailscale: false or

force gateway.auth.mode: "password".

#

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

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

#

Use this if you want the Gateway to listen directly on a 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.

#

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

Prefer OPENCLAW_GATEWAY_PASSWORD over storing the password on disk.

Tailscale Serve/Funnel requires the tailscale CLI to be installed and logged in.

tailscale.mode: "funnel" will refuse to start unless auth mode is password to avoid public exposure.

If you want OpenClaw to undo tailscale serve on exit, set gateway.tailscale.resetOnExit

or tailscale funnel configuration on exit.

gateway.bind: "tailnet" is direct Tailnet binding (no HTTPS, no Serve/Funnel).

gateway.bind: "auto" prefers loopback. Use tailnet if you want Tailnet-only.

Serve/Funnel only exposes the Gateway control UI + WS. Node connections are

via the same Gateway WS endpoint, so Serve can be used for node access.

If you run the Gateway on one machine but want to control a browser from another,

run a node host on the browser machine and keep both on the same tailnet.

The Gateway proxies browser actions to the node. No separate control server or serve URL needed.

Avoid Funnel for browser control. Treat node pairing as operator access.

Serve requires tailnet HTTPS to be enabled. If not, the CLI will prompt you.

Serve injects Tailscale identity headers. Funnel does not.

Funnel requires Tailscale v1.38.3+, MagicDNS, HTTPS enabled, and the Funnel node attribute.

Funnel only supports ports 443, 8443, 10000 over TLS.

Funnel on macOS requires the open-source Tailscale app variant.

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