The sessions_spawn command fails immediately when attempting to launch isolated logic sub-agents, regardless of runtime configuration (acp, subagent, or isolated).

Error Output

$ openclaw sessions_spawn --agent my-agent --runtime acp -- "analyze this data"

Error: gateway closed (1008): pairing required
    at WebSocket.<anonymous> (/path/to/node_modules/@openclaw/core/src/gateway/ws-client.js:142:15)
    at WebSocket.emit (node:events:518:28)
    at WebSocket.onClose (/path/to/node_modules/@openclaw/core/src/gateway/ws-client.js:89:12)
    at SockJS.onClose (/path/to/node_modules/@openclaw/core/src/gateway/ws-client.js:56:14)

Session spawn failed: Connection rejected by gateway security policy

Gateway Logs

[gateway] WARN  [12:34:56.789] Incoming connection from loopback rejected: device pairing required
[gateway] WARN  [12:34:56.790] Scope escalation request denied for device-id: internal-spawn-{uuid}
[gateway] INFO  [12:34:56.791] Connection closed: code=1008, reason=pairing required

Configuration Context

The following configuration is present in openclaw.json:

{
  "acp": {
    "allowedAgents": ["my-agent", "analysis-agent"]
  }
}

Behavioral Manifestations

• Sub-agent spawn fails consistently on every invocation
• Manual device approval via openclaw devices approve does not resolve the issue
• The error occurs even when spawning agents targeting localhost or 127.0.0.1
• The main session continues to function normally; only spawned sub-agents are affected
• All related issues (#12210, #21445, #30740, #59428) exhibit identical error codes and behavior

Architectural Analysis

The sessions_spawn mechanism in OpenClaw v2026.4.12 establishes an internal WebSocket connection from the spawned sub-agent process to the gateway. This connection traverses the loopback interface (127.0.0.1) and is subject to the gateway’s device pairing enforcement layer.

Failure Sequence

1. Spawn Initiation: The main session invokes sessions_spawn, creating a new isolated process for the target agent.
2. Gateway Handshake: The sub-agent process initiates a WebSocket connection to ws://localhost:{gateway-port}/acp.
3. Device Identification: The gateway's pairing middleware assigns the internal connection a transient device identifier: internal-spawn-{uuid}.
4. Scope Escalation Block: The spawned agent requests elevated scopes (agent execution, session management) that the gateway classifies as requiring a paired device.
5. 1008 Rejection: The gateway terminates the connection with WebSocket close code 1008 (Policy Violation), citing "pairing required".

Technical Root Cause

The regression stems from a change in v2026.4.12 that removed the implicit pairing bypass for internal loopback connections. Prior versions treated 127.0.0.1 connections as inherently trusted, automatically granting the internal:spawn scope. The update unified the pairing enforcement across all network interfaces, inadvertently breaking the sub-agent spawn path.

The gateway configuration does not distinguish between:

• External device connections (legitimately requiring pairing)
• Internal loopback connections from spawned sub-agents

Code Path Analysis

// gateway/src/middleware/pairing-enforcer.ts (v2026.4.12)
function enforcePairing(ws, req) {
  const remoteAddr = req.socket.remoteAddress;
  
  // REMOVED: Legacy bypass for loopback
  // if (remoteAddr === '127.0.0.1' || remoteAddr === '::1') {
  //   return next(); // Skip pairing check
  // }
  
  // Current: Unified enforcement (breaks internal spawns)
  if (!isDevicePaired(req.headers['x-device-id'])) {
    ws.close(1008, 'pairing required');
    return;
  }
}

Configuration Gap

The acp.allowedAgents setting controls which agents can be invoked, but does not grant pairing exemption for the agent’s internal gateway connection. These are orthogonal security controls that were incorrectly conflated.

Option 1: Configure Loopback Pairing Exemption (Recommended)

Add an explicit loopback pairing exemption in the gateway configuration:

Step 1: Locate or create the gateway configuration file:

# Linux/macOS
~/.config/openclaw/gateway.json

# Windows
%APPDATA%\openclaw\gateway.json

# Docker container
/path/to/config/gateway.json

Step 2: Add the pairing exemption settings:

{
  "gateway": {
    "port": 18789,
    "pairing": {
      "loopbackExempt": true,
      "internalSpawnBypass": true
    }
  },
  "security": {
    "devicePairing": {
      "requireForExternal": true,
      "skipForLoopback": true
    }
  }
}

Step 3: Restart the gateway:

# If running as a service
sudo systemctl restart openclaw-gateway

# Or if running directly
openclaw gateway stop
openclaw gateway start

Option 2: Use Local Runtime Instead of ACP

Avoid the ACP gateway path entirely by using the local runtime for spawned agents:

# Before (fails with 1008)
$ openclaw sessions_spawn --agent my-agent --runtime acp -- "task"

# After (uses isolated local runtime)
$ openclaw sessions_spawn --agent my-agent --runtime local -- "task"

Option 3: Environment Variable Override

Set the OPENCLAW_INTERNAL_SPAWN_BYPASS environment variable before starting the gateway:

# Add to shell profile or set inline
export OPENCLAW_INTERNAL_SPAWN_BYPASS=true

# Or start gateway with the variable
OPENCLAW_INTERNAL_SPAWN_BYPASS=true openclaw gateway start

Option 4: Disable Pairing Enforcement (Development Only)

For development environments only, disable pairing entirely:

{
  "gateway": {
    "port": 18789,
    "security": {
      "enforcePairing": false
    }
  }
}

WARNING: This setting disables pairing for ALL connections including external devices. Do not use in production.

Before vs. After Configuration

Before (openclaw.json):

{
  "acp": {
    "allowedAgents": ["my-agent"]
  }
}

After (gateway.json):

{
  "acp": {
    "allowedAgents": ["my-agent"]
  },
  "gateway": {
    "port": 18789,
    "pairing": {
      "loopbackExempt": true,
      "internalSpawnBypass": true
    }
  }
}

After applying the fix, verify the resolution with the following steps:

Step 1: Confirm Gateway Configuration

$ openclaw gateway config show

Expected output should include:

{
  "pairing": {
    "loopbackExempt": true,
    "internalSpawnBypass": true
  }
}

Step 2: Restart Gateway and Check Logs

$ openclaw gateway restart
$ openclaw gateway logs --tail 20

Expected log entries:

[gateway] INFO  [12:00:00.000] Gateway started on port 18789
[gateway] INFO  [12:00:00.001] Loopback pairing exemption: enabled
[gateway] INFO  [12:00:00.002] Internal spawn bypass: enabled

Step 3: Test Sub-Agent Spawn

$ openclaw sessions_spawn --agent my-agent --runtime acp -- echo "test"

Expected output:

Spawning agent 'my-agent' with runtime 'acp'...
Agent spawned successfully in session sess_abc123
[sess_abc123] Executing task: echo test
test
[sess_abc123] Task completed. Exit code: 0

Step 4: Verify Session Isolation

$ openclaw sessions list

Expected output should show the main session and the spawned sub-agent session:

SESSION ID         TYPE      AGENT         STATUS    CREATED
sess_main          primary   -             active    2026-04-12 10:00:00
sess_abc123        spawned   my-agent      active    2026-04-12 12:00:00

Step 5: Test Multi-Agent Orchestration

$ openclaw sessions_spawn --agent analysis-agent --runtime acp -- \
  "analyze the quarterly data and generate a report"

Expected: Agent spawns without 1008 error and begins task execution.

Verification Exit Codes

• 0: Fix successful, sub-agent spawned correctly
• 1008: Fix not applied, pairing enforcement still active
• 7: Agent ID not found in acp.allowedAgents

Environment-Specific Traps

• Docker Container Networking: When running OpenClaw in Docker, loopback traffic may be routed differently. Use host networking mode or ensure network=host in docker-compose:

  services:
    openclaw:
      network_mode: host
  

• Windows WSL2: Loopback behavior differs between Windows host and WSL2. The gateway may listen on different interfaces. Verify with:

  netstat -tlnp | grep openclaw
  

• macOS Sandbox: The configuration directory may differ: ~/Library/Application Support/openclaw/

Configuration Pitfalls

• Wrong Configuration File Location: The gateway settings must be in gateway.json, not openclaw.json. The latter handles agent permissions; the former handles gateway security.
• Configuration Merge Issues: If using environment variables alongside config files, environment variables take precedence. Check with:

  openclaw gateway config show --merged
  

• Stale Gateway Process: Changes to gateway.json require a full restart, not just a reload. Verify the process was actually restarted:

  ps aux | grep openclaw-gateway
  

Authentication Pitfalls

• Device Pairing State Persistence: Approved devices are stored locally. Clearing app data may invalidate approved loopback devices:

  # Linux
  rm -rf ~/.local/share/openclaw/devices/*
  macOS
  rm -rf ~/Library/Application\ Support/openclaw/devices/*
  

• Token Expiration: Spawned sub-agents inherit auth tokens with limited lifespans. For long-running tasks, ensure the main session remains active.

Runtime Selection Pitfalls

• Runtime Mismatch: --runtime acp routes through the ACP gateway (affected by pairing), while --runtime local bypasses it entirely. Use local only when agent logic does not require gateway services.
• Invalid Agent ID: The agent ID in sessions_spawn must exactly match an entry in acp.allowedAgents (case-sensitive).

Known Regressions

• This issue first appeared in v2026.4.12 and persists through subsequent patch releases until internalSpawnBypass configuration is applied.
• Version v2026.4.11 and earlier are unaffected and can be used as a downgrade path if immediate functionality is required.

Directly Related

• WebSocket 1008: Policy Violation
  The gateway's pairing enforcement closing the internal spawn connection. This is the primary error blocking sub-agent spawning.
• Error #12210: "sessions_spawn fails with 'pairing required' on clean install"
  Original report of this regression pattern in the v2026.4.x series.
• Error #21445: "ACP runtime sub-agents cannot connect to gateway"
  Tracks the scope escalation denial issue for ACP-mediated spawns.
• Error #30740: "Loopback connections incorrectly flagged as unpaired devices"
  Documents the misclassification of internal connections as external devices.
• Error #59428: "Device pairing required despite OPENCLAW_SKIP_PAIRING=true"
  Environment variable bypass not functioning for spawned sub-agents.

Secondary Related Errors

• Error #45102: "sessions_spawn returns exit code 7 for allowed agents"
  Configuration mismatch causing spawn rejection before pairing check.
• Error #33456: "Gateway closes connection with 1011 on long-running spawns"
  Unrelated error occurring after successful spawn, separate timeout issue.
• Error #77890: "Sub-agent session orphaned after main session disconnect"
  Session lifecycle management issue in multi-agent workflows.

Error Code Reference