子智能体

子智能体是从现有智能体运行中生成的后台智能体运行。 它们在自己的会话（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>]

使用顶层 /steer <message> 来操控当前请求者会话的活动运行。当目标是子运行时，使用 /subagents steer <id|#> <message>。

/subagents info 会显示运行元数据（状态、时间戳、会话 ID、 转录记录路径、清理）。使用 sessions_history 获取有界且经过安全过滤的回忆视图； 当你需要原始完整转录记录时，请检查磁盘上的转录记录路径。

线程绑定控制

这些命令适用于支持持久线程绑定的渠道。 请参阅下方的支持线程的渠道。

/focus <subagent-label|session-key|session-id|session-label>/unfocus/agents/session idle <duration|off>/session max-age <duration|off>

生成行为

/subagents spawn 会以用户命令（而不是内部中继）的形式启动后台子智能体， 并在运行完成时向请求者聊天发送一次最终完成更新。

上下文模式

原生子智能体默认以隔离方式启动，除非调用方明确要求 fork 当前转录记录。

请谨慎使用 fork。它用于上下文敏感的委派， 不能替代清晰的任务提示词。

工具：sessions_spawn

在全局 subagent 通道上以 deliver: false 启动一个子智能体运行， 然后运行一个通知步骤，并将通知回复发布到请求者 聊天渠道。

可用性取决于调用方的有效工具策略。coding 和 full 配置文件默认公开 sessions_spawn。messaging 配置文件 不会公开；请添加 tools.alsoAllow: ["sessions_spawn", "sessions_yield", "subagents"]，或对应该委派工作的智能体使用 tools.profile: "coding"。 渠道/群组、提供商、沙箱，以及每个智能体的允许/拒绝策略， 仍然可以在配置文件阶段之后移除该工具。请在同一 会话中使用 /tools 确认有效工具列表。

默认值：

• **模型：**继承调用方，除非你设置了 agents.defaults.subagents.model（或每个智能体的 agents.list[].subagents.model）；显式的 sessions_spawn.model 仍然优先。
• **Thinking：**继承调用方，除非你设置了 agents.defaults.subagents.thinking（或每个智能体的 agents.list[].subagents.thinking）；显式的 sessions_spawn.thinking 仍然优先。
• **运行超时：**如果省略 sessions_spawn.runTimeoutSeconds，OpenClaw 会在已设置时使用 agents.defaults.subagents.runTimeoutSeconds；否则回退到 0（无超时）。

委派提示模式

agents.defaults.subagents.delegationMode 只控制提示词指导；它不会改变工具策略，也不会强制委派。

• suggest（默认）：保留标准提示，建议对更大或更慢的工作使用子智能体。
• prefer：告诉主智能体保持响应，并通过 sessions_spawn 委派任何比直接回复更复杂的事项。

每个智能体的覆盖项使用 agents.list[].subagents.delegationMode。

{  agents: {    defaults: {      subagents: {        delegationMode: "prefer",        maxConcurrent: 4,      },    },    list: [      {        id: "coordinator",        subagents: { delegationMode: "prefer" },      },    ],  },}

工具参数

任务名称和定向

taskName 是用于编排的面向模型句柄，不是会话键。 当协调器可能需要稍后引导或终止该子项时，可将其用于稳定的子项名称，例如 review_subagents、 linux_validation 或 docs_update。

目标解析接受精确的 taskName 匹配和无歧义的前缀。 匹配范围限定在与编号 /subagents 目标相同的活动/近期目标窗口内，因此过时的已完成子项不会让复用的句柄变得有歧义。如果两个活动或近期子项共享同一个 taskName，该目标就有歧义；请改用列表索引、会话键或运行 ID。

保留目标 last 和 all 不是有效的 taskName 值， 因为它们已经具有控制含义。

工具：sessions_yield

结束当前模型轮次并等待运行时事件，主要是子智能体完成事件，以便它们作为下一条消息到达。当请求者必须等到这些完成事件到达后才能生成最终回答时，在生成必需的子项工作后使用它。

