disconnected (1008): pairing required means the OpenClaw gateway accepted your token but does not yet trust the browser, CLI or app that is connecting. Each device has its own identity, and a new one needs a one-time approval from the gateway host. Run openclaw devices list, copy the pending request ID, then run openclaw devices approve <requestId>. The page reconnects on its own once it is approved.
The rest of this page covers the ones that keep coming back: Docker, Tailscale, a device that was already paired, cron jobs, Telegram, and the other messages that share the 1008 close code. Checked against OpenClaw 2026.9.8 (October 2026) and the official docs, which track the main branch.
Why does OpenClaw close the connection with 1008?
The gateway runs two checks on every connection. First gateway auth: do you hold the shared token or password? Then device identity: has this particular browser profile or client been approved? Pairing required is the second check failing after the first passed, so a new token will not help.
According to the Control UI pairing docs, only a direct loopback connection (127.0.0.1 on the gateway host, with no proxy headers) is approved automatically, and only after gateway auth succeeds. Any browser on your LAN, your tailnet, or a public address needs an explicit approval. Each browser profile generates its own device ID, so a second browser, cleared site data or a private window all count as a new device.
How do I approve a pending device?
On the gateway host, list the requests and approve one by its exact ID:
openclaw devices list
openclaw devices approve <requestId>Two details catch people out. First, running openclaw devices approve without an ID, or with --latest, only previews the newest request and exits with code 1; it prints the exact command to rerun (devices CLI reference). And if the browser retries with changed details (role, scopes or key), the old request is superseded by a new ID, so list again right before you approve.
As the owner, openclaw dashboard on the host is the shorter path: it opens a single-use pairing link that leaves that browser with administrator access. On a host with no browser, openclaw dashboard --json prints a browserUrl to open within ten minutes. If the login screen says Pairing link is no longer valid, the link expired or was already used; generate a fresh one. It does not mean your token is wrong.
Why does it say pairing required when the device is already paired?
Because pairing also covers upgrades. When the gateway rejects a connection, the response carries a reason: not-paired, scope-upgrade, role-upgrade or metadata-upgrade (auth detail codes). A browser paired for read access that now asks for write or admin access keeps its old approval and waits for you to approve the broader set. openclaw devices list shows the requested access next to the approved access, so an upgrade does not look like a lost pairing.
The other repeat offenders:
- Private windows and profiles that discard site data on exit forget the device identity, so they show up as new after every restart. Use a persistent profile and clear old entries with
openclaw devices remove <deviceId>. - A token that was narrowed later. Approving the request keeps the narrower limit. Run
openclaw dashboard --jsonand open the fresh link in the same browser to restore admin access.
How do I fix pairing required in Docker?
Docker breaks loopback auto-approval: through Docker NAT, your browser looks like a remote client, so it always needs an explicit approval (issue #4941). Run the commands through the CLI container, as the Docker troubleshooting page shows:
docker compose run --rm openclaw-cli dashboard --no-open
docker compose run --rm openclaw-cli devices list
docker compose run --rm openclaw-cli devices approve <requestId>If the CLI reports a gateway target like ws://172.x.x.x, or pairing errors come from the CLI itself, reset the mode and bind, then point the CLI at loopback:
docker compose run --rm openclaw-cli config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"}]'
docker compose run --rm openclaw-cli devices list --url ws://127.0.0.1:18789The lan bind is expected under bridge networking, because a loopback bind is unreachable from outside the container (Docker networking docs). One trap: once you pass --url, the CLI stops reading credentials from config, so add --token if the command errors.
How do I fix pairing required over Tailscale?
It depends on how you reach the gateway. With Tailscale Serve (openclaw gateway --tailscale serve) and gateway.auth.allowTailscale: true, a verified Tailscale identity skips the pairing round trip for Control UI operator sessions. A direct tailnet bind, or opening http://<tailscale-ip>:18789, still needs an explicit approval like any LAN browser (connect and pair).
Plain HTTP over a Tailscale IP is not the cause on current versions: since 2026.8.1 the Control UI signs its device identity in pure JavaScript, so pairing works without a secure context. That is also why the old allowInsecureAuth switch is gone; our allowInsecureAuth explainer covers what replaced it. If you see unauthorized: tailscale identity missing or tailscale proxy headers missing, the request did not arrive through Serve, so use the Serve URL or the gateway token.
Why do cron jobs fail with pairing required?
Creating or editing a scheduled job is an admin action. The cron CLI docs say every automation mutation (add, edit, remove, run) requires operator.admin. A CLI or agent whose device was approved with fewer scopes gets gateway closed (1008): pairing required: device is asking for more scopes than currently approved (issue #131096), while cron list still works. Run openclaw devices list, check that the pending request asks only for what you expect, and approve it.
Is Telegram "pairing required" the same thing?
No. That is DM pairing, which decides who may message your bot, not which devices may control the gateway. With the default dmPolicy: pairing, an unknown sender gets an 8 character code and their message is not processed until you approve it (pairing docs):
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>Codes expire after one hour, each channel account holds at most three pending requests, and the bot only sends a code when it creates a new request, roughly once an hour per sender. If someone says the bot went silent, list pending codes first. Approval grants direct messages only, not group access.
What do the other 1008 errors mean?
The same close code carries several messages. The strings below are copied from the 2026.9.8 source (auth-messages.ts) and the dashboard 1008 guide.
| Message | What it means | Fix |
|---|---|---|
pairing required | New device, or an upgrade waiting | openclaw devices list, then approve the ID |
unauthorized: gateway token missing | The client sent no shared token | Run openclaw gateway auth-token --show on the host and paste it into the Control UI settings |
unauthorized: gateway token mismatch | Old token, or a different gateway | Use this gateway's gateway.auth.token; remote CLIs set gateway.remote.token |
unauthorized: device token mismatch | The cached per-device token is stale or revoked | openclaw devices rotate --device <deviceId> --role operator |
unauthorized: device token scope mismatch | Token recognized, scopes too narrow | Approve the scope upgrade; do not rotate the shared token |
unauthorized: gateway token not configured on gateway | Token auth with no token set | Set gateway.auth.token, or openclaw doctor --generate-gateway-token and restart |
unauthorized: too many failed authentication attempts (retry later) | Rate limited after bad attempts | Wait, then retry with the right token |
control ui requires HTTPS or localhost (secure context) | A Control UI older than 2026.8.1 | Update, or use Tailscale Serve or an SSH tunnel |
If rotation does not clear a token mismatch, the token drift checklist removes the stale pairing and approves again:
openclaw devices remove <deviceId>
openclaw devices list
openclaw devices approve <requestId>If the trouble started right after an upgrade, pending approvals are one item on a longer list; our post on OpenClaw breaking after an update walks the rest.
What this looks like when someone else runs the gateway
Most 1008 errors come from reaching a gateway from another machine, a container or a tailnet. On Qoren's managed OpenClaw hosting, each agent's gateway runs as its own systemd unit on your environment, and the console sends turns through the openclaw CLI on that same machine. You chat in the console, the Qoren CLI or a chat app, so there is no browser to pair before your agent can answer. A daily checkup runs openclaw doctor on every live agent and repairs what it can. If you prefer to keep your own box, the OpenClaw security checklist covers binding and auth so you only open the doors you mean to.