3. OpenClawエージェント間通信が失敗する際の根本原因分析
非同期なエージェント連携の複雑性と失敗の多様性
複数のエージェントが連携してタスクを処理する際、通信の失敗は単なる「メッセージが届かない」という現象に留まりません。認証情報の期限切れ、権限の不足、あるいはメッセージのフォーマット不一致など、複数のレイヤーで問題が発生している可能性があります。
エージェント間通信の基本原則：明示的な宛先指定と権限管理
エージェント間通信（Agent-to-Agent Communication）の基本は、「誰に（宛先）」「何を（メッセージ）」「どの権限で（認証）」送るかを明確に定義することです。sessions_sendなどのツールコールは、この3要素の整合性が求められます。
通信失敗時の系統的チェックフロー（3段階）
通信が失敗した場合、以下の順序で原因を切り分けることが最も効率的です。
| フェーズ | 確認すべきポイント | 使用すべきツール/コマンド |
|---|---|---|
| 1. 宛先（Target）の確認 | 宛先セッションキー（sessionKey）が正しいか、存在しているか | sessions_listでターゲットセッションの存在とステータスを確認する |
| 2. 権限と認証の確認 | 送信元エージェントが、宛先セッションに対してメッセージを送信する権限を持っているか | sessions_sendの呼び出し元（親エージェント）の権限スコープを確認し、必要であれば権限昇格やトークン更新を検討する |
| 3. メッセージフォーマットの確認 | メッセージの内容が、宛先エージェントが期待するフォーマット（JSONスキーマなど）に準拠しているか | sessions_historyで過去の成功メッセージのフォーマットを参考に、メッセージ本文を再構築する |
非同期処理とタイムアウトの取り扱い
エージェント間通信は非同期であるため、即座に結果が返ってこないことが「失敗」と誤認されがちです。必ずtimeoutSecondsを適切に設定し、タイムアウトが発生した場合のフォールバック処理（例：再試行ロジック、代替の通知チャネルへの切り替え）を実装することが、堅牢なシステム設計の要件となります。
まとめ：通信失敗は「状態の不一致」として捉える
エージェント間通信の失敗は、単なるネットワークエラーではなく、システムの状態管理（State Management）における「不一致」が原因であることがほとんどです。宛先、権限、フォーマットの3点を順序立てて検証することで、根本原因を特定し、堅牢な通信レイヤーを構築できます。
