中文 Subagents

• 原始链接：https://docs.openclaw.ai/zh-CN/tools/subagents
• 来源章节：5. 官方文档：工具、技能、插件与自动化
• 来源小节：无
• 抓取方式：jina:https://r.jina.ai/http://docs.openclaw.ai/zh-CN/tools/subagents
• 抓取时间：2026-04-05 13:47:10
• 状态：ok

中文内容

子智能体

子智能体是从现有智能体运行中生成的后台智能体运行。它们在自己的会话中运行（agent:<agentId>:subagent:<uuid>），完成后将结果通告回请求者的聊天渠道。

斜杠命令

使用 /subagents 检查或控制当前会话的子智能体运行：

• /subagents list
• /subagents kill <id|#|all>
• /subagents log <id|#> [limit] [tools]
• /subagents info <id|#>
• /subagents send <id|#> <message>
• /subagents steer <id|#> <message>
• /subagents spawn <agentId> <task> [--model <model>] [--thinking <level>]

/subagents info 显示运行元数据（状态、时间戳、会话 id、转录路径、清理）。

启动行为

/subagents spawn 以用户命令方式启动后台子智能体，任务完成后会向请求者聊天频道回发一条最终完成消息。

• 该命令非阻塞，先返回 runId。
• 完成后，子智能体会将汇总/结果消息发布到请求者聊天渠道。
• --model 与 --thinking 可仅对本次运行做覆盖设置。
• 可在完成后通过 info/log 查看详细信息和输出。

主要目标：

• 并行化”研究 / 长任务 / 慢工具”工作，而不阻塞主运行。
• 默认保持子智能体隔离（会话分离 + 可选沙箱隔离）。
• 保持工具接口难以滥用：子智能体默认不获得会话工具。
• 避免嵌套扇出：子智能体不能生成子智能体。

成本说明：每个子智能体都有自己的上下文和 token 使用量。对于繁重或重复的任务，为子智能体设置更便宜的模型，而让主智能体使用更高质量的模型。你可以通过 agents.defaults.subagents.model 或每智能体覆盖来配置。

工具

使用 sessions_spawn：

• 启动子智能体运行（deliver: false，全局队列：subagent）
• 然后运行通告步骤，并将通告回复发布到请求者的聊天渠道
• 默认模型：继承调用者，除非你设置了 agents.defaults.subagents.model（或每智能体的 agents.list[].subagents.model）；显式的 sessions_spawn.model 仍然优先。
• 默认思考：继承调用者，除非你设置了 agents.defaults.subagents.thinking（或每智能体的 agents.list[].subagents.thinking）；显式的 sessions_spawn.thinking 仍然优先。

工具参数：

• task（必需）
• label?（可选）
• agentId?（可选；如果允许，在另一个智能体 id 下生成）
• model?（可选；覆盖子智能体模型；无效值会被跳过，子智能体将使用默认模型运行并在工具结果中显示警告）
• thinking?（可选；覆盖子智能体运行的思考级别）
• runTimeoutSeconds?（默认 0；设置后，子智能体运行在 N 秒后中止）
• cleanup?（delete|keep，默认 keep）

允许列表：

• agents.list[].subagents.allowAgents：可以通过 agentId 指定的智能体 id 列表（["*"] 允许任意）。默认：仅限请求者智能体。

发现：

• 使用 agents_list 查看当前允许用于 sessions_spawn 的智能体 id。

自动归档：

• 子智能体会话在 agents.defaults.subagents.archiveAfterMinutes 后自动归档（默认：60）。
• 归档使用 sessions.delete 并将转录重命名为 *.deleted.<timestamp>（同一文件夹）。
• cleanup: "delete" 在通告后立即归档（仍通过重命名保留转录）。
• 自动归档是尽力而为的；如果 Gateway 网关重启，待处理的定时器会丢失。
• runTimeoutSeconds不会自动归档；它只停止运行。会话会保留直到自动归档。

认证

子智能体认证按智能体 id 解析，而不是按会话类型：

• 子智能体会话键是 agent:<agentId>:subagent:<uuid>。
• 认证存储从该智能体的 agentDir 加载。
• 主智能体的认证配置文件作为回退合并；智能体配置文件在冲突时覆盖主配置文件。

注意：合并是累加的，所以主配置文件始终可用作回退。目前尚不支持每智能体完全隔离的认证。

通告

子智能体通过通告步骤报告：

• 通告步骤在子智能体会话中运行（不是请求者会话）。

• 如果子智能体精确回复 ANNOUNCE_SKIP，则不发布任何内容。

• 否则，通告回复通过后续的 agent 调用（deliver=true）发布到请求者的聊天渠道。

• 通告回复在可用时保留线程/话题路由（Slack 线程、Telegram 话题、Matrix 线程）。

• 通告消息被规范化为稳定模板：

  • Status: 从运行结果派生（success、error、timeout 或 unknown）。
  • Result: 通告步骤的摘要内容（如果缺失则为 (not available)）。
  • Notes: 错误详情和其他有用的上下文。

• Status 不是从模型输出推断的；它来自运行时结果信号。

通告负载在末尾包含统计行（即使被包装）：

• 运行时间（例如 runtime 5m12s）
• Token 使用量（输入/输出/总计）
• 配置模型定价时的估计成本（models.providers.*.models[].cost）
• sessionKey、sessionId 和转录路径（以便主智能体可以通过 sessions_history 获取历史记录或检查磁盘上的文件）

工具策略（子智能体工具）

默认情况下，子智能体获得除会话工具外的所有工具：

• sessions_list
• sessions_history
• sessions_send
• sessions_spawn

通过配置覆盖：

{
  agents: {
    defaults: {
      subagents: {
        maxConcurrent: 1,
      },
    },
  },
  tools: {
    subagents: {
      tools: {
        // deny 优先
        deny: ["gateway", "cron"],
        // 如果设置了 allow，则变为仅允许模式（deny 仍然优先）
        // allow: ["read", "exec", "process"]
      },
    },
  },
}

并发

子智能体使用专用的进程内队列通道：

• 通道名称：subagent
• 并发数：agents.defaults.subagents.maxConcurrent（默认 8）

停止

• 在请求者聊天中发送 /stop 会中止请求者会话并停止从中生成的任何活动子智能体运行。

限制

• 子智能体通告是尽力而为的。如果 Gateway 网关重启，待处理的”通告回复”工作会丢失。
• 子智能体仍然共享相同的 Gateway 网关进程资源；将 maxConcurrent 视为安全阀。
• sessions_spawn 始终是非阻塞的：它立即返回 { status: "accepted", runId, childSessionKey }。
• 子智能体上下文仅注入 AGENTS.md + TOOLS.md（无 SOUL.md、IDENTITY.md、USER.md、HEARTBEAT.md 或 BOOTSTRAP.md）。