Many OpenClaw users see the message “Disconnected (1008): pairing required” when connecting the gateway to the Control UI or dashboard. This happens when the gateway and the client (browser or app) have not completed device authorization. OpenClaw enforces pairing to stop unauthorized access. When you first try to connect, the gateway expects an approved device identity and token. If these are missing or not approved, you will see the 1008 error instead of a live dashboard.
To restore the connection, you must complete the pairing and authentication process. That means providing the gateway token to the client and approving pending pairing requests. Once pairing is done, the UI connects and stays connected without showing the error.
What the Error Means
This error comes from OpenClaw’s security model. The gateway requires a valid token or approved device before it accepts WebSocket connections. The Control UI runs in a browser. That browser sends a device identity to the gateway when it tries to connect. If the gateway has not approved that identity, it rejects the connection with code 1008.
Common triggers include:
- Browsing the dashboard without a valid gateway token.
- Running OpenClaw behind Docker without forwarding or trusting local network headers.
- Reinstalling the app or clearing local browser storage, which removes stored tokens.
Resolve the Pairing Requirement
Here are the steps to resolve the pairing required error and get the gateway connected.
Retrieve and use your gateway token
- Locate the token stored on your host, often in
~/.openclaw/openclaw.jsonor a similar config file. - You can also generate a fresh token using tools like
openclaw doctor --generate-gateway-token. - In the Control UI dashboard settings, paste this token and save.
- Refresh the dashboard after saving the token to reattempt connection.
Approve pending device requests
- Use the OpenClaw CLI or container to list pending pairing requests.
- For a Docker setup, run a command such as:
docker compose exec openclaw-gateway \
node dist/index.js devices list
- You will see pending requests with IDs.
- To approve one, use:
docker compose exec openclaw-gateway \
node dist/index.js devices approve <ID>
- After approval, the dashboard should connect without the 1008 error.
Re-pair after configuration changes
- If you reinstalled the browser app or cleared storage, the stored identity is lost.
- In that case, you need to re-pair. Open the dashboard, paste the token, and approve the new device request when prompted.
Check network and proxy settings
- In some hosted environments or reverse proxies, requests reach the gateway with altered addresses.
- The gateway may treat these as untrusted and demand pairing.
- Configure trusted proxies or bind the gateway to localhost when appropriate so the client is treated as local and the token is accepted.
Additional Tips
- If you use Docker, ensure you access the dashboard at
localhost:18789. Remote hosts or ports can complicate token authentication. - After making changes, restart the gateway service with
openclaw gateway restart. - If errors persist, check the gateway logs for mismatch messages or network rejections.
Conclusion
OpenClaw stores device credentials and pairing tokens to secure remote access. This process prevents clients that have not been explicitly approved from controlling the gateway. Pairing also authorizes nodes or apps beyond the terminal CLI, so they work reliably.
With correct pairing and token configuration, the gateway connects smoothly. You then get full access to the Control UI, logs, and management tools without repeated pairing prompts.
