Fix 'OpenClaw Pairing Required' Error with openclaw doctor --fix (2026)

You open your browser, navigate to your OpenClaw instance, and instead of the familiar chat interface you see:

Pairing Required
Enter the pairing code displayed in your terminal.

Or worse, your Telegram bot suddenly stops responding and the logs show:

WARN  device not paired — rejecting connection from device abc123

This is the OpenClaw device pairing system doing exactly what it was designed to do: rejecting unrecognized connections. The good news is that fixing it takes about 30 seconds once you understand what happened.

Why OpenClaw Has Device Pairing

OpenClaw runs as a personal assistant with access to your email, calendar, files, and potentially sensitive data. Device pairing is a security mechanism that ensures only your explicitly approved devices can connect to your gateway^[1].

When a new device (browser, Telegram client, or API connection) first connects to the gateway, it is placed in a "pending" state. The device cannot send or receive messages until you approve it from the command line. This prevents unauthorized access even if someone discovers your gateway URL.

When and Why "Pairing Required" Appears

The error surfaces in several scenarios. Understanding which one applies to you determines the fastest fix.

Scenario 1: New Browser or Device

The most obvious case. You are connecting from a device that has never been paired before -- a new laptop, phone, or a browser you have not used with OpenClaw.

Scenario 2: Cleared Browser Cookies or Data

OpenClaw stores a device token in your browser's local storage. If you clear cookies and site data, run a privacy cleaner, or use incognito mode, the device token is gone. The gateway sees you as a brand new device.

Scenario 3: Container Restart Without OPENCLAW_GATEWAY_TOKEN

This is the most common cause and the least obvious one. In Docker deployments, the gateway regenerates its authentication token on every container restart unless the OPENCLAW_GATEWAY_TOKEN environment variable is explicitly set^[2]. When the token changes, every previously paired device becomes "unknown" to the gateway -- they are still presenting the old token.

Scenario 4: Gateway Token Mismatch After Update

After updating OpenClaw, the internal token format occasionally changes. Existing device pairings may become invalid.

Scenario 5: Reverse Proxy Stripping Headers

If you are running OpenClaw behind Nginx, Caddy, or another reverse proxy, misconfiguration can strip the X-Device-Token header. The gateway never receives the device's credentials, so it treats every request as a new unpaired device.

Fix 1: openclaw doctor --fix (Recommended)

The fastest path to resolution. The openclaw doctor command detects pairing issues and the --fix flag resolves them automatically:

openclaw doctor --fix

Example output:

CHECK  device pairing status
FAIL   2 devices pending approval
FIX    approving all pending devices...
OK     2 devices approved

CHECK  gateway token consistency
FAIL   device token mismatch detected
FIX    regenerating tokens and re-pairing...
OK     tokens synchronized

The --fix flag handles both pending device approvals and token mismatches in one pass. After running it, refresh your browser or restart your Telegram client.

Fix 2: Manual Device Approval

If you prefer to approve devices individually (recommended when you want to verify each connection):

# List all devices and their status
openclaw devices list

Output:

ID          STATUS     TYPE       LAST SEEN
abc123      pending    browser    2026-02-24 10:30
def456      approved   telegram   2026-02-24 09:15
ghi789      pending    browser    2026-02-24 10:32

Approve specific devices:

# Approve by device ID
openclaw devices approve abc123

# Approve all pending devices at once
openclaw devices approve --all

For Telegram pairing specifically, you may need to use the pairing code flow:

# Get the Telegram pairing code from your bot
# Then approve it
openclaw pairing approve telegram <CODE>

Fix 3: Set OPENCLAW_GATEWAY_TOKEN (Prevent Recurrence)

If you are running in Docker and the error keeps returning after container restarts, this is the permanent fix:

# Generate a stable token
openssl rand -hex 32

Then set it in your Docker run command or docker-compose file:

# docker-compose.yml
services:
  openclaw:
    image: openclaw-stack
    environment:
      - OPENCLAW_GATEWAY_TOKEN=your_generated_token_here
    volumes:
      - openclaw_data:/data

Or with docker run:

docker run -d \
  -e OPENCLAW_GATEWAY_TOKEN=your_generated_token_here \
  -v openclaw_data:/data \
  openclaw-stack

With this variable set, the gateway uses the same token across restarts and device pairings persist^[3].

Fix 4: Check Reverse Proxy Configuration

If devices keep needing re-pairing even with OPENCLAW_GATEWAY_TOKEN set, your reverse proxy may be stripping the device token header.

For Caddy:

yourdomain.com {
    reverse_proxy localhost:3001 {
        # Ensure WebSocket upgrade works
        header_up X-Real-IP {remote_host}
    }
}

Caddy passes all headers by default, so this is rarely the issue. But verify WebSocket upgrade is working -- the gateway uses WebSocket for persistent connections.

For Nginx:

location / {
    proxy_pass http://localhost:3001;
    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;
    # Critical: do not strip custom headers
    proxy_pass_request_headers on;
}

Also check that gateway.trustedProxies is configured in OpenClaw:

openclaw config set gateway.trustedProxies '["127.0.0.1"]'
openclaw restart

Prevention: Stop It From Happening Again

Once you have resolved the immediate error, take these steps to prevent recurrence:

1. Always Set OPENCLAW_GATEWAY_TOKEN in Docker

This cannot be overstated. It is the single most common cause of repeated pairing issues in containerized deployments.

2. Avoid Clearing Site Data for Your OpenClaw Domain

If you use browser cleaning tools, add your OpenClaw domain to the exclusion list. The device token stored in local storage is essential for maintaining the pairing.

3. Use a Dedicated Browser Profile

Consider creating a browser profile specifically for OpenClaw. This isolates its data from your regular browsing cleanup routines.

4. Monitor with openclaw doctor

Run openclaw doctor periodically (or set up a cron job) to catch issues before they become problems:

# Add to crontab for daily health checks
0 8 * * * openclaw doctor >> /var/log/openclaw-health.log 2>&1

Managed Hosting Avoids This Entirely

The device pairing system exists to protect self-hosted instances that may be exposed to the internet. With managed hosting through ClawTank, the gateway token, reverse proxy headers, and device management are handled automatically. The pairing infrastructure still exists, but the initial pairing is completed during the one-click setup process -- you never see a "pairing required" screen.

Quick Reference

References

1. OpenClaw Security Model -- Device Pairing
2. OpenClaw Docker Environment Variables
3. OpenClaw Gateway Token Persistence