セッションツール

目標：エージェントがセッションを一覧表示し、履歴を取得し、別のセッションに送信できるように、小さく誤用しにくいツールセットを提供します。

ツール名

  • 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"はアナウンスが配信されたことを保証しません。
  • ゲートウェイagent.wait（サーバー側）経由で待機するため、再接続しても待機がドロップされません。
  • エージェント間メッセージコンテキストはプライマリ実行のために注入されます。
  • プライマリ実行が完了した後、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（ゲートウェイ）
  • 自動返信配信ロジック

sessions_spawn

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

パラメータ：

  • task（必須）
  • label?（オプション。ログ/UIに使用）
  • agentId?（オプション。許可されている場合、別のエージェントIDの下でスポーン）
  • model?（オプション。サブエージェントモデルをオーバーライド。無効な値はエラー）
  • runTimeoutSeconds?（デフォルト0。設定されている場合、N秒後にサブエージェント実行を中止）
  • cleanup?（delete|keep、デフォルトkeep）

許可リスト：

  • agents.list[].subagents.allowAgents：agentId経由で許可されるエージェントIDのリスト（すべてを許可する場合は["*"]）。デフォルト：リクエスタエージェントのみ。

発見：

  • agents_listを使用して、sessions_spawnで許可されているエージェントIDを発見します。

動作：

  • deliver: falseで新しいagent:<agentId>:subagent:<uuid>セッションを開始します。
  • サブエージェントはデフォルトで完全なツールセットからセッションツールを除いたもの（tools.subagents.toolsで設定可能）。
  • サブエージェントはsessions_spawnを呼び出すことは許可されていません（サブエージェント→サブエージェントのスポーンはなし）。
  • 常に非ブロッキング：即座に{ status: "accepted", runId, childSessionKey }を返します。
  • 完了後、OpenClawはサブエージェントアナウンスステップを実行し、結果をリクエスタチャットチャネルに投稿します。
  • アナウンスステップ中に正確にANNOUNCE_SKIPと返信すると静かになります。
  • アナウンス返信はStatus/Result/Notesに正規化されます。Statusはランタイム結果から取得されます（モデルテキストではありません）。
  • サブエージェントセッションはagents.defaults.subagents.archiveAfterMinutes（デフォルト：60）後に自動アーカイブされます。
  • アナウンス返信には統計行（ランタイム、トークン、sessionKey/sessionId、トランスクリプトパス、オプションのコスト）が含まれます。

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

サンドボックス化されたセッションはセッションツールを使用できますが、デフォルトではsessions_spawn経由でスポーンしたセッションのみが表示されます。

設定：

{
  agents: {
    defaults: {
      sandbox: {
        // デフォルト: "spawned"
        sessionToolsVisibility: "spawned" // または "all"
      }
    }
  }
}
← ドキュメントに戻る