The exact error
This guide fixes the error that appears in the OpenClaw Control UI, the desktop app, or any client trying to connect to the OpenClaw Gateway over WebSocket:
Or, with a more specific reason attached:
Both come from the same place — the Gateway’s device-pairing check — and both clear with the same two commands.
What the error means
OpenClaw treats every browser session and every CLI client as a device. To use the Control UI or to talk to the Gateway over WebSocket, that device must be approved once by the Gateway host. The approval is keyed to the browser’s device identity, the requested role (for example, agent or viewer) and the requested OAuth-style scopes (for example, agent.read, agent.write).
You see pairing required when one of the following is true:
- New device — the browser, terminal, or app has never been approved by this Gateway. This is the default case when you open the dashboard from a new machine.
- Scope upgrade — the device was approved for a narrower scope and is now requesting more. The Gateway requires a fresh approval rather than silently expanding access.
- Role upgrade — the device requested a role above what it was approved for (for example, going from
viewertoagent). - Metadata refresh — the device’s reconnect metadata changed and the Gateway wants you to re-approve.
None of these are bugs; the pairing check is the Gateway’s authorization gate. The fix is to approve the pending request.
The fix — in two commands
Run both commands on the Gateway host — the machine where openclaw gateway run is running. You cannot approve a device from the browser that is showing the error.
1 List pending device approvals
openclaw devices listLook for an entry with status pending. That is the browser or client that produced the error. Copy its requestId — it looks like req_01HXY....
2 Approve the pending request
openclaw devices approve <requestId>Replace <requestId> with the value you copied. The Gateway records the approval immediately — no restart required.
3 Reconnect the Control UI
Reload the browser tab, or click Reconnect in the desktop app. The error clears and the WebSocket completes the handshake. If you are using OpenClaw Easy, the desktop app reconnects automatically as soon as the Gateway accepts the approval.
Tip: Run openclaw devices list again after approving to confirm the entry moved from pending to approved. If you still see pending, you approved a different request — check the requestId carefully and re-run step 2.
Why this happens after a working session
Cleared browser storage
The device identity lives in IndexedDB. Clearing site data, browsing in private/incognito mode, or switching browsers all reset it — the Gateway sees a brand-new device and asks for approval again. Re-run the two commands above and you’re back.
Asked for more access than last time
If the Control UI or a plug-in requests a new scope (for example, agent write access when it previously only read), the Gateway will reject the WebSocket with pairing required: scope-upgrade. The fix is identical — the new request shows up in openclaw devices list with the upgraded scopes listed; approve it.
Moved to a new machine
Device identity is per-machine. A new laptop is a new device. There is no transfer flow — you simply approve the new device once on the Gateway host.
What if the steps don’t work?
The Gateway host is unreachable
If you cannot SSH or terminal into the Gateway host, you cannot approve a device. In that case the right answer is to use OpenClaw Easy on the same machine as the Gateway — the desktop app bundles the Gateway and the UI together, so device pairing happens locally without you ever seeing this error.
Multiple Gateways
If you run more than one OpenClaw Gateway (for example, one per project), make sure you are approving on the right one. Each Gateway has its own device list. Check ~/.openclaw/ on each host to find which one your browser is hitting.
The pending entry never appears
This usually means the browser is being rejected before pairing — common causes are origin not allowed (the browser’s origin isn’t in gateway.controlUi.allowedOrigins), or device identity required (the page is served over plain HTTP, not HTTPS/localhost, so the browser can’t generate a device identity). Both errors have specific fixes; check the Gateway logs for the exact code.
Skip this entirely — OpenClaw Easy
If you are not running OpenClaw on a server you SSH into — if it’s just on your laptop — you don’t need device pairing at all. OpenClaw Easy is a free desktop app for macOS and Windows that runs the OpenClaw Gateway locally and pairs the bundled Control UI automatically on first launch. You get the same OpenClaw runtime, with the same plug-ins and AI providers, without ever seeing the pairing required error.
Frequently asked questions
What does “openclaw gateway connect failed: error: pairing required” mean?
The OpenClaw Gateway requires every browser and client device to be approved once before it can use the Control UI. The error appears when the device identity is new, or when the requested role or scope has changed since the last approval. Approve the pending request on the Gateway host and reconnect.
How do I approve a device for the OpenClaw Gateway?
On the machine running openclaw gateway run, execute openclaw devices list to see pending requests, copy the requestId, then run openclaw devices approve <requestId>. The browser can reconnect immediately.
Why does the pairing required error keep coming back?
The device identity changed — usually because browser storage was cleared, a different browser was used, or you moved machines. It can also appear after a role or scope change. Re-approve to clear it.
Can I disable device pairing?
Pairing is a security feature and should not be disabled in production. For local development on localhost or HTTPS, the Control UI pairs automatically. For non-technical use, OpenClaw Easy bundles the Gateway and UI together and skips this step entirely.
Where do I run openclaw devices list?
On the OpenClaw Gateway host — the machine where you started openclaw gateway run. Approval is a server-side action and cannot be performed from the browser showing the error.