セッションツール

OpenClaw は、セッションをまたいで作業し、状態を確認し、サブエージェントをオーケストレーションするためのツールをエージェントに提供します。

利用可能なツール

これらのツールには、引き続き有効なツールプロファイルおよび許可／拒否ポリシーが適用されます。tools.profile: "coding" には、sessions_spawn、sessions_yield、subagents を含むセッションオーケストレーションの全ツールセットが含まれます。tools.profile: "messaging" には、セッション間メッセージングツール（sessions_list、sessions_history、sessions_send、session_status）が含まれますが、サブエージェントの生成は含まれません。メッセージングプロファイルを維持したままネイティブ委任も許可するには、次を追加します。

{  tools: {    profile: "messaging",    alsoAllow: ["sessions_spawn", "sessions_yield", "subagents"],  },}

グループ、プロバイダー、サンドボックス、エージェント単位のポリシーにより、プロファイル段階の後でこれらのツールが除外される場合もあります。影響を受けるセッションから /tools を使用して、実際に有効なツール一覧を確認してください。

セッションの一覧表示と読み取り

sessions_list は、キー、agentId、種別、チャンネル、モデル、トークン数、タイムスタンプを含むセッションを返します。kinds（配列。使用可能な値：main、group、cron、hook、node、other）、完全一致の label、完全一致の agentId、search テキスト、または直近のアクティビティ（activeMinutes）でフィルターできます。デフォルトではアクティブなセッションが返されます。アーカイブ済みセッションを確認するには、代わりに archived: true を渡します。各行には pinned と archived の状態が含まれます。メールボックス形式のトリアージが必要な場合は、includeDerivedTitles、includeLastMessage、または messageLimit（上限 20）を設定すると、可視性スコープ内で生成されたタイトル、最後のメッセージのプレビュースニペット、または各行の件数を制限した最近のメッセージを取得できます。生成タイトルとプレビューは、設定されたセッションツールの可視性ポリシーに基づいて呼び出し元がすでに参照できるセッションについてのみ作成されるため、無関係なセッションは非表示のままです。可視性が制限されている場合、sessions_list は実効モードを示すオプションの visibility メタデータと、結果がスコープによって制限される可能性があるという警告を返します。

sessions_history は、特定のセッションの会話トランスクリプトを取得します。デフォルトではツール結果は除外されます。表示するには includeTools: true を渡します。最新部分を指定件数に制限するには limit を使用します。ページネーションメタデータが必要な場合は offset: 0 を渡し、その後、返された nextOffset の値を渡すことで、生のトランスクリプトファイルを読み取らずに、古い OpenClaw トランスクリプトの範囲を過去方向へページングできます。明示的なオフセットページには、外部 CLI のフォールバックインポートはマージされません。マージされた表示履歴が必要な場合は、デフォルトの最新部分表示（offset なし）を使用してください。

返されるビューは、意図的に範囲が制限され、安全性フィルターが適用されています。

• アシスタントのテキストは、再取得前に正規化されます。
  • 思考タグは除去されます
  • <relevant-memories> / <relevant_memories> のスキャフォールディングブロックは除去されます
  • <tool_call>...</tool_call>、<function_call>...</function_call>、<tool_calls>...</tool_calls>、<function_calls>...</function_calls> などのプレーンテキストのツール呼び出し XML ペイロードブロックは、正常に閉じられていない切り詰められたペイロードも含めて除去されます
  • [Tool Call: ...]、[Tool Result ...]、[Historical context ...] など、ダウングレードされたツール呼び出し／結果のスキャフォールディングは除去されます
  • <|assistant|>、その他の ASCII <|...|> トークン、全角の <｜...｜> バリアントなど、漏出したモデル制御トークンは除去されます
  • <invoke ...> / </minimax:tool_call> など、不正な MiniMax ツール呼び出し XML は除去されます
• 認証情報やトークンに類似するテキストは、返される前に墨消しされます
• 長いテキストブロックは切り詰められます
• 非常に大きな履歴では、古い行が削除されるか、サイズ超過の行が [sessions_history omitted: message too large] に置き換えられる場合があります
• ツールは、truncated、droppedMessages、contentTruncated、contentRedacted、bytes、ページネーションメタデータなどの概要フラグを報告します

どちらのツールも、セッションキー（"main" など）または以前の一覧呼び出しで取得した セッション ID のいずれかを受け付けます。

正確な生のトランスクリプトが必要な場合は、sessions_history をフィルターなしのダンプとして扱うのではなく、スコープ内の SQLite トランスクリプト行を確認してください。

セッション間メッセージの送信

sessions_send は、別のセッションにメッセージを配信し、必要に応じて応答を待機します。

• 送信後に待機しない： timeoutSeconds: 0 を設定すると、キューに追加して直ちに戻ります。
• 応答を待機： タイムアウトを設定すると、応答をインラインで取得します。

キーが :thread:<id> で終わるようなスレッドスコープのチャットセッションは、有効な sessions_send の送信先ではありません。エージェント間の調整には親チャンネルのセッションキーを使用し、ツール経由のメッセージがアクティブな対人スレッド内に表示されないようにしてください。

メッセージおよび A2A の後続応答は、受信側プロンプト（[Inter-session message ... isUser=false]）およびトランスクリプトの来歴で、セッション間データとしてマークされます。受信側のエージェントは、それらをエンドユーザーが直接作成した指示ではなく、ツール経由のデータとして扱う必要があります。

送信先が応答した後、OpenClaw はエージェントが交互にメッセージを送る 返信ループを実行できます（最大 session.agentToAgent.maxPingPongTurns、範囲 0-20、デフォルト 5）。送信先エージェントは REPLY_SKIP と応答して早期終了できます。

