セッションツール

目的：エージェントがセッションの一覧取得、履歴参照、別セッションへの送信を行うための、小さく誤用しにくいツールセット。

ツール名

sessions_list
sessions_history
sessions_send
sessions_spawn

キーモデル

メインのダイレクトチャットバケットは常にリテラルキー"main"（現在のエージェントのメインキーに解決される）。
グループチャットはagent:<agentId>:<channel>:group:<id>またはagent:<agentId>:<channel>:channel:<id>（フルキーを渡す）。
Cronジョブはcron:<job.id>。
フックはhook:<uuid>（明示的に設定されない限り）。
ノードセッションはnode-<nodeId>（明示的に設定されない限り）。

globalとunknownは予約値で、一覧に表示されません。session.scope = "global"の場合、すべてのツールでmainにエイリアスされるため、呼び出し側がglobalを見ることはありません。

sessions_list

セッションを行の配列としてリスト表示します。

パラメータ：

kinds?: string[] フィルタ："main" | "group" | "cron" | "hook" | "node" | "other"のいずれか
limit?: number 最大行数（デフォルト：サーバーデフォルト、上限例200）
activeMinutes?: number N分以内に更新されたセッションのみ
messageLimit?: number 0 = メッセージなし（デフォルト0）、>0 = 直近N件のメッセージを含む

動作：

messageLimit > 0はセッションごとにchat.historyを取得し、直近N件のメッセージを含める。
ツール結果は一覧出力からフィルタされる。ツールメッセージにはsessions_historyを使用。
サンドボックスエージェントセッションで実行中の場合、セッションツールはデフォルトでスポーンされたセッションのみ可視になる（後述）。

行の形状（JSON）：

key：セッションキー（文字列）
kind：main | group | cron | hook | node | other
channel：whatsapp | telegram | discord | signal | imessage | webchat | internal | unknown
displayName（利用可能な場合のグループ表示ラベル）
updatedAt（ミリ秒）
sessionId
model、contextTokens、totalTokens
thinkingLevel、verboseLevel、systemSent、abortedLastRun
sendPolicy（設定されている場合のセッションオーバーライド）
lastChannel、lastTo
deliveryContext（利用可能な場合の正規化された{ channel, to, accountId }）
transcriptPath（ストアディレクトリ＋sessionIdから導出されたベストエフォートパス）
messages?（messageLimit > 0の場合のみ）

sessions_history

1つのセッションのトランスクリプトを取得します。

パラメータ：

sessionKey（必須。セッションキーまたはsessions_listからのsessionIdを受け付ける）
limit?: number 最大メッセージ数（サーバーが上限を適用）
includeTools?: boolean（デフォルトfalse）

動作：

includeTools=falseはrole: "toolResult"メッセージをフィルタする。
生のトランスクリプト形式でメッセージ配列を返す。
sessionIdが渡された場合、OpenClawは対応するセッションキーに解決する（存在しないIDはエラー）。

sessions_send

別のセッションにメッセージを送信します。

パラメータ：

sessionKey（必須。セッションキーまたはsessions_listからのsessionIdを受け付ける）
message（必須）
timeoutSeconds?: number（デフォルト>0、0 = ファイア・アンド・フォーゲット）

動作：

timeoutSeconds = 0：エンキューして{ runId, status: "accepted" }を返す。
timeoutSeconds > 0：最大N秒間完了を待ち、{ runId, status: "ok", reply }を返す。
待機がタイムアウトした場合：{ runId, status: "timeout", error }。実行は継続される。後でsessions_historyを呼び出せる。
実行が失敗した場合：{ runId, status: "error", error }。
アナウンス配信はプライマリ実行完了後にベストエフォートで実行される。status: "ok"はアナウンスの配信を保証しない。
Gateway agent.wait（サーバーサイド）経由で待機するため、再接続しても待機が失われない。
エージェント間メッセージコンテキストがプライマリ実行に注入される。
セッション間メッセージはmessage.provenance.kind = "inter_session"で永続化されるため、トランスクリプト読者はルーティングされたエージェント指示と外部ユーザー入力を区別できる。
プライマリ実行完了後、OpenClawはリプライバックループを実行する：
- ラウンド2以降はリクエスター側とターゲット側のエージェントが交互に応答。
- REPLY_SKIPと正確に返信するとピンポンを停止できる。
- 最大ターン数はsession.agentToAgent.maxPingPongTurns（0-5、デフォルト5）。
ループ終了後、OpenClawはエージェント間アナウンスステップを実行する（ターゲットエージェントのみ）：
- ANNOUNCE_SKIPと正確に返信すると沈黙を維持。
- それ以外の返信はターゲットチャネルに送信される。
- アナウンスステップには元のリクエスト＋ラウンド1の返信＋最新のピンポン返信が含まれる。

チャネルフィールド

グループの場合、channelはセッションエントリに記録されたチャネル。
ダイレクトチャットの場合、channelはlastChannelからマッピング。
cron/hook/nodeの場合、channelはinternal。
不明な場合、channelはunknown。

セキュリティ／送信ポリシー

チャネル／チャットタイプによるポリシーベースのブロック（セッションID単位ではない）。

