OC
OpenClaw
Dashboard

gateway-remote-access-tailscale-serve.md

/home/ubuntu/.openclaw/workspace/docs/gateway-remote-access-tailscale-serve.md
Back

OpenClaw Gateway — Remote access (Tailscale Serve)

Goal: Access the OpenClaw Control UI (Gateway dashboard + WS) remotely over the tailnet, while keeping the Gateway bound to loopback.

What we’re using

  • Gateway bind: loopback (127.0.0.1) on port 18789
  • Remote access: Tailscale Serve (tailnet-only HTTPS)
  • Canonical URLs:
    • Dashboard (openclaw-dashboard): https://openclaw.tail18850e.ts.net/
    • Gateway Control UI: https://openclaw.tail18850e.ts.net:444/
  • Auth model:
    • Gateway handshake uses token auth (gateway.auth.mode: "token")
    • Control UI also uses device pairing (one-time approval per browser/device identity)

Why this approach

  • Keeps the Gateway not directly exposed on LAN/tailnet ports.
  • Tailscale Serve provides HTTPS + routing inside the tailnet.
  • Token auth is explicit and does not rely on identity headers.

Config (OpenClaw)

In ~/.openclaw/openclaw.json:

{
  "gateway": {
    "mode": "local",
    "bind": "loopback",
    "port": 18789,
    "auth": {
      "mode": "token"
    },
    "tailscale": {
      "mode": "off"
    }
  }
}

Notes:

  • We do not use OpenClaw-managed Serve here, because the MagicDNS root (/) is reserved for the dashboard.
  • Token value lives at gateway.auth.token.

How to open the Control UI

Use this as your one canonical URL:

  • https://openclaw.tail18850e.ts.net:444/

Avoid mixing origins/ports/hostnames because browser storage and device identity may differ and trigger additional pairing prompts.

Pairing behavior (expected)

On first connect from a new browser profile/device identity, the UI may show:

  • pairing required

Fix:

  • Approve the pending device request on the gateway host:
openclaw devices list
openclaw devices approve <requestId>

After approval, refresh the page; the Control UI should store a device token and stop prompting.

Common reasons pairing happens again:

  • Incognito/private window
  • Different browser profile
  • Cleared site data
  • Different URL origin (hostname/port/path)

Tailscale Serve mapping (manual)

We manually map two tailnet HTTPS endpoints:

  • https://openclaw.tail18850e.ts.net/ → dashboard (port 3579)
  • https://openclaw.tail18850e.ts.net:444/ → gateway control UI (port 18789)

On the gateway host:

sudo tailscale serve reset
sudo tailscale serve --bg --https=443 3579
sudo tailscale serve --bg --https=444 18789
tailscale serve status

Health checks / troubleshooting

Check gateway service + loopback reachability:

openclaw gateway status
openclaw gateway probe

Check current Serve mapping:

tailscale serve status

If the UI shows unauthorized: gateway token missing:

  • Open a tokenized URL once:
    • https://openclaw.tail18850e.ts.net:444/?token=...
  • Or use the CLI helper (local):
    • openclaw dashboard --no-open

Security notes

  • Treat the gateway token like a password.
  • Prefer sticking to one canonical URL to avoid repeated pairing.
  • Tailnet-only Serve is safer than Funnel (public).

References