トラブルシューティングガイド：ネスト化されたエージェントセッション間の相互ブロック

症状

複数のエージェントセッションを同時に実行している場合、以下の症状が発生することがあります：

• 遅延または応答の欠落： 1つまたは複数のエージェントセッションが「フリーズ」したり、要求されたタスクがシンプルであっても予想外に長い時間がかかる場合があります。
• セッション間のブロッキング： あるセッションでの長時間実行タスク（ACP Claude Codeの実行など）が、完全に無関係な他のセッションにも遅延を引き起こします。
• ゲートウェイタイムアウト： ログに lane wait exceeded: lane=nested waitedMs=XXXXX queueAhead=1 を示すエラーメッセージが表示されます。
• Discord配信の失敗： バックログ中に生成されたアシスタント応答がDiscordチャンネルに配信されません。
• 不整合な動作： 基礎となるタスクが無関係であっても、一部のセッションは即座に反応し、他のセッションは数分間アイドル状態のままになります。

原因

根本原因是、ネスト化されたエージェント実行システムにおける単一のグローバルキューのボトルネックでした。

以前、すべてのセッションにわたるネスト化されたエージェント操作は、maxConcurrent=1 を持つ "nested" という名前のレーンを共有していました，这意味着：

1. すべての sessions_send、runAgentStep、および ACP ディスパッチが同じキューエントリを競合していました。
2. セッション A が10分のタスクを実行している場合、セッション B、C、D はその背後に並んで待つ必要がありました。
3. コマンドキューは、どのセッションを対象としているかにかかわらず、すべてのネスト化された操作を同一に扱っていました。

このアーキテクチャ上の制限により、単一の長時間実行されるネスト化された操作がゲートウェイ内の他のすべてのエージェントセッションを滞らせられる、先頭ブロック問題が発生していました。

解決手順

オプション1：修正済みバージョンへのアップグレード（推奨）

OpenClaw インストールをバージョン v2026.4.19-beta.2 以降にアップグレードしてください。

このバージョンでは、ネスト化された作業を nested:<sessionKey> にスコープするセッションごとのネスト化されたレーンが導入され、各セッション内の同時実行不変量を維持しながら、異なるセッション間での並列実行が可能になります。

オプション2：レーン設定の確認（手動確認用）

修正が正しく適用されていることを確認する必要がある場合は、ゲートウェイログでとして使用されているレーン名を確認してください：

修正前、以下のようなログが表示されます：

[agent:nested] Processing session A
[agent:nested] Processing session B

修正後、スコープされたレーン名が表示されます：

[agent:nested:session-A] Processing session A
[agent:nested:session-B] Processing session B

オプション3：レーンステートマップの確認

ゲートウェイ設定では、レーンステートが裸の "nested" 文字列ではなく、完全なセッションスコープ識別子でキー付けされるようになりました。各エントリには以下が表示されます：

• 標準セッション用の nested:<sessionKey>
• レガシーcronパス専用の "nested" フォールバック

検証

修正が正しく機能していることを確認するには：

1. 複数の同時セッションを実行する： ネスト化された操作を受信できる2つ以上のエージェントセッションを設定します。

2. 1つのセッションで長時間タスクをトリガーする： 例えば、数分かかるタスクを呼び出します。

3. 別のセッションにクイックタスクを送信する： 長いタスクの実行中に、異なるセッションにシンプルなリクエストを送信します。

4. 並列実行を検証する： 2番目のセッションは、最初、セッションのタスクの完了を待たずに即座に応答する必要があります。

5. スコープされたレーンのログを確認する： セッションごとのレーン分離を確認する [agent:nested:<sessionKey>] プレフィックスがゲートウェイログにあることを確認します。

修正後の予想されるテスト結果：

pnpm test src/agents/lanes.test.ts         # 13 tests green
pnpm test src/gateway/server.sessions-send.test.ts  # 14 tests green
pnpm test 'src/agents/**/*.test.ts'        # 3841 tests green

よくある落とし穴

セッションキー処理

• 空または空白のみのセッションキー： これらはスコープなしの "nested" レーンにフォールバックします。ネスト化された操作をルーティングする前に、セッションキーが適切に入力されていることを確認してください。

• レガシーcronパス： resolveNestedAgentLane(lane) を使用して cron 統合を引き続き使用する場合は、スコープなしのフォールバックを引き続き使用します。これは下位互換性のために意図的なものです。

レーン名の衝突

• ユーザー指定のレーン名： "nested:something" のような名前のカスタムレーンを使用している場合は、これらがシステム生成の nested:<sessionKey> レーンとは異なることに注意してください。システムレーンは、既存の session:<key> パターンに一致する特定のプレフィックス規則を使用します。

メモリに関する考慮事項

レーンステートの Map は、新しいセッションキーが表示されるにつれて成長します。各レーンステートエントリは約200バイトです。現実的な上限はアクティブセッションの数であり、これは既にゲートウェイのセッション管理によってバインドされています。これが問題になった場合、アイドル状態になったネスト化されたレーンを削除する将来の拡張機能が追加される可能性があります。

無関係な問題

元のレポートで言及された2つの関連問題は、この修正の範囲外のままです：

• セッション配信コンテキストの破損
• 配信リトライ/DLQメカニズムの欠如

これらは別途追跡されているアーキテクチャ的なフォローアップです。

関連するエラー

影響を受けるバージョン

• 修正済み： v2026.4.19-beta.2
• 影響を受けるバージョン： v2026.4.14 以前

互換性

この修正は完全に下位互換性があります：

• AGENT_LANE_NESTED 定数は引き続きエクスポートされます
• 定数を直接渡し続ける呼び出し元は、既存の（スコープなし）動作を維持します
• 設定の変更は不要です
• 移行手順は不要です

この修正は、既存の統合を壊すことなく、セッション分離を強化します。