OpenClaw Control UI Auth & Pairing: Fix 'unauthorized', 1008, and Remote Dashboard Access

Control UI problems cluster into two buckets:

1. Auth token mismatch → UI shows unauthorized or reconnect loops.
2. 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:

• /guides/openclaw-installation-troubleshooting

If you are on Windows and your real confusion is “native Windows runtime vs WSL2 vs service behavior”, these are the best companion pages:

• /guides/openclaw-windows-native-vs-wsl2
• /guides/openclaw-native-windows-field-guide

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.token in openclaw.json, or
• an environment override like OPENCLAW_GATEWAY_TOKEN

The fastest way to open the UI correctly is:

openclaw dashboard

It 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 dashboard

Open 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:

• /guides/openclaw-native-windows-field-guide

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 --deep

If the gateway host is remote, prefer an SSH tunnel for first-time debugging:

ssh -N -L 18789:127.0.0.1:18789 user@host

Then 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:

• /guides/openclaw-configuration

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:

1. First-time setup / debugging: SSH tunnel to loopback + openclaw dashboard
2. 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:

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

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:

• /troubleshooting/solutions/control-ui-device-identity-required

If you’re debugging a “refresh loop” and want a tight checklist:

1. Generate a fresh tokenized link:

openclaw dashboard

2. Verify you can list devices from the same gateway you think you’re hitting:

openclaw devices list

3. 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:

• /guides/openclaw-deployment-troubleshooting

If your gateway won’t bind without auth (or keeps restarting), see:

• /troubleshooting/solutions/gateway-refusing-to-bind-without-auth

4) A “golden” recovery drill (do this once)

If you only do one operational exercise, do this:

1. Export/persist the state directory (~/.openclaw/ or $OPENCLAW_STATE_DIR).
2. Pin the gateway token via env var substitution in config.
3. Reinstall/force-install the gateway service without deleting state:

openclaw gateway install --force
openclaw gateway restart
openclaw dashboard

If you can restore state + reconnect in under 15 minutes, “unauthorized/pairing day” stops being a crisis.