Tailscale

OpenClaw 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, routing, and (for Serve) identity headers.

Modes

• text

  Copy

  serve
  : Tailnet-only Serve via
  text

  Copy

  tailscale serve
  . The gateway stays on
  text

  Copy

  127.0.0.1
  .
• text

  Copy

  funnel
  : Public HTTPS via
  text

  Copy

  tailscale funnel
  . OpenClaw requires a shared password.
• text

  Copy

  off
  : Default (no Tailscale automation).

Status and audit output use Tailscale exposure for this OpenClaw Serve/Funnel mode.

means OpenClaw is not managing Serve or Funnel; it does not mean the local Tailscale daemon is stopped or logged out.

Auth

Set

to control the handshake:

• text

  Copy

  none
  (private ingress only)
• text

  Copy

  token
  (default when
  text

  Copy

  OPENCLAW_GATEWAY_TOKEN
  is set)
• text

  Copy

  password
  (shared secret via
  text

  Copy

  OPENCLAW_GATEWAY_PASSWORD
  or config)
• text

  Copy

  trusted-proxy
  (identity-aware reverse proxy; see Trusted Proxy Auth)

When

and is , Control UI/WebSocket auth can use Tailscale identity headers () without supplying a token/password. OpenClaw verifies the identity by resolving the address via the local Tailscale daemon () and matching it to the header before accepting it. OpenClaw only treats a request as Serve when it arrives from loopback with Tailscale’s , , and headers. For Control UI operator sessions that include browser device identity, this verified Serve path also skips the device-pairing round trip. It does not bypass browser device identity: device-less clients are still rejected, and node-role or non-Control UI WebSocket connections still follow the normal pairing and auth checks. HTTP API endpoints (for example , , and ) do not use Tailscale identity-header auth. They still follow the gateway's normal HTTP auth mode: shared-secret auth by default, or an intentionally configured trusted-proxy / private-ingress setup. This tokenless flow assumes the gateway host is trusted. If untrusted local code may run on the same host, disable and require token/password auth instead. To require explicit shared-secret credentials, set and use or .

Config examples

Tailnet-only (Serve)

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

Open:

(or your configured )

Tailnet-only (bind to Tailnet IP)

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

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

Connect from another Tailnet device:

• Control UI:
  text

  Copy

  http://<tailscale-ip>:18789/
• WebSocket:
  text

  Copy

  ws://<tailscale-ip>:18789

Public internet (Funnel + shared password)

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

Prefer

over committing a password to disk.

CLI examples

bash
Copy
openclaw gateway --tailscale serve
openclaw gateway --tailscale funnel --auth password

Notes

• Tailscale Serve/Funnel requires the
  text

  Copy

  tailscale
  CLI to be installed and logged in.
• text

  Copy

  tailscale.mode: "funnel"
  refuses to start unless auth mode is
  text

  Copy

  password
  to avoid public exposure.
• Set
  text

  Copy

  gateway.tailscale.resetOnExit
  if you want OpenClaw to undo
  text

  Copy

  tailscale serve
  or
  text

  Copy

  tailscale funnel
  configuration on shutdown.
• text

  Copy

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

  Copy

  gateway.bind: "auto"
  prefers loopback; use
  text

  Copy

  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 (remote Gateway + local browser)

If you run the Gateway on one machine but want to drive a browser on another machine, run a node host on the browser machine and keep both on the same tailnet. The Gateway will proxy browser actions to the node; no separate control server or Serve URL needed.

Avoid Funnel for browser control; treat node pairing like operator access.

Tailscale prerequisites + limits

• Serve requires HTTPS enabled for your tailnet; the CLI prompts if it is missing.
• Serve injects Tailscale identity headers; Funnel does not.
• Funnel requires Tailscale v1.38.3+, MagicDNS, HTTPS enabled, and a funnel node attribute.
• Funnel only supports ports
  text

  Copy

  443
  ,
  text

  Copy

  8443
  , and
  text

  Copy

  10000
  over TLS.
• Funnel on macOS requires the open-source Tailscale app variant.

Learn more

• Tailscale Serve overview: https://tailscale.com/kb/1312/serve
• text

  Copy

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

  Copy

  tailscale funnel
  command: https://tailscale.com/kb/1311/tailscale-funnel

Related

• Remote access
• Discovery
• Authentication