Session Tools

目标：提供一套小型、不易误用的工具集，让 agent 可以列出会话、获取历史记录并发送到另一个会话。

工具名称

sessions_list
sessions_history
sessions_send
sessions_spawn

键模型

主直接聊天桶始终是字面键 "main"（解析为当前 agent 的主键）。
群聊使用 agent:<agentId>:<channel>:group:<id> 或 agent:<agentId>:<channel>:channel:<id>（传递完整键）。
Cron 作业使用 cron:<job.id>。
Hooks 使用 hook:<uuid>，除非显式设置。
Node 会话使用 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 获取工具消息。
当在沙盒化 agent 会话中运行时，session 工具默认为仅 spawned 可见性（见下文）。

行形状（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（最佳努力路径，从 store dir + sessionId 派生）
messages?（仅当 messageLimit > 0）

sessions_history

获取一个会话的转录。

参数：

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（服务器端）等待，因此重新连接不会丢失等待。
Agent-to-agent 消息上下文注入到主运行中。
会话间消息以 message.provenance.kind = "inter_session" 持久化，因此转录阅读器可以区分路由的 agent 指令和外部用户输入。
主运行完成后，OpenClaw 运行回复回环：
- 第 2+ 轮在请求者和目标 agent 之间交替。
- 精确回复 REPLY_SKIP 以停止乒乓。
- 最大回合数是 session.agentToAgent.maxPingPongTurns（0-5，默认 5）。
循环结束后，OpenClaw 运行agent-to-agent 宣布步骤（仅目标 agent）：
- 精确回复 ANNOUNCE_SKIP 以保持沉默。
- 任何其他回复都会发送到目标频道。
- 宣布步骤包括原始请求 + 第 1 轮回复 + 最新的乒乓回复。

Channel 字段

对于群组，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

在隔离的会话中生成子 agent 运行，并将结果宣布回请求者聊天频道。

参数：

task（必需）
label?（可选；用于日志/UI）
agentId?（可选；如果允许，在另一个 agent id 下生成）
model?（可选；覆盖子 agent 模型；无效值报错）
thinking?（可选；覆盖子 agent 运行的 thinking 级别）
runTimeoutSeconds?（设置时默认为 agents.defaults.subagents.runTimeoutSeconds，否则为 0；设置时，在 N 秒后中止子 agent 运行）
thread?（默认 false；当频道/插件支持时，请求此生成的线程绑定路由）
mode?（run|session；默认为 run，但当 thread=true 时默认为 session；mode="session" 需要 thread=true）
cleanup?（delete|keep，默认 keep）
sandbox?（inherit|require，默认 inherit；require 拒绝生成，除非目标子运行时是沙盒化的）
attachments?（可选的内联文件数组；仅子 agent 运行时，ACP 拒绝）。每个条目：{ name, content, encoding?: "utf8" | "base64", mimeType? }。文件具体化到子工作区的 .openclaw/attachments/<uuid>/。返回每个文件的 sha256 收据。
attachAs?（可选；{ mountPath? } 提示，保留用于未来的挂载实现）

允许列表：

agents.list[].subagents.allowAgents：允许通过 agentId 使用的 agent id 列表（["*"] 允许任何）。默认：仅请求者 agent。
沙盒继承守卫：如果请求者会话是沙盒化的，sessions_spawn 拒绝会运行非沙盒化的目标。

发现：

使用 agents_list 发现哪些 agent id 允许用于 sessions_spawn。

行为：

启动新的 agent:<agentId>:subagent:<uuid> 会话，deliver: false。
子 agent 默认为完整工具集减去 session 工具（可通过 tools.subagents.tools 配置）。
子 agent 不允许调用 sessions_spawn（不允许子 agent → 子 agent 生成）。
始终非阻塞：立即返回 { status: "accepted", runId, childSessionKey }。
使用 thread=true 时，频道插件可以将交付/路由绑定到线程目标（Discord 支持由 session.threadBindings.* 和 channels.discord.threadBindings.* 控制）。
完成后，OpenClaw 运行子 agent宣布步骤并将结果发布到请求者聊天频道。
- 如果助手最终回复为空，则子 agent 历史记录中的最新 toolResult 作为 Result 包含。
在宣布步骤中精确回复 ANNOUNCE_SKIP 以保持沉默。
宣布回复标准化为 Status/Result/Notes；Status 来自运行时结果（不是模型文本）。
子 agent 会话在 agents.defaults.subagents.archiveAfterMinutes（默认：60）后自动归档。
宣布回复包括统计行（运行时、令牌、sessionKey/sessionId、转录路径和可选成本）。

沙盒会话可见性

Session 工具可以限定范围以减少跨会话访问。

默认行为：

tools.sessions.visibility 默认为 tree（当前会话 + spawned 子 agent 会话）。
对于沙盒化会话，agents.defaults.sandbox.sessionToolsVisibility 可以强制限制可见性。

配置：

{
  tools: {
    sessions: {
      // "self" | "tree" | "agent" | "all"
      // 默认："tree"
      visibility: "tree",
    },
  },
  agents: {
    defaults: {
      sandbox: {
        // 默认："spawned"
        sessionToolsVisibility: "spawned", // 或 "all"
      },
    },
  },
}

注意：

self：仅当前会话键。
tree：当前会话 + 当前会话生成的会话。
agent：属于当前 agent id 的任何会话。
all：任何会话（跨 agent 访问仍需要 tools.agentToAgent）。
当会话是沙盒化且 sessionToolsVisibility="spawned" 时，即使你设置 tools.sessions.visibility="all"，OpenClaw 也会将可见性限制为 tree。