sessions_yield 是等待原语。不要仅为检测子项完成而用对 subagents、sessions_list、sessions_history 的轮询循环、shell sleep 或进程轮询来替代它。

只有在会话的有效工具列表包含 sessions_yield 时才使用它。某些极简或自定义工具配置可能会暴露 sessions_spawn 和 subagents，但不暴露 sessions_yield；在这种情况下，不要为了等待完成而发明轮询循环。

当存在活动子项时，OpenClaw 会在正常轮次中注入一个紧凑的运行时生成 Active Subagents 提示块，让请求者无需轮询即可看到当前子会话、运行 ID、状态、标签、任务和 taskName 别名。该块中的任务和标签字段会作为数据而非指令被引用，因为它们可能来自用户/模型提供的生成参数。

工具：subagents

列出、引导或终止请求者会话拥有的已生成子智能体运行。 它的作用域限定为当前请求者；子项只能查看/控制自己控制的子项。

将 subagents 用于按需状态、调试、引导或终止。 使用 sessions_yield 等待完成事件。

线程绑定会话

当某个频道启用线程绑定时，子智能体可以保持绑定到某个线程，使该线程中的后续用户消息继续路由到同一个子智能体会话。

支持线程的频道

Discord 目前是唯一支持的频道。它支持持久线程绑定子智能体会话（带 thread: true 的 sessions_spawn）、手动线程控制（/focus、/unfocus、/agents、 /session idle、/session max-age），以及适配器键 channels.discord.threadBindings.enabled、 channels.discord.threadBindings.idleHours、 channels.discord.threadBindings.maxAgeHours 和 channels.discord.threadBindings.spawnSessions。

快速流程

手动控制

配置开关

• 全局默认值： session.threadBindings.enabled、session.threadBindings.idleHours、session.threadBindings.maxAgeHours。
• 频道覆盖和生成自动绑定键是适配器特定的。见上方支持线程的频道。

有关当前适配器详情，请参阅配置参考和 斜杠命令。

允许列表

如果请求者会话处于沙箱隔离状态，sessions_spawn 会拒绝会以非沙箱隔离方式运行的目标。

设备发现

使用 agents_list 查看当前允许用于 sessions_spawn 的智能体 ID。响应包含每个列出智能体的有效模型和嵌入式运行时元数据，以便调用方区分 PI、Codex 应用服务器以及其他已配置的原生运行时。

自动归档

• 子智能体会话会在 agents.defaults.subagents.archiveAfterMinutes 后自动归档（默认 60）。
• 归档使用 sessions.delete，并将转录记录重命名为 *.deleted.<timestamp>（同一文件夹）。
• cleanup: "delete" 会在公告后立即归档（仍会通过重命名保留转录记录）。
• 自动归档是尽力而为；如果 Gateway 网关重启，待处理定时器会丢失。
• runTimeoutSeconds 不会自动归档；它只会停止运行。会话会保留到自动归档。
• 自动归档同样适用于深度 1 和深度 2 的会话。
• 浏览器清理独立于归档清理：运行结束时，会尽力关闭被跟踪的浏览器标签页/进程，即使转录记录/会话记录被保留。

嵌套子智能体

默认情况下，子智能体不能生成自己的子智能体 （maxSpawnDepth: 1）。设置 maxSpawnDepth: 2 可启用一级嵌套，即编排器模式：主智能体 → 编排器子智能体 → 工作子-子智能体。

