Fix OpenClaw Gateway “Pairing Required” Error

What Does “Pairing Required” Mean in OpenClaw?

When you see the error disconnected (1008): pairing required in your browser while trying to connect to the OpenClaw gateway web UI, it means the gateway's device pairing security feature has blocked your connection. This is not a bug — it is an intentional security mechanism built into OpenClaw's gateway server.

By default, OpenClaw requires each device (browser) to be “paired” with the gateway before it can communicate. Pairing works automatically when you access the gateway from localhost (the same machine the gateway runs on). However, when you connect remotely — from a different computer, through a VPS, or via a reverse proxy — the gateway sees your connection as an untrusted device and rejects it with error code 1008.

According to community reports, the openclaw gateway connect failed error pairing required message is the single most common issue users encounter when deploying OpenClaw for the first time on a remote server. It affects an estimated 70% of new self-hosted deployments because most users run OpenClaw on a VPS or cloud server, not on their local machine.

Who Is Affected by This Error?

The OpenClaw gateway pairing required error impacts several common deployment scenarios:

• VPS / cloud server users — If you're running OpenClaw on DigitalOcean, Hetzner, Vultr, AWS, or any remote server and trying to access the web UI from your local browser, you will see this error.
• Docker with port forwarding — Running OpenClaw in Docker with -p 18789:18789 and accessing it via the host's IP address (not localhost) triggers the pairing requirement.
• Users behind a reverse proxy — If you use Caddy, Nginx, or Traefik to proxy traffic to the OpenClaw gateway port (18789), the gateway sees the proxy's IP instead of your device, causing the pairing error.
• LAN access from another machine — Accessing OpenClaw via your server's local network IP (e.g., 192.168.1.100:18789) instead of localhost:18789 also triggers pairing.
• Headless server setups — Servers without a desktop environment cannot run a local browser, so every connection is remote by definition.

Understanding the Error in Detail

The full error message typically appears in the browser console or the OpenClaw gateway web UI as:

disconnected (1008): pairing required

The 1008 is a WebSocket close code meaning “policy violation.” The gateway is telling your browser: “I don't recognize this device, and my security policy requires you to be paired before I allow a connection.”

OpenClaw's device-identity pairing system works by creating a cryptographic fingerprint of each connecting browser. When you access from localhost, the gateway automatically trusts the connection and creates a pairing record. Remote connections don't get this automatic trust, so they fail with the pairing required error.

Fix 1: Enable allowInsecureAuth (Recommended)

The most straightforward fix for the OpenClaw gateway pairing error is to disable device-identity pairing and use token-only authentication instead. This is the approach recommended by the OpenClaw community for self-hosted deployments.

Open your OpenClaw configuration file, usually located at ~/.openclaw/openclaw.json, and add or modify the gateway section:

{
  "gateway": {
    "controlUi": {
      "allowInsecureAuth": true
    },
    "auth": {
      "token": "your-secret-token-here"
    }
  }
}

Replace your-secret-token-here with a strong, random token. A UUID works well — you can generate one with:

python3 -c "import uuid; print(uuid.uuid4())"

Or use any password generator to create a random string of 32+ characters.

What Does allowInsecureAuth Do?

Setting allowInsecureAuth: true tells the OpenClaw gateway to skip device-identity pairing entirely. Instead of requiring both a paired device and a valid token, the gateway will accept connections from any device that presents the correct authentication token.

The name “insecure” is slightly misleading. This setting does not disable authentication — it only disables the device fingerprint check. Your gateway is still protected by the token. As long as you:

• Use a strong, random token (UUID or 32+ character string)
• Serve the gateway over HTTPS (via a reverse proxy like Caddy or Nginx)
• Never share or expose your token publicly

...this configuration is safe for production use. The combination of HTTPS encryption and a random UUID token provides robust security for remote access.

Important: gateway.auth Must Be an Object

A common mistake when configuring OpenClaw gateway auth is passing the token as a plain string. This will not work:

// WRONG - auth as a string
{
  "gateway": {
    "auth": "my-token"
  }
}

