Fix "Pairing Required" (1008)

Common Error Message

disconnected (1008): pairing required

OpenClaw requires devices to be paired (approved) before they can connect to the Gateway. Local connections (from the same machine) are auto-approved, but Docker containers, LAN clients, and remote nodes need explicit approval.

Next Step

Fix now, then reduce repeat incidents

If this issue keeps coming back, validate your setup in Doctor first, then harden your config.

Open Doctor Harden Config

Need proactive alerts? Join Monitor early access.

Jump to Section

Quick Fix How Device Pairing Works Docker NAT Issue LAN / Remote Access Control UI Access Insecure Workaround

Quick Fix

List pending pairing requests and approve the device:

List pending requests

openclaw devices list

Approve a device

# Replace <request-id> with the ID from the list above
openclaw devices approve <request-id>

The client should automatically reconnect within a few seconds.

How Device Pairing Works

Client connects to Gateway WebSocket

The client sends a pairing request with its device identity.

Gateway checks if auto-approval applies

Connections from localhost/loopback are auto-approved. Everything else is held as "pending".

User approves via CLI or Control UI

Run "openclaw devices approve <id>" or click Approve in the web dashboard.

Gateway issues an auth token

The device receives a token, stores it in ~/.openclaw/nodes/paired.json, and reconnects.

Pending requests expire after 5 minutes

If not approved within 5 minutes, the request is discarded. The client must retry.

Auto-Approval Rules

Localhost / loopback connections are always auto-approved — no manual step needed. This includes 127.0.0.1, ::1, and the host's own Tailnet address. All other connections (LAN, Docker NAT, remote) require explicit approval.

Fix: Docker NAT Networking

This is the most common cause of "pairing required". Docker's NAT bridge translates the container's IP, so the Gateway sees an external address — not localhost — and skips auto-approval.

Option A: Approve from Inside the Container

Approve device from Docker container

# List pending requests inside the container
docker compose exec openclaw openclaw devices list

# Approve the request
docker compose exec openclaw openclaw devices approve <request-id>

Option B: Use Host Networking

Host networking makes the container use the host's network stack directly, so connections appear as localhost:

docker-compose.yml with host networking

services:
  openclaw:
    image: openclaw/openclaw:latest
    network_mode: host

Host Networking Trade-off

network_mode: host bypasses Docker's network isolation. Use this only on dedicated servers or development machines — not in multi-tenant environments.

Fix: LAN / Remote Access

When accessing the OpenClaw dashboard or API from another machine on your LAN (e.g., http://192.168.1.100:18789), you need to approve the device from the server running OpenClaw:

Approve LAN device

# On the server running OpenClaw:
openclaw devices list

# Find the pending request from the LAN IP and approve it
openclaw devices approve <request-id>

For Tailnet (Tailscale) peers, the Gateway recognizes the Tailnet address and may auto-approve depending on your configuration.

Fix: Control UI Dashboard

The web Control UI needs a secure context (HTTPS or localhost) to generate a device identity. Without it, the identity handshake fails before pairing logic even triggers.

Access via localhost

Use http://localhost:18789 instead of http://192.168.x.x:18789 when on the same machine

Use HTTPS reverse proxy

For remote access, put Nginx or Caddy in front with TLS to provide a secure context

Use Tailscale

Tailscale provides automatic HTTPS certificates via MagicDNS

Insecure Workaround (Development Only)

For local development only, you can bypass the pairing requirement entirely:

Disable pairing (insecure)

# WARNING: Only use for local development
openclaw config set gateway.controlUi.allowInsecureAuth true
openclaw gateway restart

Security Warning

Setting allowInsecureAuth: true disables device authentication entirely. Never use this in production or on a publicly accessible server. Anyone who can reach the Gateway port can connect and control your agents.

Seeing Other Errors Too?

Pairing issues often come with these related problems:

Gateway Monitor detects when your Gateway goes offline or restarts unexpectedly — so you can reapprove devices before your automations fail.

Get Early Access

Fix It Faster With Our Tools

Config Wizard

Generate a production-ready clawhub.json in 30 seconds.

Local Doctor

Diagnose Node.js, permissions, and config issues instantly.

Cost Simulator

Calculate your agent burn rate before you get surprised.

Did this guide solve your problem?