OpenClaw Gateway Pairing Required? 6 Fixes That Work

TLDR

The "gateway connect failed: pairing required" error means your client cannot authenticate with the OpenClaw gateway. Check your device scopes in paired.json, verify your tokens match, and confirm the gateway is running with auth configured. This guide has six targeted fixes.

Table of Contents

• Introduction
• What Does Gateway Connect Pairing Required Mean
• Start Here: The Diagnostic Ladder
• Fix 1: Missing operator.admin Scope
• Fix 2: Token Mismatch
• Fix 3: Old clawdbot-gateway Still Running
• Fix 4: Auth Mode Not Configured
• Fix 5: LAN-Bound Gateway Without Auth
• Fix 6: Broken SSH Tunnel
• Quick Reference Table
• Key Terms
• FAQ
• Sources

Introduction

If you just installed OpenClaw, formerly Clawdbot, and your CLI spits out pairing required errors, you are not alone. This guide consolidates fixes from multiple Reddit threads, GitHub bug reports, and the official docs into one place.

These are the error variants and fixes I could track down as of February 2026. Each one maps to a specific root cause.

What Does "Gateway Connect Pairing Required" Mean?

When you run openclaw tui or open the desktop app, you might see:

gateway connect failed: Error: pairing required
gateway disconnected: pairing required | idle

The gateway is rejecting your connection. It uses WebSocket status code 1008 (policy violation) to close connections that fail authentication.

Several variations exist:

• gateway connect failed: Error: pairing required
• gateway closed (1008): pairing required
• Disconnected from gateway. disconnected (1008): unauthorized
• gateway connect: connect timed out
• disconnected (1000): no reason

They all point to auth or connection issues between your client and the gateway. The specific message narrows down where the problem is. See the quick reference table at the end to jump to the right fix.

OpenClaw Gateway Connect Pairing Required: Start Here

Run the official diagnostic ladder first:

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor

What to look for:

• gateway status should show Runtime: running and RPC probe: ok
• doctor should report no blocking issues
• Logs should not show repeated pairing required or unauthorized lines

If gateway status shows Runtime: stopped, start it with openclaw gateway start.

If the gateway runs but RPC probe: failed, the gateway is alive but your client cannot authenticate. One of the fixes below should resolve it.

Fix 1: Missing operator.admin Scope in paired.json

This comes up often on fresh VPS installs per this r/clawdbot thread.

The problem: OpenClaw creates a device entry in ~/.openclaw/devices/paired.json during install. Sometimes this entry only gets operator.read, which is not enough for CLI/TUI control.

Check it:

cat ~/.openclaw/devices/paired.json

If the scopes array looks like this, you found the problem:

"scopes": [ "operator.read" ]

Fix (manual edit):

1. Open: nano ~/.openclaw/devices/paired.json
2. Find "scopes" in your device entry
3. Change to: "scopes": [ "operator.read", "operator.admin" ]
4. Save (Ctrl+O, Enter, Ctrl+X)

If you prefer a one-liner:

python3 -c "import json, os; p = os.path.expanduser('~/.openclaw/devices/paired.json'); d = json.load(open(p)); [v['scopes'].append('operator.admin') for k,v in d.items() if 'scopes' in v and 'operator.admin' not in v['scopes']]; json.dump(d, open(p, 'w'), indent=2)"

This adds operator.admin to every device entry that is missing it.

Restart and verify:

systemctl --user restart openclaw-gateway
openclaw tui

You should see gateway connected | idle.

Fix 2: Token Mismatch Between Config and Gateway

The problem: The token in openclaw.json does not match what the gateway expects. This happens after partial upgrades, manual config edits, or running doctor --generate-gateway-token without restarting.

Symptoms: gateway closed (1008): pairing required with correct device scopes, or disconnected (1008): unauthorized.

Check it:

openclaw config get gateway.auth.token

Compare that value to your credentials directory. Mismatch means this is the issue.

Fix:

Regenerate tokens and restart:

openclaw auth regenerate
openclaw gateway restart

If auth regenerate is not available on your version:

openclaw doctor --generate-gateway-token
openclaw gateway restart

Fix 3: Old clawdbot-gateway Service Still Running

The problem: After upgrading from Clawdbot, the old service might still hold port 18789. Both gateways fighting over the same port causes restart loops.

Symptoms: another gateway instance is already listening in logs.

Check it:

sudo ss -tlnp | grep 18789

If a non-OpenClaw process owns that port, the old service is running.

Fix:

systemctl --user stop clawdbot-gateway
systemctl --user disable clawdbot-gateway
openclaw gateway start
openclaw gateway status

Fix 4: Auth Mode Not Configured on Fresh Install

The problem: A fresh install without auth setup leaves the gateway unable to authenticate anyone. Shows gateway password missing or disconnected (1008): unauthorized.

Fix:

You need to generate a token, clean up any broken config keys, set token auth as the mode, and restart. Four commands, in order:

openclaw doctor --generate-gateway-token
openclaw doctor --fix
openclaw config set gateway.auth.mode token
openclaw gateway restart

