April 15, 2026 • バージョン: v2026.4.12

sessions_spawn が分離ロジックエージェントの生成時に「pairing required (1008)」で失敗する

sessions_spawn 経由で生成されたサブエージェントが、WebSocket 1008 エラーにより失敗します。gateway が内部 loopback 接続を未認可の device scope escalation 要求として拒否するためです。

🔍 症状

sessions_spawnコマンドは、ランタイム設定（acp、subagent、またはisolated）に関係なく、分離されたロジックサブエージェントを起動しようとしたときに即座に失敗します。

エラー出力

$ 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] 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

設定コンテキスト

openclaw.jsonには以下の設定が含まれています：

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

動作的症状

サブエージェントのスポーンが每次呼び出しで一貫して失敗する
openclaw devices approveによる手動デバイス承認では問題が解決しない
localhostまたは127.0.0.1をターゲットにしたエージェントをスポーン場合でもエラーが発生する
メインセッションは正常に動作し続ける。スポーンされたサブエージェントのみが影響を受ける
すべての関連問題（#12210、#21445、#30740、#59428）が同一のエラーコードと動作を示す

🧠 原因

アーキテクチャ分析

OpenClaw v2026.4.12のsessions_spawnメカニズムは、スポーンされたサブエージェントプロセスからゲートウェイへの内部WebSocket接続を確立します。この接続はループバックインターフェース（127.0.0.1）を経由し、ゲートウェイのデバイスペアリング強制レイヤーの対象となります。

失敗シーケンス

スポーン開始：メインセッションがsessions_spawnを呼び出し、ターゲットエージェント用の新しい分離プロセスを作成する。
ゲートウェイハンドシェイク：サブエージェントプロセスがws://localhost:{gateway-port}/acpへのWebSocket接続を開始する。
デバイス識別：ゲートウェイのペアリングミドルウェアが内部接続に一時的なデバイス識別子を割り当てます：internal-spawn-{uuid}。
スコープエスカレーションのブロック：スポーンされたエージェントが、ゲートウェイがペアリング済みデバイスを必要すると分類する elevated scopes（エージェント実行、セッション管理）を要求する。
1008拒否：ゲートウェイがWebSocketクロースコード1008（Policy Violation）で「pairing required」を理由に接続を終了する。

技術的根本原因

このリグレッションは、内部ループバック接続の暗黙的なペアリングバイパスを削除したv2026.4.12の変更に起因します。以前のバージョンでは127.0.0.1接続を本質的に信頼するものとして扱い、internal:spawnスコープを自動的に付与していました。この更新により、すべてのネットワークインターフェースでペアリング強制が統一され、誤ってサブエージェントスポーンパスを壊してしまいました。

ゲートウェイ設定では以下を区別していません：

外部デバイス接続（正当なペアリング要求）
スポーンされたサブエージェントからの内部ループバック接続

コードパス分析

// 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;
  }
}

設定のギャップ

acp.allowedAgents設定はどのエージェントが呼び出されるかを制御しますが、エージェントの内部ゲートウェイ接続に対するペアリング免除は付与しません。これらは誤って混同された、独立したセキュリティコントロールです。

🛠️ 解決手順

オプション1：ループバックペアリング免除の設定（推奨）

ゲートウェイ設定に明示的なループバックペアリング免除を追加します：

ステップ1： ゲートウェイ設定ファイルを作成または特定します：

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

# Windows
%APPDATA%\openclaw\gateway.json

# Dockerコンテナ
/path/to/config/gateway.json

ステップ2： pairing免除設定を追加します：

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

ステップ3： ゲートウェイを再起動します：

# サービスとして実行している場合
sudo systemctl restart openclaw-gateway

# 直接実行している場合
openclaw gateway stop
openclaw gateway start

オプション2：ACPではなくローカルランタイムを使用

スポーンされたエージェントに対してローカルランタイムを使用することで、ACPゲートウェイパスを完全に回避します：

# 以前（1008で失敗）
$ openclaw sessions_spawn --agent my-agent --runtime acp -- "task"

# 変更後（分離ローカルランタイムを使用）
$ openclaw sessions_spawn --agent my-agent --runtime local -- "task"

オプション3：環境変数による上書き

ゲートウェイ起動前にOPENCLAW_INTERNAL_SPAWN_BYPASS環境変数を設定します：

# シェルプロファイルに追加するか、インラインで設定
export OPENCLAW_INTERNAL_SPAWN_BYPASS=true

# または変数付きでゲートウェイを起動
OPENCLAW_INTERNAL_SPAWN_BYPASS=true openclaw gateway start

オプション4：ペアリング強制の無効化（開発環境のみ）

開発環境でのみ、ペアリングを完全に無効化します：

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

警告：この設定は外部デバイスを含むすべての接続のペアリングを無効化します。商用環境では使用しないでください。

設定変更前後の比較

変更前（openclaw.json）：

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

変更後（gateway.json）：

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

🧪 検証

修正を適用した後、以下の手順で解決を検証します：

ステップ1：ゲートウェイ設定の確認

$ openclaw gateway config show

出力には以下が含まれている必要があります：

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

