How to fix OpenClaw's “pairing required” (1008) scope error
The 1008 close code means a device wants more scopes than an operator approved. Reading Requested vs Approved, approving the request, and the agent-hands case.
gateway closed (1008): pairing required means a device is asking the Gateway for more permission scopes than an operator has approved. Nothing is broken: OpenClaw parked the request as a pending approval and is waiting for you. Run openclaw devices list, compare the Requested and Approved columns, then approve the exact request: openclaw devices approve <requestId>.
What the error is telling you
Every client that talks to the Gateway (your browser dashboard, the CLI, even OpenClaw’s own internal components) is a “device” with an approved set of scopes (read, write, admin, and finer-grained ones). When an already-paired device asks for a scope it wasn’t approved for, OpenClaw deliberately does not upgrade it in place. It keeps the existing approval, files a pending upgrade request, and refuses the connection with close code 1008 and the message “pairing required: device is asking for more scopes than currently approved.” Scope upgrades are never auto-approved (there is no config that changes this on current stable releases), because silent permission escalation is precisely what an agent security model must not allow.
The fix, in order
- 1. See what’s pending. Look for a row where
Copiedopenclaw devices listRequestedis broader thanApproved. You can also preview just the newest request withopenclaw devices approve --latest. Note that this previews and exits; it does not approve. - 2. Approve the exact request. The requestId appears in the error itself (“scope upgrade pending approval (requestId: …)”) and in the list output.
Copiedopenclaw devices approve <requestId> - 3. If nothing is pending, trigger it first. Pending requests expire. If the device gave up waiting, make it ask again: retry the action that failed (a browser command, a tool call), then approve the fresh request while it’s live.
- 4. Verify at the real surface. Don’t trust the approval message. Repeat the thing that originally failed. For an agent’s internal device, that means a real agent turn that uses a tool, not just a status command.
The case that catches people: the agent’s own hands
The confusing version of this error isn’t your browser. It’s the pod or server install where the agent’s own internal device was approved with read-only scope during setup. Everything looks healthy until the agent tries to use a tool (web_search, exec, a browser), the tool call requests a write or admin scope, and every action fails with 1008 while the upgrade request sits pending with nobody watching. From the chat, it looks like an agent that keeps replying that it can’t do things, and it carries on long after the pending request has expired. If you script your own setup, the durable fix is to approve the internal device’s scopes as part of setup and then prove it with a live agent turn. Self-hosters on VPS setups hit the same wall (upstream issue #81555 documents a browser-tools variant on an earlier release; a fix for that specific regression landed in PR #81716), so if approving doesn’t stick on an old version, updating is part of the answer.
What not to do
Don’t reach for allowInsecureAuth or similar downgrades to make the error go away: the security audit flags those for good reason, and the pairing model is doing its job. And don’t confuse this with chat-sender pairing: the codes new Telegram or WhatsApp senders get are a different system with different rules, explained in our pairing and allowlists guide.