Gateway: 'disconnected (1008): pairing required' after update (scope-upgrade)

Symptoms

• The gateway is running, but new connections fail with:
  • disconnected (1008): pairing required (Control UI / webchat), or
  • gateway closed (1008): pairing required (CLI / sessions_spawn / cron announce).
• One existing session may still work, but anything that opens a new WebSocket gets rejected.
• This often starts after:
  • openclaw update,
  • openclaw gateway install --force,
  • deleting/resetting ~/.openclaw/identity / ~/.openclaw/devices,
  • changing gateway auth/bind settings.

Cause

OpenClaw enforces device pairing (and scoped device access) on gateway WebSocket connections.

Sometimes the device is already paired, but the new connection requests a higher scope (a scope upgrade). In that case the gateway still closes the connection with 1008: pairing required until the missing scope shown by logs is approved.

Fix

1) Approve the pending device request

openclaw devices list
openclaw devices approve <requestId>

Tip: if there is only one pending request, you can often do:

openclaw devices approve

2) If logs show a scope-upgrade, approve only the missing scope

Check logs before rotating anything:

openclaw logs --follow | rg -i "pairing required|scope-upgrade|devices"

If you see reason=scope-upgrade, use the current device CLI docs to approve or rotate only the missing scope named by the log. Do not assume every post-update pairing error requires an operator write scope.

3) Confirm what the gateway thinks is happening (logs)

On the gateway host:

openclaw logs --follow | rg -i "pairing required|scope-upgrade|devices"

If you do not see reason=scope-upgrade, treat it as ordinary pairing and do not rotate scopes.

Verify

• Control UI loads without disconnect:
  • open http://127.0.0.1:18789/
• Sub-agents work again:
  • retry your sessions_spawn call
• Cron announce delivery no longer errors (if this was the trigger):
  • wait for the next cron run

Related

• CoClaw: Control UI pairing required: /troubleshooting/solutions/control-ui-pairing-required/