ステップ2：ゲートウェイの再起動とログ確認

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

期待されるログエントリ：

[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

ステップ3：サブエージェントスポーンのテスト

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

期待される出力：

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

ステップ4：セッション分離の確認

$ openclaw sessions list

出力にはメインセッションとスポーンされたサブエージェントセッションの両方が表示される必要があります：

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

ステップ5：マルチエージェントオーケストレーションのテスト

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

期待される結果：エージェントが1008エラーなしでスポーンされ、タスク実行を開始する。

検証終了コード

0：修正成功、サブエージェントが正常にスポーンされた
1008：修正未適用、ペアリング強制がまだ有効
7：エージェントIDがacp.allowedAgents

`⚠️ よくある落とし穴`

`環境固有のトラップ`

Dockerコンテナネットワーキング：DockerでOpenClawを実行する場合、ループバックトラフィックは異なる方法でルーティングされる場合があります。hostネットワーキングモードを使用するか、docker-composeでnetwork=hostことを確認してください：services: openclaw: network_mode: host
Windows WSL2：ループバックの動作はWindowsホストとWSL2間で異なります。ゲートウェイは異なるインターフェースでリッスン場合があります。以下で確認してください：netstat -tlnp | grep openclaw
macOSサンドボックス：設定ディレクトリが異なる場合があります：~/Library/Application Support/openclaw/

`設定の落とし穴`

設定ファイルの場所的错误：ゲートウェイ設定はopenclaw.jsonではなくgateway.jsonに配置する必要があります。後者はエージェント権限を処理し、前者はゲートウェイセキュリティを処理します。
設定マージの問題：環境変数と設定ファイルを同時に使用する場合、環境変数が優先されます。以下で確認してください：openclaw gateway config show --merged
古いゲートウェイプロセス：gateway.jsonへの変更は再読み込みではなく完全な再起動が必要です。プロセスが実際に再起動されたことを確認してください：ps aux | grep openclaw-gateway

`認証の落とし穴`

デバイスペアリング状態の永続化：承認されたデバイスはローカルに保存されます。アプリデータをクリアすると、承認されたループバックデバイスが無効になる場合があります：# Linux rm -rf ~/.local/share/openclaw/devices/* macOS rm -rf ~/Library/Application\ Support/openclaw/devices/*
トークンの有効期限：スポーンされたサブエージェントは有限の寿命を持つ認証トークンを継承します。長時間実行されるタスクの場合、メインセッションがアクティブなままになっていることを確認してください。

`ランタイム選択の落とし穴`

ランタイムの不一致：--runtime acpはACPゲートウェイを経由し（ペアリングの影響を受ける）、--runtime localは完全にバイパスします。エージェントロジックがゲートウェイサービスを必要としない場合にのみlocalを使用してください。
無効なエージェントID：sessions_spawn内のエージェントIDは、acp.allowedAgents内のエントリ（大文字小文字を区別）と完全に一致する必要があります。

`既知のリグレッション`

この問題はv2026.4.12で初めて発生し、internalSpawnBypass設定が適用されるまで後続のパッチリリースでも継続します。
バージョンv2026.4.11以前では影響を受けず、即座な機能が必要な場合はダウングレードパスとして使用できます。

`🔗 関連するエラー`

`直接的な関連エラー`

WebSocket 1008: Policy Violation ゲートウェイのペアリング強制が内部スポーン接続を閉じるエラー。サブエージェントスポーンをブロックしている主要エラー。
エラー #12210：「新規インストールで'sessions_spawn'が'pairing required'で失敗する」 v2026.4.xシリーズにおけるこのリグレッションパターンの初回報告。
エラー #21445：「ACPランタイムサブエージェントがゲートウェイに接続できない」 ACP介在スポーンに対するスコープエスカレーション拒否の問題を追跡。
エラー #30740：「ループバック接続が誤って未ペアリングデバイスとしてフラグ付けされる」内部接続の外部デバイスとしての誤分類を文書化。
エラー #59428：「OPENCLAW_SKIP_PAIRING=trueでもデバイスペアリングが必要」スポーンされたサブエージェントに対して環境変数バイパスが機能しない。

`二次的な関連エラー`

エラー #45102：「許可されたエージェントに対してsessions_spawnが終了コード7を返す」ペアリングチェック前のスポーン拒否を引き起こす設定の不一致。
エラー #33456：「長時間実行されるスポーンでゲートウェイが1011で接続を閉じる」正常なスポーン後に発生する無関係のエラー、別のタイムアウト問題。
エラー #77890：「メインセッション切断後にサブエージェントセッションが孤立する」マルチエージェントワークフローでのセッションライフサイクル管理の問題。

`エラーコードリファレンス`

コード	名前	コンテキスト
1008	Policy Violation	ペアリング強制による内部接続のブロック
1006	Abnormal Closure	スポーンハンドシェイク中のゲートウェイクラッシュ
1011	Unexpected Condition	スコープエスカレーション中のサーバー側エラー
7	Invalid Agent	エージェントIDがallowedAgentsリストにない
65	Session Limit	最大同時セッション数を超過