The "pairing required" error is one of OpenClaw's most confusing because it shows up in completely different situations with different root causes. The WebSocket close code 1008 is the common thread, but what causes it varies significantly.

The OpenClaw team has shipped multiple fixes for different variants of this error across the 3.31 and 4.x release series. If you're hitting it, here's how to identify exactly which variant you have.

Step 1 — Identify Your Variant

Run the gateway with verbose logging and reproduce the error:

openclaw gateway start --verbose 2>&1 | grep -i "pairing\|1008\|token\|auth"

Then match your error message to one of the causes below.

Cause 1 — Local Exec Failing After 3.31

Symptoms

Local exec and node clients fail with pairing-required after upgrading to 3.31+. Previously worked fine. Error appears even when running commands from the same machine as the gateway.

Root cause: The 3.31 update changed how the gateway handles legacy-role fallback for empty paired-device token maps. If your exec-approvals.json had no paired devices listed, the gateway incorrectly required pairing for local connections.

Fix: Update to a version that includes the loopback fix (3.31+ patch series or 4.x). If you're on an older build:

openclaw gateway restart

If that doesn't help, explicitly add a local device entry:

# In ~/.openclaw/openclaw.json
"gateway": {
  "bind": "127.0.0.1",
  "localExec": {
    "requirePairing": false
  }
}

Cause 2 — Sub-Agent Spawning Dies with "pairing required"

Symptoms

sessions_spawn fails. Error in gateway log: close(1008) "pairing required". Happens when the agent tries to spin up a sub-agent or isolated session.

Root cause: The sub-agent's gateway call was making a loopback scope-upgrade request (from agent privilege level to operator.admin) but the pairing requirement was incorrectly enforced on loopback connections. Fixed in a 4.x patch that pins admin-only sub-agent gateway calls to operator.admin while keeping the parent agent at least privilege.

Fix: Upgrade to the patched version. Check the releases page for the sub-agent fix. If you need to stay on your current version:

# Explicitly set sub-agent scope in your agent config
"agents": {
  "subagents": {
    "allowGatewaySubagentBinding": true,
    "scope": "operator.admin"
  }
}

Cause 3 — Malformed exec-approvals.json Policy Enums

Symptoms

Pairing errors appear after editing exec-approvals.json. Running openclaw doctor shows schema warnings about invalid policy values.

Root cause: If exec-approvals.json contains invalid values for the security, ask, or askFallback fields (typos, outdated enum values from old versions), the runtime policy resolution corrupts and the gateway falls back to blocking everything — which manifests as pairing-required errors.

Fix: Validate your exec-approvals.json and fix any invalid values:

cat ~/.openclaw/exec-approvals.json | python3 -m json.tool

# Valid values:
# security: "full", "allowlist", "deny"
# ask: "off", "on-miss", "always"
# askFallback: "deny", "allow"

Or delete the file and let OpenClaw regenerate it with defaults:

rm ~/.openclaw/exec-approvals.json
openclaw gateway restart

Cause 4 — DM Policy Requiring Pairing for New Users

Symptoms

A specific Discord or Telegram user can't reach your agent — they get "pairing required" or the agent simply doesn't respond to their DMs.

Root cause: By design. OpenClaw's dmPolicy: "pairing" requires new users to complete a pairing flow before they can interact with your agent via DM. This is a security feature, not a bug.

Fix: Either the user completes the pairing flow (recommended), or you change the DM policy:

# In openclaw.json — less secure, use only for trusted channels
"channels": {
  "discord": {
    "dmPolicy": "allowlist",
    "dm": {
      "allowedUsers": ["USER_ID_1", "USER_ID_2"]
    }
  }
}

Quick Diagnostic Script

#!/bin/bash
echo "=== OpenClaw Pairing Diagnostic ==="
echo ""
echo "Version: $(openclaw --version)"
echo ""
echo "--- exec-approvals.json ---"
cat ~/.openclaw/exec-approvals.json 2>/dev/null | python3 -m json.tool 2>&1 | head -20
echo ""
echo "--- doctor output ---"
openclaw doctor 2>&1 | grep -i "pairing\|exec\|approval\|token\|error\|warning"

Paste the output when asking for help on r/openclaw — it'll immediately narrow down which cause applies to you.

Most common fix in practice: Delete exec-approvals.json, restart the gateway, then reconfigure it correctly using our exec-approvals guide. This resolves Causes 1, 2, and 3 in one shot by clearing any corrupt state.