OpenClaw Remote Dashboard Access Playbook: SSH Tunnel, Tailnet, or Reverse Proxy

Remote dashboard access is where OpenClaw stops feeling like “a web page on a port” and starts behaving like what it is: an authenticated control plane with device identity.

This playbook is intentionally boring: pick one access pattern and make it stable.

What this guide helps you finish

By the end of this guide, you should be able to do three things confidently:

1. choose the right remote access pattern for your situation,
2. open the Control UI from that path without token/pairing churn, and
3. verify that the setup survives refreshes, device changes, and gateway restarts.

If your real need is “understand why pairing behaves this way,” keep this page for the setup path and use the deeper mental-model pages for explanation and incident recovery.

Who this is for (and not for)

This guide is for you if:

• you want to open the Control UI from another laptop or a phone,
• local openclaw dashboard works but remote access keeps failing,
• you are deciding between SSH tunnel, tailnet, and reverse proxy,
• you want one daily-use origin that stops generating repeat 1008 / unauthorized loops.

This guide is not for you if:

• your issue is that the gateway itself is not starting,
• you are debugging a provider/model/auth issue unrelated to Control UI access,
• you need the full trust-model explanation more than a setup playbook.

If you want the longer, deeper map of auth + pairing, read:

• /guides/control-ui-auth-and-pairing

If your remote path is part of a broader self-hosted deployment decision, also keep /guides/openclaw-deployment-troubleshooting and /guides/openclaw-pairing-explained close by. In practice, remote UI failures usually sit in the overlap between deployment shape, token persistence, and the pairing trust model.

0) The rule that prevents 80% of remote UI pain

Do not treat these as equivalent:

• http://127.0.0.1:18789 on the gateway host
• http://<LAN-IP>:18789 from another machine
• https://<tailnet-name> via a tailnet
• a reverse-proxied HTTPS origin

Pick one stable origin for daily use. Use SSH tunnel for first-time debugging.

Before you choose a path: decide what “good” looks like

Different remote paths solve different jobs well.

Use this decision rule:

• choose SSH tunnel to prove the system works,
• choose tailnet when you want the least fragile private daily path,
• choose reverse proxy only when you truly need a polished, stable external origin and you are prepared to operate it.

Before you debug: collect these four facts

Before changing config, write down:

1. the exact origin you want to keep using every day,
2. whether the gateway is bound only to loopback or beyond loopback,
3. where the gateway token comes from,
4. whether the state directory survives restart/redeploy.

Those four facts usually tell you whether the problem is path choice, auth drift, or lost pairing state.

1) Pattern A (recommended for first-time setup): SSH tunnel to loopback

This keeps the gateway bound to loopback (safe), but lets you access it remotely through an encrypted tunnel.

On your laptop (client machine):

ssh -L 18789:127.0.0.1:18789 <user>@<gateway-host>

Then open the dashboard locally through the tunnel:

openclaw dashboard

If you cannot run the CLI on the client machine, open:

http://127.0.0.1:18789/

and use the tokenized URL from the gateway host output of openclaw dashboard.

If this works but your LAN/reverse proxy path does not, you have proven the problem is access path, not “the UI is broken”.

Use SSH tunnel when:

• you are debugging first-time remote access,
• you want to keep the gateway bound to loopback,
• you do not yet trust your proxy or LAN exposure assumptions.

Do not treat SSH tunnel as your only answer if the real goal is effortless day-to-day phone access. It is the cleanest proof path, not always the best final operator path.

2) Pattern B: Tailnet access (Tailscale-style) for daily use

If you want to reach the Control UI from your phone/laptop regularly, a tailnet is often the least fragile option.

Key rules:

1. Prefer one stable hostname (not random IPs).
2. Prefer HTTPS when you can (browser storage, origin rules, and token persistence behave better).
3. Keep the gateway token reproducible (env var), and keep state persistent.

If you are moving from loopback to LAN/tailnet access, you will typically need:

{ gateway: { bind: "lan" } }

And you must keep auth on:

• token or password auth is required when binding beyond loopback

Deep dive:

• /guides/openclaw-deployment-troubleshooting
• /troubleshooting/solutions/gateway-refusing-to-bind-without-auth

Tailnet is usually the best daily-use answer when:

• the users are you or a small trusted set of operators,
• you want one private, repeatable hostname,
• you want fewer moving parts than a public proxy stack.

3) Pattern C: Reverse proxy (nginx/Caddy/Traefik) for daily use

Reverse proxy is fine, but it is the easiest way to create “worked yesterday, broke after update” incidents.

Two high-frequency footguns:

1. The gateway starts speaking HTTPS (TLS auto-generate enabled), but your proxy still forwards plain HTTP.
2. You unknowingly changed the origin (host/port/scheme), so the browser’s stored token/device identity no longer matches.

If your proxy suddenly returns 502 or weird protocol errors after an update:

• /troubleshooting/solutions/gateway-reverse-proxy-breaks-after-tls-auto-generate

Reverse proxy is the right answer only when you can keep all of these stable:

• scheme (http vs https),
• hostname,
• upstream protocol,
• auth story,
• persistence and restart behavior.

If those are not under control yet, tailnet is often the calmer operating choice.

4) Token + pairing: the shortest stable loop

When you access the UI remotely, always do these in order:

1. On the gateway host, print the tokenized URL:

   openclaw dashboard

2. If the UI says pairing required (1008), approve the device:
   • /troubleshooting/solutions/control-ui-pairing-required
3. Stop mixing origins. If you alternate between raw IP, proxy URL, and tunnel URL, you will keep generating “new devices.”

If you want the full mental model (why this happens):

• /guides/openclaw-pairing-explained

5) The fastest decision tree when the remote path feels unstable

• If SSH tunnel works and your other path does not: your problem is almost certainly origin/path/proxy design, not the UI itself.
• If the page loads but keeps saying unauthorized: check token source drift before you do anything with pairing.
• If the tokenized URL works once but refresh causes pairing required (1008): stop switching origins and check whether the browser is appearing as a new device.
• If restart breaks a previously good setup: check state persistence before you blame the browser.

6) Verification (prove it’s stable)

You are done only if all of these are true:

1. The Control UI loads without unauthorized loops.
2. Refresh does not flip you back to device identity required / pairing.
3. After openclaw gateway restart, you can still open the UI from the same origin without re-pairing.
4. A second approved device can use the same stable origin without creating a new debugging pattern every session.

If (3) fails, you are likely not persisting state in Docker/PaaS, or your token source is drifting:

• /guides/openclaw-deployment-troubleshooting

7) What to keep stable after it works

Once the path is healthy, try not to keep “testing” new origins casually.

Preserve:

• one canonical daily-use origin,
• one reproducible token source,
• one deliberate binding strategy,
• persistent gateway state,
• a recovery note that says which path you trust first when incidents happen.

That is what turns remote dashboard access from a recurring puzzle into an operator surface you can actually rely on.