Why sessions_spawn Fails in Docker: The Device Pairing Bug That Blocks Sub-Agents

If you've tried running sub-agents with sessions_spawn in Docker Compose (embedded gateway mode) and hit mysterious timeouts, you're not alone. A recent GitHub issue reveals a subtle but blocking bug that affects anyone running OpenClaw with bindMode: lan or bindMode: tailnet.

The Symptom

Your main agent tries to spawn a sub-agent, waits 10 seconds, times out, retries, times out again, and fails:

You might think it's a timeout issue, but that 1008 pairing required error is the real culprit.

What's Actually Happening

When sessions_spawn calls callGateway() from inside the gateway process with bind mode lan or tailnet, the system builds a WebSocket URL using your LAN or Tailscale IP (e.g., ws://172.18.0.2:18789). Here's where it breaks:

1. The gateway's isLocalDirectRequest() check requires the client IP to be loopback (127.0.0.1) AND the Host header to be localhost/127.0.0.1/::1
2. When connecting via LAN IP, the connection is treated as remote
3. Remote connections require device pairing
4. The internal device identity isn't paired → immediate 1008 close → spawn fails

The OPENCLAW_GATEWAY_TOKEN env var handles token auth correctly, but device pairing is a separate authentication layer that still rejects the loopback connection.

The Fix

The solution adds a forceLoopback option to callGateway() and buildGatewayConnectionDetails(). When set, connections always use 127.0.0.1 regardless of bind mode - the gateway listens on 0.0.0.0, so loopback always works.

The key change in buildGatewayConnectionDetails:

 export function buildGatewayConnectionDetails(
-  options: { config?: OpenClawConfig; url?: string; configPath?: string } = {},
+  options: { config?: OpenClawConfig; url?: string; configPath?: string; forceLoopback?: boolean } = {},
 ): GatewayConnectionDetails {
   ...
-  const preferTailnet = bindMode === "tailnet" && !!tailnetIPv4;
-  const preferLan = bindMode === "lan";
+  const preferTailnet = !options.forceLoopback && bindMode === "tailnet" && !!tailnetIPv4;
+  const preferLan = !options.forceLoopback && bindMode === "lan";

Then set forceLoopback: true on all callGateway calls inside sessions_spawn.

Other Tools Affected

This bug affects any tool that calls callGateway() internally when using LAN/tailnet bind mode:

• sessions_send
• sessions_list
• sessions_history
• cron operations

If you're seeing similar pairing errors with these tools in Docker, the same fix applies.

Bonus: Timeout Improvements

The fix also addresses the original timeout complaint - the default timeout was bumped from 10s to 30s and made configurable via spawnTimeoutMs in your agent defaults:

agentDefaults:
  subagents:
    spawnTimeoutMs: 45000  # 45 seconds

This helps when spawning sub-agents under heavy load.

Summary

If your sub-agents silently fail in Docker with embedded mode, check your bind mode. The fix forces internal gateway calls to use loopback, bypassing the device pairing check that incorrectly treats internal connections as remote.

Full discussion and code changes: openclaw/openclaw#29186