セッションツール

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

利用可能なツール

これらのツールには、引き続き有効なツールプロファイルと許可/拒否ポリシーが適用されます。tools.profile: "coding" には、完全なセッションオーケストレーションセットが含まれます。tools.profile: "messaging" には、セッションのセルフサービス、検出、再呼び出し、セッション間メッセージング、外部会話ツール、および完全な生成ライフサイクル（sessions_spawn、sessions_yield、subagents）が含まれます。UI 専用のタスク提案ツール spawn_task と dismiss_task は、引き続きコーディングプロファイルのツールです。

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

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

sessions_list は、セッションキー、エージェント、種類、チャンネル、ラベル/タイトル/プレビューフィールド、親子関係、最終更新、アーカイブ/ピン留め状態、状態バージョン、モデル、コンテキスト/合計トークン数、実行ステータス、および最後の実行が中断されたかどうかを含む、絞り込まれた検出行を返します。kinds（配列。使用可能な値：main、group、cron、hook、node、other）、完全一致の label、完全一致の agentId、search テキスト、または最近の期間（activeMinutes）で絞り込めます。デフォルトではアクティブなセッションが返されます。代わりにアーカイブ済みセッションを確認するには、archived: true を渡します。メールボックス形式のトリアージが必要な場合は、includeDerivedTitles、includeLastMessage、または messageLimit（上限20）を設定します。これにより、可視性スコープに基づいて生成されたタイトル、最後のメッセージのプレビュー抜粋、または各行に含める件数を制限した最近のメッセージを取得できます。配信ルーティング、内部セッション ID、実行単位のタイミング/設定、コスト見積もり、およびトランスクリプトパスは意図的に省略されています。これらの所有者固有の詳細については、session_status、会話ツール、および sessions_history を使用してください。生成されるタイトルとプレビューは、設定されたセッションツール可視性ポリシーに基づいて呼び出し元がすでに表示できるセッションについてのみ作成されるため、無関係なセッションは非表示のままです。可視性が制限されている場合、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" など）を sessions_history、sessions_send、session_status で使用します。これらのターゲット指定ツールは既知のセッション ID も解決できますが、sessions_list は内部 ID を公開しません。

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

表示可能なユーザーおよびアシスタントのトランスクリプトテキスト全体を正確に全文検索するには、sessions_search を使用します。その結果には、後続の sessions_history 呼び出しに使用する sessionKey が含まれます。可視性フィルタリング、抜粋の秘匿化、および出力範囲の制限は履歴境界と同じです。

セッション設定とグループの管理

所有者によって制限される sessions ツールは、範囲を限定した2つのセルフサービス機能を提供します。

• action: "patch" はデフォルトで現在のセッションを変更します。または、sessionKey で選択した別の表示可能なセッションを変更します。ラベル、サイドバーアイコン、ピン留め/アーカイブ状態、モデル、および思考レベルを設定できます。リセット、削除、または compact 操作は公開しません。
• group_list、group_set、group_rename、group_delete は、グローバルな順序付きセッショングループカタログを管理します。group_set は、1つの項目を更新するのではなく、順序付き名前リスト全体を置き換えます。

エージェントが選択したモデルの変更は、その選択での実行が正常に完了するまで元に戻せます。認証、請求、またはモデルが見つからないエラーにより選択したモデルが明確に使用不能な場合、OpenClaw は以前のモデルを復元し、表示可能なシステムノートを書き込みます。一時的なレート制限、過負荷、タイムアウト、ネットワーク、およびサーバー障害では、選択は取り消されません。

セッションと会話の違い

セッションはローカルのモデルコンテキストです。会話は、1人の相手、チャンネル、スレッドなどの厳密な外部アドレスです。この2つは関連付けられていますが、相互に置き換えられるものではありません。ダイレクトメッセージは、個別の会話アドレスを維持しながら、1つの main セッションを共有できます。

