How to Fix "OpenClaw Gateway Connect Failed: Pairing Required"

You run an OpenClaw command or open the Control UI and instead of your agent you get an error: the gateway refuses the connection and demands pairing. It often appears right after an install, an update, or a config change, and it blocks everything, including openclaw gateway status itself. Here is what the error actually means and the exact steps to clear it.

gateway connect failed: pairing required

This is the full error most people see, sometimes as disconnected (1008): pairing required in the Control UI or logs. It is not a crash. OpenClaw enforces device authorization: every client (your CLI, a browser tab, the desktop app, a mobile node) must present an approved device identity or a valid auth token when it opens the WebSocket connection to the Gateway. When the gateway sees a client it does not recognize, it closes the connection with code 1008 and this message.

Three situations trigger it:

1. A fresh install or a new device that has simply never been approved.
2. A token mismatch, where the token your client sends does not match what the gateway expects (common after partial upgrades or manual edits to ~/.openclaw/openclaw.json).
3. A stale device identity, often caused by running commands as root or sudo, which leaves cache files owned by the wrong user and an outdated identity that the gateway rejects.

Fix 1: Approve the Pending Device (Most Common)

For most people, especially on a first install, the client has already asked to pair and is just waiting for approval.

1. On the machine running the gateway, list devices and pairing requests: openclaw devices list.
2. Look for a pending request and note its request ID.
3. Approve it: openclaw devices approve <requestId>.
4. Retry the connection from the client. It should connect immediately, no restart needed.

Fix 2: Refresh a Stale or Mismatched Token

If approving devices does not help, or the logs show AUTH_TOKEN_MISMATCH, your client is sending the wrong token.

1. Read the token the gateway actually expects: openclaw config get gateway.auth.token.
2. Paste that token into the client. In the Control UI, open the connection settings and replace the stored token. In a browser, the cleanest route is a fresh tokenized link from openclaw dashboard, which embeds the current token for you.
3. If you run OpenClaw in Docker or another container, pass the token explicitly with the environment variable OPENCLAW_GATEWAY_TOKEN so the container and CLI agree on the same value.
4. Restart the gateway after any token change: openclaw gateway restart.

Fix 3: The Gateway or Relay Is Not Reachable

Sometimes "pairing required" is a symptom of connecting to the wrong gateway, or to a half-restarted one. Confirm you are talking to the gateway you think you are.

1. Check that the gateway is up: openclaw gateway status.
2. Probe the WebSocket endpoint directly: openclaw gateway health --url ws://127.0.0.1:18789.
3. If the gateway is on a remote server, make sure your tunnel or VPN is up, then reconnect. A dropped SSH tunnel produces confusing auth errors because the client falls back to a different endpoint.
4. Restart cleanly if in doubt: openclaw gateway restart, then retry from the client.

Fix 4: Full Re-Pair for a Stale Device Identity

If the same device keeps getting rejected after approval, its stored identity is stale. This is the classic aftermath of running the CLI or an update with sudo, which creates root-owned cache files.

1. Check file ownership in your OpenClaw state directory (~/.openclaw/). If files are owned by root, fix ownership back to your user.
2. Remove the rejected device on the gateway side: list with openclaw devices list, then revoke the stale entry.
3. Reconnect from the client so it generates a new pairing request.
4. Approve the new request: openclaw devices approve <requestId>.
5. Run openclaw doctor afterwards to confirm no other auth or config drift remains.

Reading the Error Codes

The gateway attaches a detail code to failed connect attempts, visible in openclaw logs --follow. They map directly to fixes:

1. PAIRING_REQUIRED: run openclaw devices approve <requestId> (Fix 1).
2. AUTH_TOKEN_MISSING: the client sent no token at all; set or paste one (Fix 2).
3. AUTH_TOKEN_MISMATCH: the token is wrong or outdated; refresh it from openclaw config get gateway.auth.token (Fix 2).

Frequently Asked Questions

Do I have to re-pair after every OpenClaw update?

No. Device approvals persist across updates. If pairing breaks after an update, the usual culprit is a token that changed on one side only, or an update that was run with sudo and left root-owned cache files. Fix the token or the file ownership rather than re-pairing everything.

Is it safe to disable pairing to make the error go away?

Avoid it. Pairing is what stops anyone on your network from driving your agent, reading your messages, and using your API keys. If pairing gets in your way on a private machine, keep token auth enabled at minimum, and never expose port 18789 publicly without authentication.

Where does OpenClaw store the gateway auth token?

In the gateway config under gateway.auth.token, inside ~/.openclaw/openclaw.json. You can read it safely with openclaw config get gateway.auth.token, or supply it via the OPENCLAW_GATEWAY_TOKEN environment variable in containerized setups.

Pairing headaches mostly come from mismatched state between machines, which is one reason many teams prefer a managed OpenClaw host where the gateway, tokens, and device approvals are handled for them.