Control UI problems cluster into two buckets:
- Auth token mismatch → UI shows unauthorized or reconnect loops.
- Device identity not approved → UI disconnects with 1008: pairing required.
This guide gives you a single flow that’s easier than searching for error strings one-by-one, and links to dedicated fix pages when you need more detail.
Prereqs (recommended):
- You can run commands on the gateway host (local machine, container shell, or SSH).
- You understand where OpenClaw state lives:
~/.openclaw/(or$OPENCLAW_STATE_DIR).
If you’re still stuck on install/service setup first, start here:
If you are on Windows and your real confusion is “native Windows runtime vs WSL2 vs service behavior”, these are the best companion pages:
What this guide helps you finish
By the end of this guide, you should be able to tell whether the dashboard problem is token auth, device pairing, scope drift, or remote-access design, then run the shortest stable recovery path.
Who this is for (and not for)
This guide is for operators who can already reach the gateway host and need to recover dashboard access without blind resets.
It is not the best page if your real issue is first-time install, Windows runtime confusion, or a reverse proxy that is already known to be broken.
Before you chase error strings: collect these four facts
Before touching config, confirm:
- which gateway runtime you are actually reaching,
- how that runtime gets its gateway token,
- which exact origin you are using for the dashboard,
- whether state and approved-device data persist across restart.
Those four facts usually decide whether the incident is auth, pairing, or environment drift.
0) The 60-second mental model
A) “Unauthorized” is about the gateway token
The gateway typically has auth enabled (recommended). The UI must send the same token/password that the gateway expects.
Token sources, in practice:
gateway.auth.tokeninopenclaw.json, or- an environment override like
OPENCLAW_GATEWAY_TOKEN
The fastest way to open the UI correctly is:
openclaw dashboardIt prints a tokenized URL (often ...?token=...) that bootstraps browser auth.
B) “Pairing required (1008)” is about the device list
OpenClaw uses a device identity model: the first time a new browser/device connects, you must approve it once.
On the gateway host:
openclaw devices list
openclaw devices approve <requestId>Dedicated fix pages:
- Unauthorized: /troubleshooting/solutions/control-ui-unauthorized
- Pairing: /troubleshooting/solutions/control-ui-pairing-required
1) Fix “unauthorized” (and stop the reconnect loop)
1.1 Always start from a fresh tokenized link
Run:
openclaw dashboardOpen the URL it prints. If you bookmarked an old URL (or opened http://127.0.0.1:18789/ directly), you may simply be
missing the one-time token bootstrap.
1.2 Confirm you are reaching the right gateway
If you are on native Windows, remember that a foreground shell, a Scheduled Task gateway, and a node host can all behave like different environments. If that is the problem, use:
This is the most common remote-host trap: you think you’re hitting the remote gateway, but you’re actually hitting a local port, a stale reverse proxy, or a different container.
Run:
openclaw status --deepIf the gateway host is remote, prefer an SSH tunnel for first-time debugging:
ssh -N -L 18789:127.0.0.1:18789 user@hostThen open the tokenized URL on your local machine.
1.3 Check for env var overrides (token drift)
If OPENCLAW_GATEWAY_TOKEN is set in systemd/launchd/Docker, it can override what you see in the file.
If you keep “fixing” openclaw.json but nothing changes, you are likely debugging config precedence:
2) Fix “disconnected (1008): pairing required”
2.1 Approve the pending device request (on the gateway host)
openclaw devices list
openclaw devices approve <requestId>Reload the page and reconnect.
2.1.1 The “access path priority” that avoids pairing/auth loops
Device identity and auth state are strongly tied to how you access the dashboard (scheme + host + port).
If you keep bouncing between:
http://127.0.0.1:18789/http://localhost:18789/https://mydomain.example/https://tailnet-hostname/
…you can accidentally create “new devices” over and over, or lose the stored identity after refresh.
Most reliable order:
- First-time setup / debugging: SSH tunnel to loopback +
openclaw dashboard - Stable daily use: one HTTPS origin (reverse proxy or built-in TLS) +
openclaw dashboard
Pick one primary origin and stick to it.
2.2 Use a secure access path for remote dashboards
The most robust “first setup” options:
- SSH tunnel (fast, no extra infra)
- Tailscale / tailnet access + HTTPS serving
- Reverse proxy with real TLS (avoid mixed-content / WebCrypto issues)
If you are using a reverse proxy and things “worked then broke”, also check:
2.3 If you see “device identity required” or token mismatch loops
Some setups fail to persist browser identity (or you are switching browsers/profiles constantly). Use the targeted fix:
If you’re debugging a “refresh loop” and want a tight checklist:
- Generate a fresh tokenized link:
openclaw dashboard- Verify you can list devices from the same gateway you think you’re hitting:
openclaw devices list- Approve the pending request and reload the same tokenized origin:
openclaw devices approve <requestId>3) Make remote dashboard access predictable (bind + persistence)
Remote connectivity failures often look like auth/pairing issues but actually come from:
- binding only to loopback when you need LAN/tailnet access
- not persisting state (fresh deployments wipe tokens + approved devices)
If you deploy on Docker/VPS/PaaS, treat state persistence as a first-class requirement:
If your gateway won’t bind without auth (or keeps restarting), see:
3.5) Verification: prove the dashboard is really stable
Before you call the fix complete, verify all of these:
- a fresh tokenized link connects cleanly
- the approved device reconnects after a refresh
- the same primary origin works again after a gateway restart
- you can explain whether auth, pairing, or persistence was the real failure layer
4) A “golden” recovery drill (do this once)
If you only do one operational exercise, do this:
- Export/persist the state directory (
~/.openclaw/or$OPENCLAW_STATE_DIR). - Pin the gateway token via env var substitution in config.
- Reinstall/force-install the gateway service without deleting state:
openclaw gateway install --force
openclaw gateway restart
openclaw dashboardIf you can restore state + reconnect in under 15 minutes, “unauthorized/pairing day” stops being a crisis.