conversations_list は、アクティブなエージェントの不透明な conversationRef 値を返します。明示的な channel を指定すると、Gateway は承認済み Reef ピアなど、そのチャンネルのローカルディレクトリからアドレスも更新します。現在の結果ページに含まれない特定のピアを検索するには、query を使用します。検出はモデルコンテキストのセッションを作成せずにアドレスをカタログへ登録します。対応するセッションは、配信または受信コンテキストで必要になったときにのみ作成されます。会話の検出と配信では Gateway のチャンネル認証情報を使用するため、所有者のみが実行できます。送信後に結果を待たない配信には conversations_send を使用します。リモートの返信が現在のモデルターンに属する場合は、conversations_turn を使用します。Gateway は1つのトランスポートメッセージ ID を予約し、トランスポート I/O の前に配信操作とキューの意図を永続化し、2回目のローカルエージェントターンを開始する代わりに、対応する返信をツールから返します。配信操作はモデルのトランスクリプト外に保存されます。取得された返信は、ツール結果がモデルコンテキストを保持する間、付随的な成果物としてのみ保持されます。キュー登録後に Gateway が再起動した場合、配信は復旧できますが、プロセスローカルの待機処理が失われているため、後から届いた返信は通常の受信ディスパッチに従います。未要求の受信メッセージは常に通常のチャンネルディスパッチ経路を通じて処理されます。

明示的な生のチャンネルターゲットをすでに持っている場合、またはチャンネル固有のアクションが必要な場合は、共有の message ツールを使用します。会話参照のスコープはアクティブなエージェントに限定されるため、セッションキーから構築するのではなく、conversations_list を通じて取得する必要があります。

Code Mode では、会話ツールは Gateway の出力契約をそのまま再利用します。1つの exec セルでアドレスを一覧表示し、返された conversationRef を選択して、conversations_send または conversations_turn を呼び出せます。ネストされた呼び出しにも、通常のツールポリシーと承認が引き続き適用されます。

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

sessions_send は同じ Gateway 上で別のセッションを実行し、必要に応じて応答を待ちます。その sessionKey、label、または agentId は、外部の宛先ではなく、ローカルのモデルコンテキストを選択します。生成された返信は、確立済みの要求元またはターゲットの配信コンテキストを通じて引き続き通知できます。この既存の動作に変更はありません。外部へ厳密に配信するには、会話ツール、またはチャンネルとターゲットを明示した message を使用します。

• 送信後に待機しない： timeoutSeconds: 0 を設定すると、キューへ登録して直ちに戻ります。
• 返信を待つ： タイムアウトを設定すると、応答がインラインで返されます。

キーが :thread:<id> で終わるものなど、スレッドスコープのチャットセッションは、有効な sessions_send ターゲットではありません。ツール経由のメッセージが進行中の人間向けスレッド内に表示されないように、エージェント間の連携には親チャンネルのセッションキーを使用してください。

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

ターゲットが応答した後、OpenClaw は、組み込みの上限に達するまでエージェントが交互にメッセージを送る返信ループを実行できます。ターゲットエージェントは 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 件受信します。

状態変更イベントでは、重複するセッション ID／エージェント ID が省略され、モデルに有用なペイロードフィールド（outcome、channel、または turns）のみが公開されます。照合に使用するイベント概要とアクター／実行識別子は引き続き利用できます。

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

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

subagents は、ネイティブサブエージェント実行と共有バックグラウンドタスク台帳を対象とするセッションツリービューです。action: "list" は、アクティブ／最近のサブエージェントに加えて、スコープが設定された ACP、CLI／メディア、および Cron タスクを報告します。action: "cancel" は返された taskId を受け取り、呼び出し元が制御するセッションツリー内の処理のみを停止できます。リーフサブエージェントは、別のセッションのタスクをキャンセルできません。

サブエージェントの生成

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" が使用されます。
• 非表示のサブエージェントセッションではなく、永続的なダッシュボードセッションを作成するための visible: true。可視の生成では、明示的なモデル、作業ディレクトリ、同一エージェントのトランスクリプトフォーク、およびオプションの管理対象ワークツリーがサポートされます。正確な互換性の制限については、サブエージェントを参照してください。

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

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

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

可視性

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

デフォルトは tree です。サンドボックス化されたセッションは、設定にかかわらず tree に制限されます。 デフォルトの session.dmScope: "main" では、グループ内のアクティビティにより、監視対象の 同一エージェントグループセッションをメインセッションから読み取れるようになります。

関連資料

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

関連項目

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