OpenClaw error: gateway connect failed, pairing required

The full message usually looks like one of these:

gateway connect failed: GatewayClientRequestError: pairing required
error gateway connect failed: pairing required
device identity required

All three mean the same thing. Your client reached the OpenClaw gateway, the gateway answered, and the gateway refused to act because it does not recognise the device asking. This is a trust problem, not a connectivity problem, which is why restarting the gateway almost never helps.

First, confirm the gateway is actually healthy

Before changing anything, rule out the simpler failure:

openclaw status
openclaw health

If those come back clean, the gateway is fine and you are in the right article. If they fail, you have a different problem and pairing is a red herring.

Cause 1: the device was never approved

This is the common case, and it is a thirty-second fix. On the machine running the gateway:

openclaw devices list
openclaw devices approve <id>

Then reconnect the client. If you are pairing a messaging channel rather than a device, the equivalent commands are:

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <code> --notify

Pairing codes are eight characters and they expire, so list them fresh rather than reusing a code from an old terminal window.

Cause 2: a reverse proxy is hiding the fact that the request is local

This one costs people hours, because everything looks correctly configured.

The gateway auto-approves requests that it can see are coming from the local machine. It decides that by looking at the incoming request. Put nginx, Caddy, or any other reverse proxy in front of it with the usual defaults, and the proxy rewrites the Host header and adds X-Forwarded-For and X-Real-IP. From the gateway's point of view the request is now arriving from somewhere else, so it stops auto-approving and demands pairing.

The fix is to make the proxied request look local again. In the proxy block that forwards to the gateway, set the host header to localhost and do not forward the client IP headers:

proxy_set_header Host "localhost";
# and deliberately do NOT set X-Forwarded-For or X-Real-IP here

If you deliberately want remote access with real pairing, leave the headers alone and approve the device instead. Just be aware which of the two you chose.

Cause 3: the dashboard is being served over plain HTTP

Browser device identity is generated with the WebCrypto API, and browsers only expose WebCrypto on a secure context. Over http:// on anything other than localhost, the browser cannot create the key, so the dashboard has no identity to present and the gateway asks for pairing that can never complete.

The proper fix is to serve the dashboard over HTTPS. If you are testing on a trusted local network and accept the risk, the gateway config accepts allowInsecureAuth: true as a temporary escape hatch. Do not leave that on for anything reachable from the internet.

Cause 4: the gateway token does not match

If your client passes a token, a mismatch surfaces as a pairing or unauthorized error rather than a clear "wrong token" message. Related errors you may see are gateway token missing and unauthorized gateway token mismatch.

Check that OPENCLAW_GATEWAY_TOKEN is set to the same value on both sides, and remember that the env var has to be visible to the process, not just to your login shell. A token exported in .bashrc is invisible to a systemd unit.

Quick reference

Symptom	Most likely cause
Fresh install, first connection	Device never approved
Works locally, fails through nginx or Caddy	Proxy headers
Fails only in the browser, CLI is fine	No HTTPS, WebCrypto blocked
Started after a token rotation	Token mismatch
Started after restoring a backup	Stale device identity, re-approve

Where the identity actually lives

Paired node tokens are stored in ~/.openclaw/nodes/paired.json. That file holds credentials, so it should be chmod 600. If you are moving a gateway between machines and want the pairings to come with it, that is the file to carry across, along with the rest of ~/.openclaw.