If you've been setting up OpenClaw and suddenly hit a "pairing required" error when trying to connect to your gateway, don't panic. This is one of the most common issues new users encounter, and it's actually a sign that your gateway's security is working correctly. In this guide, we'll explain exactly what this error means, why it happens, and how to fix it in minutes.
What Does "Pairing Required" Mean?
OpenClaw's gateway includes a built-in security layer called device pairing. When you connect to the gateway — whether through a browser, WebSocket client, or the control UI — the gateway checks whether your device has been previously authorized. If it hasn't, the connection is rejected with a disconnected (1008): pairing required error.
Think of it like Bluetooth pairing: before two devices can communicate, they need to go through a one-time handshake to establish trust. OpenClaw uses this mechanism to prevent unauthorized access to your AI assistant's gateway, even if someone discovers your gateway URL.
This is a security feature, not a bug. The gateway is intentionally rejecting connections from unrecognized devices to protect your instance from unauthorized use. The fix is straightforward — you just need to complete the pairing process or adjust your configuration.
When Will You See This Error?
The "pairing required" error typically appears in these situations:
- Connecting from a new browser or device — Each browser profile is treated as a separate device. If you switch from Chrome to Firefox, or open the gateway on your phone for the first time, you'll need to pair again.
- After clearing cookies or browser data — The pairing identity is stored in your browser. Clearing cookies or site data removes it, making your browser appear as a new, unpaired device.
- Remote access — If you're trying to access the gateway control UI from a different machine than the one running OpenClaw, the remote browser won't have a pairing identity established.
- WebSocket disconnection and reconnection — In some cases, network interruptions can cause the gateway to require re-pairing, especially if the session state was lost on the server side.
- After restarting the OpenClaw container — Depending on your setup, restarting the container may clear the stored device identities, requiring all previously paired devices to pair again.
Method 1: Complete the Pairing Flow
The most straightforward fix is to complete the device pairing process as intended. Here's how:
- Open your gateway URL in the browser you want to pair. This is typically
http://localhost:18789for local setups, or your configured domain for remote access. - Check your terminal or container logs for a pairing code. When an unpaired device tries to connect, OpenClaw generates a short alphanumeric code and displays it in the gateway logs.
- Enter the pairing code in the browser prompt that appears on the gateway's control UI page.
- Approve the device — once the code matches, the gateway establishes a trust relationship with your browser, and future connections will work without pairing.
If you're running OpenClaw in Docker, you can view the pairing code in the container logs with docker logs your-container-name. For a detailed walkthrough with screenshots, see our complete gateway pairing guide.
Having trouble with the pairing flow? Make sure your gateway token is configured correctly first — an invalid or missing token can cause similar connection issues.
Method 2: Disable Device Pairing for Remote Access
If you're accessing the gateway remotely and find the pairing flow cumbersome — especially when you need to check logs on the server just to get a pairing code — there's a simpler option. You can disable device-identity pairing entirely by adding one line to your OpenClaw configuration:
{
"gateway": {
"controlUi": {
"allowInsecureAuth": true
}
}
}Despite the name, this setting is perfectly safe when your gateway is behind HTTPS and protected by a token. Here's why: the "insecure" in allowInsecureAuth refers specifically to skipping the device-identity pairing step. Your gateway is still protected by:
- HTTPS encryption — all traffic between your browser and the gateway is encrypted
- Token authentication — anyone connecting still needs to provide the correct gateway auth token
What you're removing is only the additional device-fingerprinting layer. For most self-hosted setups — especially those behind a reverse proxy like Caddy or Nginx with automatic HTTPS — this is a reasonable trade-off between security and convenience.
After making this change, restart your OpenClaw instance for it to take effect. Any device with the correct gateway token will be able to connect without going through the pairing flow.
How to Avoid This Error Entirely
If you'd rather not deal with gateway pairing, device identity, or configuration files at all, the easiest path is to use OpenClaw Launch — a managed hosting platform for OpenClaw.
With OpenClaw Launch, gateway pairing is handled automatically during deployment. When you create an instance through the platform, the configuration is pre-set with the correct auth settings, so you never encounter the "pairing required" error. The gateway is secured behind HTTPS with a unique token, and the control UI is accessible without manual device pairing.
This is especially useful if you're deploying OpenClaw for non-technical users — for example, setting up a Telegram or Discord bot for a team. Nobody needs to understand gateway internals or SSH into a server to approve devices. It just works.
Beyond pairing, managed hosting also eliminates other common self-hosting headaches like bots not responding and instances stuck on starting.
Skip the Troubleshooting
Gateway pairing errors are easy to fix once you understand what's happening, but they're even easier to avoid entirely. If you want to deploy an OpenClaw-powered AI assistant without worrying about gateway configuration, device pairing, or server management, try OpenClaw Launch.
You can go from zero to a working AI assistant on Telegram or Discord in under a minute — no terminal, no config files, no pairing codes. Just pick your model, connect your channels, and deploy.