The gateway.auth field must be an object with a token property:

// CORRECT - auth as an object
{
  "gateway": {
    "auth": {
      "token": "my-token"
    }
  }
}

Similarly, auth: "none" and auth: { type: "none" } are both invalid and will cause the gateway to reject all connections.

After Changing the Config

Restart the OpenClaw container for the changes to take effect. If you're using Docker:

docker restart openclaw

Then open the gateway web UI in your browser. You should now be prompted for the authentication token instead of seeing the pairing required error. Enter the token you configured, and the connection will be established.

Fix 2: Set Up a Reverse Proxy with HTTPS

If you are accessing the OpenClaw gateway over the internet, you should use a reverse proxy with HTTPS regardless of which authentication method you choose. This fix is especially important if you skipped Fix 1 and want to keep device pairing enabled — the reverse proxy must correctly forward client identity information.

Caddy (Recommended)

Caddy is the easiest reverse proxy to set up because it handles SSL certificates automatically. Add this to your Caddyfile:

openclaw.yourdomain.com {
    reverse_proxy localhost:18789
}

Caddy will automatically obtain and renew a Let's Encrypt certificate for your domain. No additional SSL configuration is needed.

Nginx

For Nginx, you need to configure SSL manually and proxy WebSocket connections:

server {
    listen 443 ssl;
    server_name openclaw.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/openclaw.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/openclaw.yourdomain.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:18789;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Critical: Configure trustedProxies

When using a reverse proxy, you must add the proxy's IP address to the trustedProxies list in your openclaw.json configuration. Without this, the gateway cannot correctly identify the real client IP address, which breaks both pairing and rate limiting.

{
  "gateway": {
    "trustedProxies": ["172.17.0.1"],
    "controlUi": {
      "allowInsecureAuth": true
    },
    "auth": {
      "token": "your-secret-token-here"
    }
  }
}

Important: The trustedProxies field only accepts exact IP addresses. It does not support CIDR notation or subnet ranges. OpenClaw's internal isTrustedProxyAddress()function performs a strict string comparison (===), so you must use the exact IP.

Fix 3: Connect from Localhost

The simplest workaround — if your setup allows it — is to access the OpenClaw gateway from the same machine it runs on. Connections from localhost are automatically trusted and skip the pairing requirement entirely.

If OpenClaw is running on your local machine (Mac, Windows with WSL2, or Linux desktop), simply open your browser and navigate to:

http://localhost:18789

This avoids the openclaw gateway connect pairing required error because the gateway recognizes localhost connections as trusted by default.

SSH Tunnel for Remote Servers

If OpenClaw is running on a remote server (VPS), you can create an SSH tunnel to make it appear as a localhost connection. This is useful for one-off access without changing the gateway configuration:

ssh -L 18789:localhost:18789 user@your-server-ip

With the tunnel active, open http://localhost:18789 in your local browser. The traffic is securely forwarded to the remote server through SSH, and the gateway sees it as a localhost connection.

However, this approach has limitations: the tunnel must stay open, you need SSH access, and it only works for a single user at a time. For permanent remote access, Fix 1 (allowInsecureAuth) combined with Fix 2 (reverse proxy with HTTPS) is the better solution.

Complete Recommended Configuration

For a fully working remote OpenClaw setup that resolves the gateway pairing required error and follows security best practices, here is the complete openclaw.json gateway section:

{
  "gateway": {
    "port": 18789,
    "controlUi": {
      "allowInsecureAuth": true
    },
    "auth": {
      "token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    },
    "trustedProxies": ["172.17.0.1"]
  },
  "models": {
    "providers": {
      "openrouter": {
        "apiKey": "sk-or-v1-your-key-here"
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/anthropic/claude-sonnet-4.6"
      }
    }
  }
}

This configuration disables device pairing (token-only auth), trusts the Docker bridge gateway IP, and is safe for production when served behind HTTPS.

Troubleshooting Checklist

If you are still seeing the openclaw gateway connect failed error pairing required message after applying the fixes above, work through this checklist:

1. Did you restart the container? — OpenClaw only reads the config file on startup. After editing openclaw.json, you must run docker restart openclaw.
2. Is the config file being mounted correctly? — Check with docker exec openclaw cat /home/node/.openclaw/openclaw.json to verify the container sees your updated config.
3. Is the JSON valid? — A single syntax error (missing comma, extra bracket) will prevent OpenClaw from reading the config. Validate with python3 -m json.tool ~/.openclaw/openclaw.json.
4. Are file permissions correct? — The OpenClaw container runs as user node (uid 1000). The config directory needs read access. Run chmod 777 ~/.openclaw and chmod 644 ~/.openclaw/openclaw.json if needed.
5. Is the gateway port accessible? — Ensure port 18789 is open in your firewall and the Docker port mapping is correct ( -p 18789:18789).
6. Check the container logs — Run docker logs openclaw --tail 50 to see if there are any startup errors or config parsing failures.
7. Is trustedProxies set correctly? — If using a reverse proxy, verify the proxy IP is an exact match (no CIDR ranges). Check with docker network inspect bridge.

The Easy Way: Use OpenClaw Launch

All three fixes above require editing JSON config files, managing Docker containers, setting up reverse proxies, and debugging networking issues. If you'd rather skip all of that, there is a simpler option.

OpenClaw Launch is a managed hosting platform purpose-built for OpenClaw. It handles gateway configuration, SSL, authentication, and networking automatically. You never see the pairing required error because everything is pre-configured for secure remote access out of the box.

With OpenClaw Launch, you configure your AI agent visually — pick your model (Claude, GPT, Gemini, DeepSeek), connect your chat platform (Telegram, Discord, or browser), and click deploy. Your OpenClaw instance is live in under 30 seconds with secure gateway access, proper authentication, and SSL included. No config files, no Docker commands, no reverse proxy setup, and no pairing errors.

Frequently Asked Questions

What does “pairing required” mean in OpenClaw?

It means the OpenClaw gateway's device-identity security feature is blocking your browser connection. The gateway requires each device to be “paired” (cryptographically verified) before it allows access. Localhost connections are automatically paired, but remote connections — from a different computer, through Docker port forwarding, or via a reverse proxy — are blocked by default. You can fix this by enabling allowInsecureAuth in the gateway config to switch to token-only authentication.

How do I fix the OpenClaw gateway pairing error?

The fastest fix is to add "controlUi": { "allowInsecureAuth": true } to the gateway section of your openclaw.json config file, along with a strong authentication token. Then restart the OpenClaw container. For production deployments, also set up a reverse proxy (Caddy or Nginx) with HTTPS. See the full instructions above.

Is allowInsecureAuth safe to use?

Yes, when used correctly. Despite the name, allowInsecureAuth does not disable authentication — it only disables the device fingerprint check. Your gateway is still protected by token-based authentication. Combined with HTTPS (via a reverse proxy) and a strong random token (UUID or 32+ characters), this is a secure configuration used by the majority of self-hosted OpenClaw deployments.

Why does OpenClaw gateway disconnect with error 1008?

WebSocket close code 1008 means “policy violation.” In the context of OpenClaw, it specifically means the gateway's device pairing policy rejected your connection because your browser has not been paired with the gateway. This happens whenever you connect from a non-localhost address without having allowInsecureAuth enabled.

How do I connect to OpenClaw gateway remotely?

To connect to an OpenClaw gateway running on a remote server: (1) enable allowInsecureAuth: true in the gateway config, (2) set a strong authentication token, (3) optionally set up a reverse proxy with HTTPS for encrypted connections, and (4) add the proxy IP to trustedProxies if using a reverse proxy. After restarting OpenClaw, access the web UI via your server's domain or IP and enter the token when prompted.

Related Guides

• How to install OpenClaw — Step-by-step setup guide for self-hosting
• What is OpenClaw? — Complete overview of the framework
• OpenClaw AI Agent guide — What your AI agent can do once it's running
• OpenClaw Manual — Chat commands and daily usage