跳到主要内容

会话工具 (Session Tools)

目标：提供一套简洁、难以误用的工具集，以便代理可以列出会话、获取历史记录并发送消息到另一个会话。

工具名称​

  • sessions_list
  • sessions_history
  • sessions_send
  • sessions_spawn

关键模型​

  • 主直接聊天桶 (Direct chat bucket) 始终使用字面量键 "main"（解析为当前代理的主键）。
  • 群组聊天使用 agent:<agentId>:<channel>:group:<id> 或 agent:<agentId>:<channel>:channel:<id>（传递完整键名）。
  • 定时任务使用 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 获取工具消息。
  • 在沙箱 (sandboxed) 代理会话中运行时，会话工具默认仅具有已生成会话可见性 (spawned-only visibility)（见下文）。

行形状 (JSON)：

  • key: 会话键名 (string)
  • 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​

获取单个会话的转录记录。

参数：

  • sessionKey (必填；接受来自 sessions_list 的会话键名或 sessionId)
  • limit?: number 最大消息数（服务器会进行限制）
  • includeTools?: boolean (默认 false)

行为：

  • includeTools=false 会过滤掉 role: "toolResult" 的消息。
  • 以原始转录格式返回消息数组。
  • 当提供 sessionId 时，Clawdbot 会将其解析为相应的会话键名（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 }。
  • 交付通知 (Announce delivery) 在主运行完成后运行，且是尽力而为的；status: "ok" 不保证通知已交付。
  • 通过网关 agent.wait（服务器端）进行等待，因此重连不会导致等待中断。
  • 为主运行注入代理间消息上下文 (Agent-to-agent message context)。
  • 主运行完成后，Clawdbot 会运行一个回复循环 (reply-back loop)：
    • 第 2 轮及以后在请求代理和目标代理之间交替。
    • 回复内容完全匹配 REPLY_SKIP 时停止对话。
    • 最大轮数为 session.agentToAgent.maxPingPongTurns (0–5, 默认 5)。
  • 循环结束后，Clawdbot 运行代理间通知步骤 (agent‑to‑agent announce step)（仅限目标代理）：
    • 回复内容完全匹配 ANNOUNCE_SKIP 时保持静默。
    • 任何其他回复都会发送到目标频道。
    • 通知步骤包括原始请求 + 第 1 轮回复 + 最新的对话回复。

Channel 字段​

  • 对于群组，channel 是记录在会话条目上的频道。
  • 对于直接聊天，channel 从 lastChannel 映射。
  • 对于 cron/hook/node，channel 为 internal。
  • 如果缺失，channel 为 unknown。

安全 / 发送策略 (Security / Send Policy)​

基于频道/聊天类型的策略拦截（而非按会话 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 发现哪些代理 ID 允许用于 sessions_spawn。

行为：

  • 启动一个新的 agent:<agentId>:subagent:<uuid> 会话，且 deliver: false。
  • 子代理默认使用完整的工具集，但不包括会话工具（可通过 tools.subagents.tools 配置）。
  • 子代理不允许调用 sessions_spawn（不支持子代理生成子代理）。
  • 始终是非阻塞的：立即返回 { status: "accepted", runId, childSessionKey }。
  • 完成后，Clawdbot 运行子代理通知步骤 (announce step) 并将结果发布到请求聊天频道。
  • 在通知步骤中回复完全匹配 ANNOUNCE_SKIP 时保持静默。
  • 通知回复被归一化为 Status/Result/Notes；Status 来自运行时结果（而非模型文本）。
  • 子代理会话在 agents.defaults.subagents.archiveAfterMinutes（默认：60）后自动归档。
  • 通知回复包括一行统计信息（运行时间、令牌数、sessionKey/sessionId、转录路径以及可选的成本）。

沙箱会话可见性 (Sandbox Session Visibility)​

沙箱化会话可以使用会话工具，但默认情况下，它们只能看到通过 sessions_spawn 生成的会话。

配置：

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