Fix "Pairing Required" (1008)
Common Error Message
disconnected (1008): pairing requiredOpenClaw 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.
- 1.
openclaw devices list(find the new device ID) - 2.
openclaw devices approve <device-id> - 3. Retry your command — connection resumes automatically
Next Step
Fix now, then reduce repeat incidents
If this issue keeps coming back, validate your setup in Doctor first, then harden your config.
Jump to Section
Quick Fix
List pending pairing requests and approve the device:
openclaw devices list
Expected output — look for status: "pending" and copy the id:
[
{
"id": "dev_a1b2c3d4", ← copy this value
"name": "my-laptop",
"status": "pending", ← this is the one to approve
"ip": "172.17.0.2",
"requestedAt": "2026-03-01T10:23:45Z"
}
]# Paste the id from the output above openclaw devices approve dev_a1b2c3d4
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
# 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:
services:
openclaw:
image: openclaw/openclaw:latest
network_mode: hostHost 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:
# 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:
# 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.
Fix: Docker on Windows 11 — Container Path Mismatch
On Windows 11 with Docker Desktop, a common issue is that the host path ~/.openclaw/ maps to a different location inside the container (/root/.openclaw/). This path mismatch causes pairing tokens to be invisible between host and container.
Windows Host vs Container Path
C:\Users\You\.openclaw\ on the Windows host is not the same as /root/.openclaw/ inside the Linux container. Device pairing state saved on one side is invisible to the other unless you mount the volume correctly.
Step 1: Diagnose
openclaw --version openclaw gateway status
openclaw pairing list --channel discord openclaw pairing approve discord <CODE>
Step 2: Use Device Approval Workflow
If the pairing is a device/node pairing (not a DM/channel pairing), use the devices workflow instead:
openclaw devices list # Find your pending device and approve it openclaw devices approve <id>
DM/Channel Pairing vs Device/Node Pairing
DM/Channel pairing (e.g., Discord) uses openclaw pairing list --channel discord and openclaw pairing approve discord <CODE>. Device/Node pairing uses openclaw devices list and openclaw devices approve <id>. If one doesn't show your pending request, try the other.
Seeing Other Errors Too?
Pairing issues often come with these related problems:
Fix It Faster With Our Tools
Did this guide solve your problem?