{
  "session": {
    "sendPolicy": {
      "rules": [
        {
          "match": { "channel": "discord", "chatType": "group" },
          "action": "deny"
        }
      ],
      "default": "allow"
    }
  }
}

ランタイムオーバーライド（セッションエントリ単位）：

sendPolicy: "allow" | "deny"（未設定 = 設定を継承）
sessions.patchまたはオーナー限定の/send on|off|inherit（単独メッセージ）で設定可能。

適用ポイント：

chat.send / agent（gateway）
自動返信配信ロジック

sessions_spawn

隔離されたセッションでサブエージェント実行をスポーンし、結果をリクエスター元のチャットチャネルにアナウンスします。

パラメータ：

task（必須）
label?（省略可能。ログ/UIに使用）
agentId?（省略可能。許可されていれば別のエージェントIDでスポーン）
model?（省略可能。サブエージェントのモデルをオーバーライド。無効な値はエラー）
thinking?（省略可能。サブエージェント実行のthinkingレベルをオーバーライド）
runTimeoutSeconds?（agents.defaults.subagents.runTimeoutSecondsが設定されている場合はそのデフォルト、それ以外は0。設定時はN秒後にサブエージェント実行を中断）
thread?（デフォルトfalse。チャネル/プラグインがサポートしている場合、このスポーンにスレッドバインドルーティングを要求）
mode?（run|session。デフォルトはrunだが、thread=trueの場合はsessionがデフォルト。mode="session"はthread=trueが必要）
cleanup?（delete|keep、デフォルトkeep）
sandbox?（inherit|require、デフォルトinherit。requireはターゲットの子ランタイムがサンドボックス化されていない場合にスポーンを拒否）
attachments?（省略可能なインラインファイルの配列。サブエージェントランタイムのみ、ACPは拒否）。各エントリ：{ name, content, encoding?: "utf8" | "base64", mimeType? }。ファイルは子ワークスペースの.openclaw/attachments/<uuid>/に実体化される。ファイルごとのsha256を含むレシートを返す。
attachAs?（省略可能。将来のマウント実装用に予約された{ mountPath? }ヒント）

許可リスト：

agents.list[].subagents.allowAgents：agentIdで許可されるエージェントIDのリスト（["*"]で任意を許可）。デフォルト：リクエスターエージェントのみ。
サンドボックス継承ガード：リクエスターセッションがサンドボックス化されている場合、sessions_spawnはサンドボックス外で実行されるターゲットを拒否する。

ディスカバリー：

agents_listを使ってsessions_spawnで許可されるエージェントIDを確認できる。

動作：

deliver: falseで新しいagent:<agentId>:subagent:<uuid>セッションを開始する。
サブエージェントはデフォルトでセッションツールを除くフルツールセットを使用（tools.subagents.toolsで設定可能）。
サブエージェントはsessions_spawnを呼び出せない（サブエージェントからサブエージェントへのスポーンは不可）。
常にノンブロッキング：即座に{ status: "accepted", runId, childSessionKey }を返す。
thread=trueの場合、チャネルプラグインが配信/ルーティングをスレッドターゲットにバインドできる（Discordのサポートはsession.threadBindings.*とchannels.discord.threadBindings.*で制御）。
完了後、OpenClawはサブエージェントのアナウンスステップを実行し、結果をリクエスター元のチャットチャネルに投稿する。
- アシスタントの最終返信が空の場合、サブエージェント履歴の最新のtoolResultがResultとして含まれる。
アナウンスステップでANNOUNCE_SKIPと正確に返信すると沈黙を維持。
アナウンス返信はStatus/Result/Notesに正規化される。Statusはランタイムの結果から取得され（モデルテキストではない）。
サブエージェントセッションはagents.defaults.subagents.archiveAfterMinutes（デフォルト：60）後に自動アーカイブされる。
アナウンス返信には統計行（ランタイム、トークン数、sessionKey/sessionId、トランスクリプトパス、オプションのコスト）が含まれる。

サンドボックスセッションの可視性

セッションツールの可視範囲を制限して、クロスセッションアクセスを抑制できます。

デフォルトの動作：

tools.sessions.visibilityのデフォルトはtree（現在のセッション＋スポーンされたサブエージェントセッション）。
サンドボックスセッションの場合、agents.defaults.sandbox.sessionToolsVisibilityで可視性をハードクランプできる。

設定：

{
  tools: {
    sessions: {
      // "self" | "tree" | "agent" | "all"
      // デフォルト: "tree"
      visibility: "tree",
    },
  },
  agents: {
    defaults: {
      sandbox: {
        // デフォルト: "spawned"
        sessionToolsVisibility: "spawned", // or "all"
      },
    },
  },
}

補足：

self：現在のセッションキーのみ。
tree：現在のセッション＋現在のセッションからスポーンされたセッション。
agent：現在のエージェントIDに属するすべてのセッション。
all：すべてのセッション（クロスエージェントアクセスにはtools.agentToAgentが別途必要）。
セッションがサンドボックス化されておりsessionToolsVisibility="spawned"の場合、tools.sessions.visibility="all"を設定しても、OpenClawは可視性をtreeにクランプする。