Complete Fix Guide for the “gateway connect pairing required" Error For OpenClaw

Complete Fix Guide for the “Pairing Required” Error

If you are seeing any of these errors, you are in the right place:

• gateway connect failed: Error: pairing required
• gateway closed (1008): pairing required
• disconnected (1008): pairing required
• Node host logs show pairing required but you never get a request ID

This problem is common when you run OpenClaw across devices (local machine + VPS), behind Docker NAT, or behind a reverse proxy. The good news is: it is usually a security policy doing its job, and you can resolve it safely.

This guide explains what “pairing required” actually means, why it happens, and exactly how to fix it.

Related reading (if you are deciding between self-hosting and managed):
How to choose the right OpenClaw deployer
Best OpenClaw Deployer

What “Pairing Required” Means in OpenClaw

OpenClaw Gateway uses pairing as an access-control layer for devices and clients that try to connect.

When the gateway sees a connection as “remote” or “untrusted,” it may block the session and require you to approve that device first.

In plain English:

• Your client is reaching the gateway
• Authentication is not being accepted as sufficient for that connection
• The gateway wants an approval step (pairing) before it allows actions

Fast Diagnosis: Identify Which Case You Have

Use the section that matches what you are seeing.

Case A: You Can Open the Gateway UI, but It Says Pairing Required (1008)

This typically happens when the dashboard connection is being treated as remote or coming from a proxy/NAT network, even though you are on the same machine. This is common with Docker Desktop and some proxy setups.

Case B: CLI or Node Host Shows Pairing Required, and You See Pending Devices

This is the easiest case. You just need to approve the pending device request.

Case C: CLI or Node Host Shows Pairing Required, but No Request ID Appears

This happens most often with remote gateway + Windows node host combinations, or when a proxy is blocking or rewriting identity information.

Case D: You Fixed Pairing Required, but Now You Get Token Mismatch Errors

You may see an “unauthorized token mismatch” message that mentions aligning tokens. This is a separate configuration mismatch and is fixable.

The Safe Fix Path (Works for Most People)

This is the most reliable sequence to resolve pairing required without weakening security.

Step 1: Confirm You Are Connecting to the Correct Gateway URL

If the gateway URL is wrong, OpenClaw may fail in confusing ways. In general, “gateway connect failed” can be a wrong URL, and “pairing required” is an approval state.

Confirm what your CLI or node host is targeting and that it matches your gateway host and port.

Step 2: List Pending Devices on the Gateway

Run the device list command from the gateway environment (or inside the gateway container if using Docker).

If you are running gateway in Docker, execute the command inside the gateway container.

Your goal is to find a pending device request.

Step 3: Approve the Pending Request

Approve the pending request using the request ID shown in the list output.

After approval:

• Refresh the dashboard
• Retry your CLI command
• Restart node host if necessary

Step 4: Verify the Connection Is Stable

Use diagnostic commands and logs to confirm state changes.

If it reconnects and stays connected, you are done.

Fixes by Environment (The Real Causes)

Most pairing-required issues come from one of these root causes.

1) Docker Desktop or Docker NAT Makes the Dashboard Look “Remote”

If you run OpenClaw Gateway in Docker on Windows or some desktop setups, the browser connects to localhost, but the gateway sees the incoming address as a Docker network IP instead of true localhost.

The gateway then enforces pairing because it thinks the request is remote.

What Works

• Run the gateway in a way that preserves real localhost behavior
• Avoid the Docker NAT path for the dashboard connection
• Run the gateway natively as a workaround

When to Use This

• Dashboard shows disconnected (1008): pairing required
• Token in URL does not help
• Logs show Docker subnet IPs

2) Reverse Proxies (Railway, Tunnels, and “Trusted Proxy” Problems)

When OpenClaw Gateway sits behind a proxy, it may not trust the proxy source and treats incoming requests as remote.

This triggers pairing enforcement.

What Works

• Configure trusted proxy networks correctly
• Restrict proxy ranges
• Test direct access without proxy

When to Use This

• You host behind tunnels or reverse proxies
• Pairing appears despite valid tokens

3) First-Time Connection Requires Approval (Normal Behavior)

Sometimes pairing required is simply the expected first-time approval step.

What Works

• List devices
• Approve pending request
• Refresh and retry

This is the most common case.

4) Windows Node Host to Linux Gateway: No Request ID

If pairing appears but no request ID shows:

Possible Causes

• Version mismatch
• Identity flow blocked
• Network translation issues

What to Try

1. Align gateway and node host versions
2. Restart gateway cleanly
3. Check logs
4. Test direct networking

If needed, use WSL or Linux temporarily for pairing.

5) Token Mismatch After Pairing

After pairing attempts, some users encounter token mismatch errors.

What to Do

• Verify gateway and client tokens match
• Restart gateway
• Retry pairing

Full Troubleshooting Checklist

Use this if you are stuck:

1. Confirm gateway host and port
2. Verify auth token
3. Restart gateway
4. List pending devices
5. Approve request
6. Test without Docker NAT
7. Test without proxy
8. Align versions

How to Prevent Pairing Required Issues

You should not disable pairing. It protects your system.

Instead:

• Keep dashboard private
• Use firewall rules
• Align OpenClaw versions
• Simplify networking
• Avoid unnecessary proxies

A clean network setup prevents recurring issues.

FAQ

Is Pairing Required a Bug?

Sometimes in specific Docker or proxy environments, but most cases are normal security behavior.

Why Is the Error Code 1008?

It is a WebSocket policy violation indicating rejected connections.

Why Does It Appear After Server Changes?

New IPs or networks create new device identities that require approval.

Conclusion

“Gateway connect pairing required” means OpenClaw is protecting your gateway from unapproved access.

Fix it safely by:

• Listing devices
• Approving requests
• Aligning tokens
• Fixing Docker and proxy networking

If you share your setup (VPS, Docker, OS, error logs), I can give you the fastest resolution path.