OpenClaw Troubleshooting

OpenClaw “Pairing Required” (1008) Fix — Full Step-by-Step Guide

Seeing pairing required, gateway connect failed, or WebSocket code 1008? This guide gives you a quick 2-minute fix, then a full recovery flow for stubborn pairing/auth issues.

What this error actually means

In OpenClaw, pairing is an explicit owner-approval step. The error usually means the connecting device is not approved yet, or device/auth state drifted after an update. Most cases are recoverable in minutes.

2-minute quick fix

  1. Run gateway and device checks on the gateway host.
  2. Approve the latest pending request.
  3. Retry the original action.
openclaw gateway status
openclaw devices list
openclaw devices approve --latest
openclaw status

Full fix workflow

Step 1) Verify gateway reachability first

openclaw gateway status
openclaw status

If the gateway is down or unreachable, pairing commands won’t fix anything. Bring gateway health to normal first.

Step 2) Check and approve pending device requests

openclaw devices list
openclaw devices approve <requestId>

Approve the most recent request. If a device retried with changed details, old request IDs may be superseded.

Step 3) Validate auth/token mismatch symptoms

openclaw config get gateway.auth.token
openclaw logs --follow

If you see unauthorized or token mismatch signatures, ensure the client and gateway use the same active token/password source.

Step 4) If issue started after update

openclaw gateway restart
openclaw devices list
openclaw devices approve --latest
openclaw status

Update-related state drift can happen. A clean restart + fresh approval usually restores normal handshake behavior.

Step 5) Remote/VPS/reverse-proxy checks

  • Confirm the dashboard/CLI points to the correct gateway URL and port.
  • Confirm auth mode and token expectations are consistent.
  • Pair the actual remote client device (each browser/profile/device can appear as a distinct identity).

Validation checklist

  • Gateway is running and reachable.
  • No required pairing requests remain unapproved.
  • Client can reconnect without WebSocket 1008.
  • No repeated unauthorized/token mismatch logs.

FAQ

Is “pairing required” always a bug? Usually no. It is a security gate that requires explicit approval.

Why does this happen even with correct token? Token auth and device pairing are separate checks. Passing token auth does not auto-approve a device.

Do I need to approve every restart? Not normally. Re-approval is usually needed when device identity or auth state changed.

Sources

Need hands-on help?

If your setup still fails after this flow, collect logs and error signatures, then reach out.

Contact us