openclaw pairing required 1008
OpenClaw Pairing Required 1008: root cause and fix runbook
Troubleshooting playbook for openclaw pairing required 1008, grounded in official docs plus active community issues.
1. What this error usually means
1008 means WebSocket policy/auth rejection; it is not exclusively a token-format error.
2. Three-step triage
Use a deterministic order: logs, pairing state, then connectivity.
- Check logs for `unauthorized`, `pairing required`, and `invalid-request-frame`
- Run `openclaw pairing list feishu` and `openclaw devices list`
- Verify `http://127.0.0.1:18789/healthz` and actual ws/wss target
Minimal command set for 1008 triage
docker compose logs --since=30m openclaw-gateway | rg -n "1008|pairing required|unauthorized|token|invalid-request-frame"\nopenclaw pairing list feishu\nopenclaw devices list\ncurl -fsS http://127.0.0.1:18789/healthz3. Prevent recurrence
Prevent regressions with baseline config + verification checklist.
- Template gateway token and endpoint settings
- Include pairing approval checks in release SOP
- Alert on 1008 log-rate spikes
Frequently asked questions
Is 1008 always a token issue?
No. Community reports include token issues, pairing state problems, and protocol mismatches.
How long should I observe after a fix?
At least 24 hours of traffic with no recurring 1008 events is a good baseline.