Control UI: disconnected (1008): pairing required

Symptoms

• The Control UI connects, then shows: “disconnected (1008): pairing required”.
• You can open the page (http://<host>:18789/), but the WebSocket disconnects immediately.
• This often happens when opening the UI from a different machine (LAN/tailnet) or via a reverse proxy.

Branch first (avoid wrong fix path)

Use this page only when the disconnect reason is specifically pairing required for a new/unapproved device.

Cause

OpenClaw requires a one-time device pairing approval the first time a new browser/device connects to the gateway.

Common triggers:

• You are connecting remotely (LAN/tailnet/VPS/Docker host).
• You switched browsers, used a new browser profile, or cleared browser storage (new device id).
• You are using plain HTTP on a remote host and the browser blocks WebCrypto (pairing identity can’t be established).

Fix

1) Approve the pending device request

On the gateway host, list pending requests:

openclaw devices list

Approve the request:

openclaw devices approve <requestId>

Then reload the Control UI page and reconnect.

2) If you’re remote, prefer a secure access path

Recommended options:

• Use an SSH tunnel and open locally:
  • ssh -N -L 18789:127.0.0.1:18789 user@host
  • Open http://127.0.0.1:18789/
• Or expose the UI via HTTPS (for example, Tailscale Serve).

3) If you must use plain HTTP remotely

If you’re on a controlled network and understand the trade-offs, use the current Control UI auth guide for the exact plain-HTTP exception on your installed version. Do not use this as the default remote access path.

Verify

• The Control UI stays connected (no immediate 1008 disconnect).
• openclaw devices list shows your browser/device as approved.

Related

• /troubleshooting/solutions/control-ui-unauthorized
• /troubleshooting/solutions/control-ui-device-identity-required
• /troubleshooting/solutions/gateway-pairing-required-scope-upgrade
• /guides/control-ui-auth-and-pairing