{  agents: {    defaults: {      subagents: {        maxSpawnDepth: 2, // allow sub-agents to spawn children (default: 1)        maxChildrenPerAgent: 5, // max active children per agent session (default: 5)        maxConcurrent: 8, // global concurrency lane cap (default: 8)        runTimeoutSeconds: 900, // default timeout for sessions_spawn when omitted (0 = no timeout)        announceTimeoutMs: 120000, // per-call gateway announce timeout      },    },  },}

深度级别

公告链

结果会沿链路向上返回：

1. 深度 2 工作项完成 → 向其父项（深度 1 编排器）公告。
2. 深度 1 编排器收到公告，合成结果并完成 → 向主智能体公告。
3. 主智能体收到公告并投递给用户。

每一级只能看到来自其直接子项的公告。

按深度划分的工具策略

• 角色和控制范围会在生成时写入会话元数据。这可以避免扁平化或恢复后的会话键意外重新获得编排器权限。
• **深度 1（编排器，当 maxSpawnDepth >= 2 时）：**获得 sessions_spawn、subagents、sessions_list、sessions_history，以便管理它的子会话。其他会话/系统工具仍被拒绝。
• **深度 1（叶节点，当 maxSpawnDepth == 1 时）：**没有会话工具（当前默认行为）。
• **深度 2（叶工作器）：**没有会话工具，sessions_spawn 在深度 2 始终被拒绝。不能再生成更多子会话。

每个智能体的生成限制

每个智能体会话（任意深度）同一时间最多可以有 maxChildrenPerAgent（默认 5）个活跃子会话。这可以防止单个编排器失控式扇出。

级联停止

停止深度 1 编排器会自动停止其所有深度 2 子会话：

• 主聊天中的 /stop 会停止所有深度 1 智能体，并级联停止它们的深度 2 子会话。
• /subagents kill <id> 会停止特定子智能体，并级联停止它的子会话。
• /subagents kill all 会停止请求者的所有子智能体，并执行级联停止。

身份验证

子智能体身份验证按 智能体 ID 解析，而不是按会话类型解析：

• 子智能体会话键是 agent:<agentId>:subagent:<uuid>。
• 身份验证存储从该智能体的 agentDir 加载。
• 主智能体的身份验证配置会作为后备合并进来；发生冲突时，智能体配置会覆盖主配置。

合并是增量式的，因此主配置始终可作为后备使用。尚不支持每个智能体完全隔离的身份验证。

公告

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

• 公告步骤在子智能体会话内部运行（不是请求者会话）。
• 如果子智能体精确回复 ANNOUNCE_SKIP，则不会发布任何内容。
• 如果最新助手文本是精确的静默令牌 NO_REPLY / no_reply，即使之前存在可见进度，也会抑制公告输出。

投递取决于请求者深度：

• 顶层请求者会话使用带外部投递的后续 agent 调用（deliver=true）。
• 嵌套请求者子智能体会话会收到内部后续注入（deliver=false），这样编排器可以在会话内合成子结果。
• 如果嵌套请求者子智能体会话已不存在，OpenClaw 会在可用时回退到该会话的请求者。

对于顶层请求者会话，完成模式的直接投递会先解析任何已绑定的对话/线程路由和钩子覆盖，然后从请求者会话存储的路由中填补缺失的渠道目标字段。这样即使完成来源只标识渠道，完成结果也会保持在正确的聊天/主题上。

构建嵌套完成发现时，子完成聚合会限定在当前请求者运行范围内，防止旧的先前运行子输出泄漏到当前公告中。当渠道适配器上可用时，公告回复会保留线程/主题路由。

公告上下文

公告上下文会规范化为稳定的内部事件块：

终止失败的运行会报告失败 Status，而不会重放捕获的回复文本。超时时，如果子会话只执行到工具调用，公告可以将该历史折叠为简短的部分进度摘要，而不是重放原始工具输出。

统计行

公告载荷末尾会包含统计行（即使被包装）：

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

内部元数据仅用于编排；面向用户的回复应改写为正常的助手语气。

为什么优先使用 sessions_history

sessions_history 是更安全的编排路径：

• 助手回忆会先被规范化：移除思考标签；移除 <relevant-memories> / <relevant_memories> 脚手架；移除纯文本工具调用 XML 载荷块（<tool_call>、<function_call>、<tool_calls>、<function_calls>），包括从未干净闭合的截断载荷；移除降级的工具调用/结果脚手架和历史上下文标记；移除泄漏的模型控制令牌（<|assistant|>、其他 ASCII <|...|>、全角 <｜...｜>）；移除畸形的 MiniMax 工具调用 XML。
• 类似凭据/token 的文本会被打码。
• 长块可以被截断。
• 极大的历史可以丢弃较旧行，或用 [sessions_history omitted: message too large] 替换过大的行。
• 当你需要完整的逐字节转录时，原始磁盘转录检查是后备方案。

工具策略

子智能体首先使用与父智能体或目标智能体相同的配置文件和工具策略管线。之后，OpenClaw 会应用子智能体限制层。

在没有限制性 tools.profile 的情况下，子智能体会获得除会话工具和系统工具之外的所有工具：

• sessions_list
• sessions_history
• sessions_send
• sessions_spawn

sessions_history 在这里仍然是有界且经过清理的回忆视图，并非原始转录转储。

当 maxSpawnDepth >= 2 时，深度 1 编排器子智能体还会收到 sessions_spawn、subagents、sessions_list 和 sessions_history，以便管理它们的子会话。

通过配置覆盖

{  agents: {    defaults: {      subagents: {        maxConcurrent: 1,      },    },  },  tools: {    subagents: {      tools: {        // deny wins        deny: ["gateway", "cron"],        // if allow is set, it becomes allow-only (deny still wins)        // allow: ["read", "exec", "process"]      },    },  },}

tools.subagents.tools.allow 是最终的仅允许过滤器。它可以收窄已经解析出的工具集，但不能加回被 tools.profile 移除的工具。例如，tools.profile: "coding" 包含 web_search/web_fetch，但不包含 browser 工具。要让 coding-profile 子智能体使用浏览器自动化，请在配置文件阶段添加 browser：

{  tools: {    profile: "coding",    alsoAllow: ["browser"],  },}

当只有一个智能体应获得浏览器自动化时，使用逐智能体的 agents.list[].tools.alsoAllow: ["browser"]。

并发

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

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

存活性与恢复

OpenClaw 不会将缺少 endedAt 视为子智能体仍然存活的永久证明。超过陈旧运行窗口的未结束运行，在 /subagents list、Status 摘要、后代完成门控和逐会话并发检查中不再计为活跃/待处理。

Gateway 网关重启后，陈旧的未结束恢复运行会被剪除，除非其子会话被标记为 abortedLastRun: true。这些因重启中止的子会话仍可通过子智能体孤儿恢复流程恢复，该流程会在清除中止标记前发送一条合成恢复消息。

自动重启恢复按每个子会话设有边界。如果同一个子智能体子会话在快速重新卡住窗口内反复被接受进行孤儿恢复，OpenClaw 会在该会话上持久化一个恢复墓碑，并在后续重启时停止自动恢复它。运行 openclaw tasks maintenance --apply 来协调任务记录，或运行 openclaw doctor --fix 来清除带墓碑会话上的陈旧中止恢复标志。

停止

• 在请求者聊天中发送 /stop 会中止请求者会话，并停止从它生成的所有活跃子智能体运行，同时级联到嵌套子会话。
• /subagents kill <id> 会停止特定子智能体，并级联停止它的子会话。

限制

• 子智能体公告是尽力而为的。如果 Gateway 网关重启，待处理的“公告回传”工作会丢失。
• 子智能体仍共享同一个 Gateway 网关进程资源；请将 maxConcurrent 视为安全阀。
• sessions_spawn 始终是非阻塞的：它会立即返回 { status: "accepted", runId, childSessionKey }。
• 子智能体上下文只注入 AGENTS.md、TOOLS.md、SOUL.md、IDENTITY.md 和 USER.md（不注入 MEMORY.md、HEARTBEAT.md 或 BOOTSTRAP.md）。
• 最大嵌套深度是 5（maxSpawnDepth 范围：1–5）。大多数用例推荐深度 2。
• maxChildrenPerAgent 限制每个会话的活跃子会话数量（默认 5，范围 1–20）。

相关

• ACP Agents
• Agent send
• 后台任务
• 多 Agent 沙盒工具