• doctor --generate-gateway-token: Creates the credentials directory and generates a secure token
• doctor --fix: Removes invalid config keys (like gateway.auth.type left over from older versions)
• config set gateway.auth.mode token: Tells the gateway to use token-based auth
• gateway restart: Applies the new configuration

Verify:

openclaw gateway status

Should show Auth Mode: token and Runtime: running.

For browser dashboard access, add the token to the URL:

http://127.0.0.1:18789/?token=YOUR_TOKEN_HERE

Fix 5: LAN-Bound Gateway Without Proper Auth

The problem: Gateways bound to a LAN IP instead of localhost require auth. Without it: refusing to bind gateway ... without auth.

Check your bind:

openclaw config get gateway.bind

If it returns lan, tailnet, or a specific IP, you need auth.

Fix:

openclaw config set gateway.auth.mode token
openclaw config set gateway.auth.token "$(openssl rand -hex 32)"
openclaw gateway restart

On any connecting machine, set the token:

export OPENCLAW_GATEWAY_TOKEN="your-token-here"

Fix 6: Broken SSH Tunnel for Remote Access

This one is not strictly a pairing error, but it mimics the symptoms. The problem: Remote VPS gateways need an SSH tunnel. A broken tunnel shows as timeouts. A mid-session tunnel drop can produce disconnected (1000): no reason.

Set up the tunnel (Windows, Mac, or Linux):

ssh -N -L 19999:127.0.0.1:18789 root@YOUR_SERVER_IP

Keep this terminal open. Closing it kills the tunnel.

Verify:

curl http://127.0.0.1:19999

You should get an HTML response from the gateway.

Access the dashboard:

http://127.0.0.1:19999/?token=YOUR_TOKEN

Replace YOUR_SERVER_IP with your server IP. Replace YOUR_TOKEN with the value from openclaw config get gateway.auth.token.

Quick Reference: Error Messages and Their Fixes

Key Terms

OpenClaw Gateway

The background process that handles communication between your AI agent and external services. It manages CLI, TUI, desktop app, web dashboard, and messaging channel connections. Listens on port 18789 by default.

Pairing

The authentication handshake between a client device and the gateway. Successful pairing needs a valid device token with correct scopes. Failed pairing triggers a 1008 WebSocket close.

WebSocket Status Code 1008

A close code meaning "policy violation." In OpenClaw, it signals that the gateway rejected your connection due to an authentication failure.

paired.json

Located at ~/.openclaw/devices/paired.json. Stores device entries with tokens and permission scopes. Each device needs operator.read and operator.admin for full CLI access.

Frequently Asked Questions

How do I manually trigger the pairing process?

Run openclaw devices list to see device entries. If that command itself fails with pairing errors, the issue is at the auth level (Fix 1 or Fix 2). Fix auth first, then pairing works automatically.

I ran openclaw doctor --fix but the error persists. Now what?

The doctor command fixes config issues but does not modify paired.json scopes. If your scopes are wrong (Fix 1), doctor will not catch it. Check paired.json manually for the operator.admin scope.

Does this error affect messaging channels like WhatsApp or Telegram?

Not directly. Channels connect through a different path than CLI/TUI. You can have working WhatsApp while CLI is stuck on pairing. But if gateway auth is completely broken (Fix 4), channels may also fail with HTTP 401 errors.

The desktop app cycles between "pairing required" and "timed out." What gives?

This is a known issue on macOS. Try the diagnostic ladder, then Fix 1 and Fix 2. If it persists, use TUI or web dashboard as alternatives while the issue is tracked upstream.

Do I need an SSH tunnel for a remote server?

Yes. The gateway binds to 127.0.0.1 by default. It only accepts local connections. To reach it from your laptop, use an SSH tunnel (Fix 6). Binding to LAN works too but requires auth (Fix 5).

Conclusion

The "gateway connect pairing required" error has several causes, but they all come down to authentication between your client and the OpenClaw gateway. Start with the diagnostic ladder, match your error message to the quick reference table, and apply the targeted fix.

If none of these fixes work, check the OpenClaw troubleshooting docs for additional scenarios, or open an issue on GitHub with your openclaw gateway status --json output.

If you are setting up OpenClaw for the first time, our OpenClaw on a $6 VPS guide walks through the full install process. For a broader list of common issues, see our OpenClaw troubleshooting guide. For comparisons with other automation platforms, check out OpenClaw vs n8n vs Make on EmergentWeirdness.

Sources

1. OpenClaw Gateway Troubleshooting (Official Docs)
2. OpenClaw Gateway-Owned Pairing (Official Docs)
3. OpenClaw Gateway Protocol (Official Docs)
4. [SOLVED] OpenClaw "gateway connect failed" on Fresh VPS (Reddit)
5. Fix OpenClaw "Disconnected from Gateway (1008)" (Ucartz)
6. OpenClaw "gateway closed (1008): pairing required" (Reddit)
7. Every OpenClaw Problem I Hit (Medium)
8. Gateway connection fails, Issue #21519 (GitHub)

Changelog

• 2026-02-24: Initial publication with 6 fix paths for gateway pairing errors.