How to fix "openclaw gateway connect failed: error: pairing required"

If you are running OpenClaw and a client, the CLI, the macOS app, an iOS or Android node, or the web control UI, refuses to connect with one of these lines, you are in the right place:

gateway connect failed: Error: pairing required
gateway closed (1008): pairing required
disconnected (1008): pairing required
GatewayClientRequestError: pairing required

The good news is that this is almost never a crash. It is the gateway doing exactly what it is designed to do, which is refusing a session to a client it has not been told to trust yet. The OpenClaw gateway troubleshooting guide maps these signatures to specific remediation steps; this page walks through the same fixes in order.

What the error means

OpenClaw runs as a single Gateway process that owns your sessions, channels, and tools. Everything that talks to it, your terminal on the same machine, the menu bar app, a phone, or a browser tab, connects as a client over a WebSocket. Before the gateway hands that client a working session, the client has to be paired and approved.

When a client connects but has not been approved, the gateway closes the socket with WebSocket status code 1008, which means policy violation, and reports pairing required. The connection reached the server. The handshake is what failed. That distinction matters, because it tells you the network path is fine and the fix is an approval step rather than a port or firewall change.

The structured error code is often PAIRING_REQUIRED in the connect response. Check error.details.reason in logs, since each variant points at a slightly different fix, all of them in the device pairing layer rather than your model or channel config.

The common fix

For a first time connection, the device is sitting in a pending state waiting for you to approve it. Approve it from the machine the gateway runs on.

1. List the devices the gateway knows about and find the one marked pending:

openclaw devices list

2. Copy the request ID from the pending entry and approve it:

openclaw devices approve <REQUEST_ID>

If only one request is waiting, you can skip the copy and run openclaw devices approve --latest.

3. Refresh the dashboard or rerun the command from the client that failed. It should now hold a session.

The device was reaching the gateway the entire time; it just needed you to say yes once. If the CLI itself cannot connect to run devices list, run the command on the gateway host without passing --url so the CLI can use loopback local fallback while the remote WebSocket is still gated (#21913).

Scope upgrades after an OpenClaw update

Some releases tightened WebSocket handshake checks, and existing paired devices started failing with pairing required even on localhost (#21236). The gateway was running; the CLI was rejected on a scope upgrade. Fixed upstream in #21447 with automatic legacy metadata repair on reconnect, but if you are on an affected build the manual path is:

openclaw devices list
openclaw devices approve --latest

If logs show reason=scope-upgrade and approval keeps looping, rotate the operator token to include write scope:

openclaw devices list --json
openclaw devices rotate --device <DEVICE_ID> --role operator \
  --scope operator.read --scope operator.write
openclaw gateway restart
openclaw health

After updating OpenClaw, restart the gateway once so it reloads the device store before you assume pairing is broken.

No request ID

Sometimes openclaw devices list itself fails with the same pairing error, which is a chicken and egg problem: the client needs an approved session to run commands, but it needs commands to get approved. When that happens, the auth layer is the real issue, not the pending queue.

Open the device store and check the scopes on your entry:

nano ~/.openclaw/devices/paired.json

Some installs write a device entry with only operator.read, which lets the client see status and logs but not control the gateway from the CLI or TUI. Adding operator.write to that entry is usually all it takes to get a working session back. The wider scopes go further than that: operator.admin is effectively full control of the gateway, since it can approve other devices, change config, and run the privileged commands, so handing it to a device is close to handing that device the keys, and operator.approvals and operator.pairing let it manage who else gets in. Reach for the broad set only when the narrower operator.write does not clear the block, and treat a hand edit of paired.json as the break glass move it is rather than the default.

The supported way to make the same change is openclaw devices rotate --device <DEVICE_ID> --role operator with the explicit --scope flags you actually need, which writes the entry through the gateway instead of around it and is easier to reason about later. Stack Junkie's writeup walks through the manual scope edit if you want a reference. After any change to paired.json, restart the gateway so it reloads the store:

openclaw gateway restart

A second cause in this bucket is a token mismatch. If the gateway is started with one auth token and the client is configured with another, the gateway will refuse the session. Confirm the token your client sends matches the one the gateway is running with, then restart. Run openclaw doctor to surface token drift and device identity problems in one pass.

VPS and Docker setups

This is where the error gets noisy, and it is common because so many people run OpenClaw on a cheap VPS. When the gateway sits behind Docker, a tunnel, or a proxy like the ones Railway and similar hosts put in front of you, it can see the connection arriving from an internal NAT address rather than your real client. It treats that unexpected source as untrusted and asks for pairing again, sometimes on every reconnect.

The fix is to tell the gateway which proxy addresses to trust, and to be precise about it. Use exact IP addresses in trustedProxies rather than CIDR ranges. A block like 172.17.0.0/16 is known to break this silently; the exact Docker bridge address such as 172.17.0.1 works. Run the openclaw devices commands from inside the gateway environment, which for Docker means inside the container, so you are approving the device against the same store the gateway reads.

It is also worth a quick sanity check on the gateway URL. "gateway connect failed" on its own often means the client is pointed at a URL the gateway is not actually serving, while "pairing required" is the approval state on top of a reachable URL. Confirm the URL resolves and the port is right before you go deeper. For remote setups, the gateway exposure runbook covers doing this safely, and it is worth reading before you open anything to the public internet, because an exposed gateway has been the root of real OpenClaw security incidents this year.

On Docker Desktop specifically, the dashboard often appears to connect from a Docker bridge IP rather than your laptop's loopback. Pair once from inside the container context, set trustedProxies to that bridge IP, and avoid re pairing on every container restart by persisting ~/.openclaw/devices on a volume.

Debugging order

When you see pairing required, walk this sequence before you reinstall OpenClaw. Confirm the gateway process is actually running (openclaw gateway status). Read openclaw logs --follow during a failed connect and note whether the reason is not-paired, scope-upgrade, or token drift. Approve pending devices from the gateway host. If approval loops, fix scopes in paired.json or rotate the operator token.

If only remote clients fail, fix trustedProxies with exact IPs and approve from inside the gateway environment. If everything broke immediately after an upgrade, restart the gateway and approve once more for scope upgrade before you delete pairing state.

That order matters because deleting paired.json as a first move forces re pairing everywhere, while a single devices approve --latest often clears a post update scope gate.

Channel pairing

There is a separate pairing flow that uses the same word. When an unknown person messages your bot on Telegram, WhatsApp, or another channel, OpenClaw replies with a short pairing code and waits for you to approve that sender with openclaw pairing approve. That is access control for people talking to your agent, and it is unrelated to the pairing required socket error above, which is about clients connecting to the gateway. If your error is a six character code sent to a person in a chat, you want the channel pairing docs, not this page.

The managed option

The pairing error is the price of OpenClaw being a real gateway you administer yourself, and once you understand the device approval step it stops being mysterious. If you would rather not run and approve gateways at all, Operator.io is managed OpenClaw: we run the gateway, keep the device and token plumbing wired up, and connect Telegram and Discord for you, so a working agent is waiting on the first message instead of a 1008 close. You can start a free trial and message it in a minute, or keep self hosting with the steps above. Both get you to the same place.