Resolving the OpenClaw Gateway Connect Pairing Required (1008) Error: A Comprehensive Guide
OpenClaw users frequently encounter the Disconnected (1008): pairing required error when attempting to connect the gateway to the Control UI or dashboard. This issue arises when the gateway and the client (browser or application) have not completed the necessary device authorization process. OpenClaw enforces this pairing mechanism to prevent unauthorized access. Upon initial connection attempts, the gateway expects an approved device identity and token. If these credentials are absent or unapproved, the system displays the 1008 error instead of granting access to the live dashboard.
To reestablish the connection, it’s essential to complete the pairing and authentication process. This involves providing the gateway token to the client and approving any pending pairing requests. Once this process is successfully completed, the UI will connect seamlessly without displaying the error.
Understanding the Error
The Disconnected (1008): pairing required error is rooted in OpenClaw’s security framework. The gateway mandates a valid token or an approved device before accepting WebSocket connections. When the Control UI operates within a browser, it sends a device identity to the gateway during connection attempts. If the gateway hasn’t approved that identity, it rejects the connection, resulting in the 1008 error.
Common scenarios that trigger this error include:
– Absence of a Valid Gateway Token: Accessing the dashboard without a valid gateway token can lead to this error.
– Docker Configuration Issues: Running OpenClaw behind Docker without properly forwarding or trusting local network headers can cause the gateway to reject connections.
– Application Reinstallation or Browser Data Clearance: Reinstalling the application or clearing local browser storage can remove stored tokens, necessitating reauthorization.
Steps to Resolve the Pairing Requirement
To address the pairing required error and restore the gateway connection, follow these steps:
1. Retrieve and Utilize Your Gateway Token:
– Locate the Token: The gateway token is typically stored on your host machine, often found in the `~/.openclaw/openclaw.json` configuration file.
– Generate a New Token (if necessary): If the token is missing or you prefer to generate a new one, use the command:
“`bash
openclaw doctor –generate-gateway-token
“`
– Input the Token into the Control UI: Access the Control UI dashboard settings, paste the retrieved or newly generated token into the appropriate field, and save the changes.
– Refresh the Dashboard: After saving the token, refresh the dashboard to attempt reconnection.
2. Approve Pending Device Requests:
– List Pending Pairing Requests: Utilize the OpenClaw Command Line Interface (CLI) or container to view pending pairing requests. For Docker setups, execute:
“`bash
docker compose exec openclaw-gateway \
node dist/index.js devices list
“`
– Identify Pending Requests: The command will display a list of pending requests along with their respective IDs.
– Approve the Pending Request: To approve a specific request, use the following command, replacing `
“`bash
docker compose exec openclaw-gateway \
node dist/index.js devices approve
“`
– Verify Connection: Once approved, the dashboard should connect without displaying the 1008 error.
3. Re-pair After Configuration Changes:
– Address Lost Stored Identity: If you’ve reinstalled the browser application or cleared browser storage, the stored device identity may be lost.
– Initiate Re-pairing: Open the dashboard, input the gateway token as previously described, and approve the new device request when prompted.
4. Check Network and Proxy Settings:
– Assess Hosted Environments or Reverse Proxies: In certain hosted environments or when using reverse proxies, requests may reach the gateway with altered addresses.
– Configure Trusted Proxies: Ensure that trusted proxies are configured correctly or bind the gateway to localhost. This configuration helps the client be recognized as local, allowing the token to be accepted.
Additional Tips
– Docker Users: If you’re utilizing Docker, ensure that you access the dashboard at `localhost:18789`. Accessing it via remote hosts or different ports can complicate token authentication.
– Restart Gateway Service: After implementing changes, restart the gateway service to apply them:
“`bash
openclaw gateway restart
“`
– Review Gateway Logs: If the error persists, examine the gateway logs for messages indicating mismatches or network rejections.
Conclusion
OpenClaw employs device credentials and pairing tokens to secure remote access, preventing unauthorized clients from controlling the gateway. This pairing process also authorizes nodes or applications beyond the terminal CLI, ensuring reliable operation.
By correctly configuring pairing and token settings, the gateway can connect smoothly, granting full access to the Control UI, logs, and management tools without recurring pairing prompts.