watch: true を渡すと、送信元を送信先の状態変更監視者として登録することもできます。後で別のアクターが送信先に直接人間のメッセージを送信するか、その目標を変更すると、送信元は session_status の changesSince を示すシステム通知を受け取ります。登録は正常なディスパッチ後に行われ、実際にメッセージを受信したセッションが対象となり、その時点の状態バージョンから開始されるため、それ以降の変更のみが通知されます。登録に成功すると、結果には watched: true が報告されます。セッション状態の認識を参照してください。

状態とオーケストレーションのヘルパー

session_status は、現在または別の可視セッションに対する軽量な /status 相当のツールです。使用量、時刻、モデル／ランタイムの状態、および存在する場合はリンクされたバックグラウンドタスクのコンテキストを報告します。/status と同様に、最新のトランスクリプト使用量エントリから不足しているトークン／キャッシュカウンターを補完でき、model=default はセッション単位のオーバーライドを解除します。呼び出し元の現在のセッションには sessionKey="current" を使用します。openclaw-tui のような可視クライアントラベルはセッションキーではありません。

ルートメタデータが利用可能な場合、session_status には可視の Route context JSON ブロックと、それに対応する構造化された details フィールドも含まれます。これらのフィールドは、セッションキーと、現在ライブ実行を処理しているルートを区別します。

• origin はセッションが作成された場所です。保存された生成元メタデータが古い状態に存在しない場合は、配信可能なセッションキープレフィックスから推定されたプロバイダーです。
• active は現在のライブ実行ルートです。現在処理中のライブセッションまたは現在のセッションについてのみ報告されます。
• deliveryContext はセッションに保存されている永続的な配信ルートであり、アクティブなサーフェスが異なる場合でも、OpenClaw が後の配信に再利用できます。

セッション状態の変更

OpenClaw は、重要なセッション状態変更（監視対象セッションへの人間からの直接メッセージ、子実行の結果、目標の変更、Compaction）の永続的なシグナルログを保持します。sessions_list の行と session_status はセッションの stateVersion を公開し、session_status は changesSince: <version> を受け付け、そのバージョン以降の型付きイベントを返します。要求されたバージョンが保持されている履歴より古い場合は、正確な historyGap シグナルも返します。監視者（生成元の親は自動登録、sessions_send watch: true は明示的登録）は、別のアクターが監視対象セッションを変更すると、統合された古い状態の通知を 1 件受け取ります。

イベント種別、監視者の登録、スパム防止通知プロトコル、調整フロー、現在の制限を含む完全なモデルについては、セッション状態の認識を参照してください。

sessions_yield は、次のメッセージを待機中の後続イベントにできるよう、意図的に現在のターンを終了します。ポーリングループを構築する代わりに、完了結果を次のメッセージとして受け取りたい場合は、サブエージェントを生成した後に使用します。

subagents は、すでに生成された OpenClaw サブエージェント用の可視性ヘルパーです。アクティブまたは最近の実行を確認するための action: "list" をサポートします。

サブエージェントの生成

sessions_spawn は、デフォルトでバックグラウンドタスク用の分離されたセッションを作成します。常にノンブロッキングで、runId と childSessionKey を直ちに返します。ネイティブのサブエージェント実行では、委任されたタスクが子セッションで最初に表示される [Subagent Task] メッセージとして渡されます。一方、システムプロンプトにはサブエージェントのランタイムルールとルーティングコンテキストのみが含まれます。

主なオプション：

• 外部ハーネスエージェントには runtime: "subagent"（デフォルト）または "acp"。
• 子セッション用の model および thinking オーバーライド。
• 生成をチャットスレッド（Discord、Slack など）に結び付ける thread: true。
• 子でサンドボックス化を強制する sandbox: "require"。
• 子が現在の依頼元トランスクリプトを必要とする場合、ネイティブサブエージェントには context: "fork"。クリーンな子には省略するか、context: "isolated" を使用します。context: "fork" は runtime: "subagent" との組み合わせでのみ有効です。スレッドに結び付けられたネイティブサブエージェントは、threadBindings.defaultSpawnContext で別途指定されていない限り、デフォルトで context: "fork" を使用します。

デフォルトのリーフサブエージェントには、セッションツールは付与されません。maxSpawnDepth >= 2 の場合、深度 1 のオーケストレーターサブエージェントには、独自の子を管理できるよう、追加で sessions_spawn、subagents、sessions_list、sessions_history が付与されます。リーフ実行には、引き続き再帰的オーケストレーションツールは付与されません。

完了後、通知ステップで依頼元のチャンネルに結果が投稿されます。完了通知では、利用可能な場合は関連付けられたスレッド／トピックのルーティングが維持されます。また、完了元がチャンネルのみを識別する場合でも、OpenClaw は直接配信のために依頼元セッションに保存されたルート（lastChannel / lastTo）を再利用できます。

ACP 固有の動作については、ACP エージェントを参照してください。

可視性

セッションツールには、エージェントが参照できる範囲を制限するスコープが設定されます。

デフォルトは tree です。サンドボックス化されたセッションは、設定にかかわらず tree に制限されます。

関連資料

• セッション管理：ルーティング、ライフサイクル、メンテナンス
• サブエージェント：子セッションのライフサイクルと配信
• ACP エージェント：外部ハーネスの生成
• マルチエージェント：マルチエージェントアーキテクチャ
• Gateway の設定：セッションツールの設定項目

関連項目

• セッション管理
• セッションのプルーニング