Session 工具

目标：提供一套简洁、不易误用的工具集,让 Agent 可以列出 session、获取历史记录,以及向其他 session 发送消息。

工具名称

  • sessions_list
  • sessions_history
  • sessions_send
  • sessions_spawn

Key 模型

  • 主直接聊天的 key 始终是字面值 "main"(解析为当前 Agent 的主 key)。
  • 群聊使用 agent:<agentId>:<channel>:group:<id> 或 agent:<agentId>:<channel>:channel:<id>(传递完整 key)。
  • Cron 任务使用 cron:<job.id>。
  • Hook 使用 hook:<uuid>,除非显式设置。
  • Node session 使用 node-<nodeId>,除非显式设置。

global 和 unknown 是保留值,永远不会被列出。如果 session.scope = "global",所有工具会将其别名为 main,调用者永远看不到 global。

sessions_list

以数组形式列出 session。

参数:

  • kinds?: string[] 过滤器:可选值为 "main" | "group" | "cron" | "hook" | "node" | "other"
  • limit?: number 最大行数(默认:服务器默认值,限制如 200)
  • activeMinutes?: number 仅显示 N 分钟内更新过的 session
  • messageLimit?: number 0 = 不包含消息(默认 0);>0 = 包含最后 N 条消息

行为:

  • messageLimit > 0 会获取每个 session 的 chat.history 并包含最后 N 条消息。
  • 列表输出中会过滤掉工具结果;使用 sessions_history 查看工具消息。
  • 在 Sandbox Agent session 中运行时,session 工具默认为 仅显示已生成的 session(见下文)。

行结构 (JSON):

  • key: session 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 (session 覆盖设置,如果已设置)
  • lastChannel, lastTo
  • deliveryContext (标准化的 { channel, to, accountId },如果可用)
  • transcriptPath (从存储目录 + sessionId 派生的尽力而为路径)
  • messages? (仅当 messageLimit > 0 时)

sessions_history

获取单个 session 的对话记录。

参数:

  • sessionKey (必需;接受 session key 或来自 sessions_list 的 sessionId)
  • limit?: number 最大消息数(服务器限制)
  • includeTools?: boolean (默认 false)

行为:

  • includeTools=false 会过滤 role: "toolResult" 消息。
  • 返回原始对话记录格式的消息数组。
  • 当给定 sessionId 时,OpenClaw 会将其解析为对应的 session key(缺失的 id 会报错)。

sessions_send

向另一个 session 发送消息。

参数:

  • sessionKey (必需;接受 session key 或来自 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 到 Agent 的消息上下文会注入到主运行中。
  • 主运行完成后,OpenClaw 会运行 回复循环:
    • 第 2 轮及以后在请求者和目标 Agent 之间交替。
    • 精确回复 REPLY_SKIP 可停止乒乓。
    • 最大轮数为 session.agentToAgent.maxPingPongTurns (0–5,默认 5)。
  • 循环结束后,OpenClaw 会运行 Agent 到 Agent 通知步骤(仅目标 Agent):
    • 精确回复 ANNOUNCE_SKIP 保持静默。
    • 任何其他回复都会发送到目标 Channel。
    • 通知步骤包含原始请求 + 第 1 轮回复 + 最新乒乓回复。

Channel 字段

  • 对于群组,channel 是 session 条目上记录的 channel。
  • 对于直接聊天,channel 从 lastChannel 映射。
  • 对于 cron/hook/node,channel 是 internal。
  • 如果缺失,channel 是 unknown。

安全 / 发送策略

基于 channel/聊天类型的策略阻止(不是按 session id)。

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

运行时覆盖(按 session 条目):

  • sendPolicy: "allow" | "deny" (未设置 = 继承配置)
  • 可通过 sessions.patch 或仅所有者的 /send on|off|inherit(独立消息)设置。

执行点:

  • chat.send / agent (Gateway)
  • 自动回复投递逻辑

sessions_spawn

在隔离的 session 中生成子 Agent 运行,并将结果通知回请求者聊天 Channel。

参数:

  • task (必需)
  • label? (可选;用于日志/UI)
  • agentId? (可选;如果允许,在另一个 agent id 下生成)
  • model? (可选;覆盖子 Agent 模型;无效值会报错)
  • runTimeoutSeconds? (默认 0;设置后,N 秒后中止子 Agent 运行)
  • cleanup? (delete|keep,默认 keep)

白名单:

  • agents.list[].subagents.allowAgents: 通过 agentId 允许的 agent id 列表(["*"] 允许任何)。默认:仅请求者 Agent。

发现:

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

行为:

  • 启动新的 agent:<agentId>:subagent:<uuid> session,设置 deliver: false。
  • 子 Agent 默认使用完整工具集 减去 session 工具(可通过 tools.subagents.tools 配置)。
  • 子 Agent 不允许调用 sessions_spawn(不能子 Agent → 子 Agent 生成)。
  • 始终非阻塞:立即返回 { status: "accepted", runId, childSessionKey }。
  • 完成后,OpenClaw 运行子 Agent 通知步骤并将结果发布到请求者聊天 Channel。
  • 在通知步骤期间精确回复 ANNOUNCE_SKIP 保持静默。
  • 通知回复标准化为 Status/Result/Notes;Status 来自运行时结果(不是模型文本)。
  • 子 Agent session 在 agents.defaults.subagents.archiveAfterMinutes(默认:60)后自动归档。
  • 通知回复包含统计行(运行时间、Token、sessionKey/sessionId、对话记录路径和可选成本)。

Sandbox Session 可见性

Sandbox session 可以使用 session 工具,但默认情况下它们只能看到通过 sessions_spawn 生成的 session。

配置:

{
  agents: {
    defaults: {
      sandbox: {
        // 默认: "spawned"
        sessionToolsVisibility: "spawned", // 或 "all"
      },
    },
  },
}