子智能体

子智能体是从现有智能体运行中派生的后台智能体运行。 每个子智能体都在自己的会话（agent:<agentId>:subagent:<uuid>）中运行，并在完成后将结果通知回请求方的聊天渠道。 每个子智能体运行都会作为后台任务进行跟踪。

目标：

• 并行执行研究、长时间任务和缓慢的工具工作，而不阻塞主运行。
• 默认保持子智能体相互隔离（会话分离，可选沙箱隔离）。
• 降低工具面的误用风险：默认情况下，子智能体不会获得会话或消息工具。
• 支持可配置的嵌套深度，以适应编排器模式。

斜杠命令

/subagents 可检查当前会话的子智能体运行：

/subagents list/subagents log <id|#> [limit] [tools]/subagents info <id|#>

/subagents info 显示运行元数据（状态、时间戳、会话 ID、记录路径、清理）。/subagents log 输出某次运行最近的聊天轮次；添加 tools token 可包含工具调用/结果消息（默认省略）。在智能体轮次中，使用 sessions_history 获取有边界且经过安全过滤的回溯视图，或检查磁盘上的记录路径以查看原始完整记录。

在 Control UI 中，近期运行过子智能体的父会话会显示一个可展开的侧边栏行。嵌套行会显示子智能体的状态和运行时长；选择其中一项会打开该子智能体的聊天，同时保留父级层次结构。

话题串绑定控件

这些命令适用于具有持久话题串绑定的渠道。请参阅下方的支持话题串的渠道。

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

派生行为

智能体使用 sessions_spawn 工具启动后台子智能体。 完成结果会作为父会话内部事件返回；父智能体/请求方智能体会决定是否需要面向用户更新。

上下文模式

除非调用方明确要求派生当前记录，否则原生子智能体启动时相互隔离。

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

工具：sessions_spawn

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

是否可用取决于调用方的有效工具策略。内置 coding 和 messaging 配置文件包含 sessions_spawn、sessions_yield 和 subagents；minimal 不包含这些工具。full 允许所有工具。对于使用自定义、更窄配置文件但仍需委派工作的智能体，请通过 tools.alsoAllow 添加这些工具，或使用上述配置文件之一。 在配置文件阶段之后，渠道/群组、提供商、沙箱及按智能体设置的允许/拒绝策略仍可能移除该工具。使用同一会话中的 /tools 确认有效工具列表。

默认值：

• **模型：**除非设置 agents.defaults.subagents.model（或按智能体设置 agents.entries.*.subagents.model），否则原生子智能体会继承调用方的模型。存在已配置的子智能体模型时，ACP 运行时派生也会使用相同模型；否则，ACP harness 会保留自己的默认模型。显式设置的 sessions_spawn.model 仍具有最高优先级。
• **思考：**除非设置 agents.defaults.subagents.thinking（或按智能体设置 agents.entries.*.subagents.thinking），否则原生子智能体会继承调用方的设置。ACP 运行时派生也会为所选模型应用 agents.defaults.models["provider/model"].params.thinking。显式设置的 sessions_spawn.thinking 仍具有最高优先级。
• **运行超时：**设置后，OpenClaw 使用 agents.defaults.subagents.runTimeoutSeconds；否则回退到 0（无超时）。sessions_spawn 不接受按调用设置的超时覆盖。
• **进程生命周期：**分离的 OpenClaw 子智能体拥有自己的运行生命周期。在外部 CLI 后端中创建的后台任务则有所不同：它会与父 CLI 子进程共享生命周期，并在父进程达到 agents.defaults.timeoutSeconds 时停止。
• **任务交付：**原生子智能体通过其第一条可见的 [Subagent Task] 消息接收委派任务。子智能体系统提示词包含运行时规则和路由上下文，不包含任务的隐藏副本。

已接受的原生子智能体派生会在工具结果中包含已解析的子智能体模型元数据：resolvedModel 包含已应用的模型引用；如果该引用带有提供商前缀，resolvedProvider 会包含该前缀。

委派提示模式

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

• suggest（默认）：保留标准提示，建议对规模较大或耗时较长的工作使用子智能体。
• prefer：要求主智能体保持响应，并通过 sessions_spawn 委派任何比直接回复更复杂的工作。

按智能体覆盖：agents.entries.*.subagents.delegationMode。

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

工具参数

支持 visible: true、model、cwd 和同智能体的 context: "fork"。沙箱隔离的目标会将 cwd 限制在该智能体的工作区内。此路径不支持线程绑定、mode、思考覆盖、lightContext、attachments 和 attachAs，因为可见会话是通过 sessions.create 创建的持久仪表板会话。如果请求方本身是使用继承的工具允许列表或拒绝列表生成的，则会拒绝可见生成；此限制在生成时固定，无法通过配置覆盖。会话列表和寻址遵循 tools.sessions.visibility；默认的 tree 范围涵盖当前会话及其自己的生成子树。有关检出命名、设置、清理和恢复行为，请参阅托管工作树。

任务名称和目标定位

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

列出由请求方会话树拥有的已生成子智能体运行和后台任务记录。 任务行涵盖原生子智能体、ACP 运行、 Gateway CLI/媒体工作和定时任务执行。其范围限于当前 请求方；子项只能查看自己控制的子项。

使用 subagents 进行按需状态检查和调试。使用 sessions_yield 等待完成事件。

使用 action: "cancel" 和 action: "list" 返回的 taskId 来停止 任务。取消操作仅限于受控会话树；叶级 子智能体无法取消其他会话拥有的工作。

线程绑定会话

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

支持线程的渠道

当渠道注册了对话 绑定适配器时，它就支持持久的线程绑定子智能体会话 （sessions_spawn 与 thread: true）。支持此功能的内置渠道：Discord、 iMessage、Matrix 和 Telegram。Discord 和 Matrix 默认 创建子线程；Telegram 和 iMessage 默认绑定 当前对话。使用各渠道的 threadBindings 配置键设置 启用状态、超时和 spawnSessions。

快速流程

手动控制

配置开关

• 全局默认值： session.threadBindings.enabled、session.threadBindings.idleHours、session.threadBindings.maxAgeHours。
• 渠道覆盖和生成时自动绑定键取决于适配器。请参阅上文的支持线程的渠道。

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

允许列表

如果请求方会话已进行沙箱隔离，sessions_spawn 会拒绝将以 非沙箱隔离方式运行的目标。

设备发现

使用 agents_list 查看当前允许用于 sessions_spawn 的 Agent ID。响应包含列出的每个 Agent 的实际生效 模型和嵌入式运行时元数据，以便调用方区分 OpenClaw、Codex app-server 和其他已配置的原生运行时。

allowAgents 条目必须指向 agents.entries.* 中已配置的 Agent ID。 ["*"] 表示任意已配置的目标 Agent 加上请求方。如果删除了某个 Agent 配置， 但其 ID 仍保留在 allowAgents 中，sessions_spawn 会拒绝该 ID， 而 agents_list 会将其省略。运行 openclaw doctor --fix 以清理过期的 允许列表条目；如果目标应在继承默认值的同时保持可生成，则添加最小化的 agents.entries.* 条目。

自动归档

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

嵌套子智能体

默认情况下，子智能体无法生成自己的子智能体 （maxSpawnDepth: 1）。将 maxSpawnDepth: 2 设为启用一层 嵌套，即编排器模式：主智能体 → 编排器子智能体 → 工作子智能体。

{  agents: {    defaults: {      subagents: {        maxSpawnDepth: 2, // 允许子智能体生成子级（默认值：1，范围 1-5）        maxChildrenPerAgent: 5, // 每个智能体会话的最大活跃子级数（默认值：5，范围 1-20）        maxConcurrent: 8, // 全局并发通道上限（默认值：8）        runTimeoutSeconds: 900, // sessions_spawn 的默认超时时间（0 = 不超时）        announceTimeoutMs: 120000, // 每次调用的 Gateway 网关通知超时时间      },    },  },}

深度级别

通知链

结果沿链向上返回：

1. 深度为 2 的工作单元完成 → 通知其父级（深度为 1 的编排器）。
2. 深度为 1 的编排器收到通知、综合结果并完成 → 通知主智能体。
3. 主智能体收到通知并将结果交付给用户。

每一级只能看到来自其直接子级的通知。

按深度划分的工具策略

• 子级生成时会捕获请求方当时实际生效的发送方策略。即使 toolsBySender 随后发生变化，无发送方的子级运行和经过身份验证的操作员恢复操作仍会保留该快照；当前的全局、Agent、提供商、沙箱和子智能体限制仍然适用。如果新的外部渠道轮次以该子级为目标，则会改为重新解析当前发送方策略。
• 角色和控制范围会在生成时写入会话元数据。这样可防止扁平化或恢复后的会话键意外重新获得编排器权限。
• **深度 1（当 maxSpawnDepth >= 2 时为编排器）：**获得 sessions_spawn、subagents、sessions_list、sessions_history，以便生成子级并检查其状态。其他会话/系统工具仍被拒绝。
• **深度 1（当 maxSpawnDepth == 1 时为叶级）：**没有会话工具（当前默认行为）。
• **深度 2（叶级工作单元）：**没有会话工具——在深度 2 时始终拒绝 sessions_spawn。无法继续生成子级。

每个 Agent 的生成限制

每个 Agent 会话（无论深度如何）同时最多可有 maxChildrenPerAgent 个活跃子级（默认值为 5）。这可以防止单个编排器不受控制地扇出。

级联停止

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

• 主聊天中的 /stop 会停止所有深度为 1 的 Agent，并级联停止其深度为 2 的子级。

身份验证

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

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

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

通知

子智能体通过通知步骤报告结果：

• 通知步骤在子智能体会话中运行（而不是在请求方会话中）。
• 如果子智能体的回复与 ANNOUNCE_SKIP 完全一致，则不会发布任何内容。
• 如果最新的助手文本是完全一致的静默令牌 NO_REPLY / no_reply，即使此前存在可见进度，也会抑制通知输出。

交付方式取决于请求方的深度：

• 顶层请求方会话使用后续 agent 调用进行外部交付（deliver=true）。
• 嵌套的请求方子智能体会话接收内部后续注入（deliver=false），以便编排器在会话内综合子级结果。
• 如果嵌套的请求方子智能体会话已不存在，OpenClaw 会在可用时回退到该会话的请求方。

对于顶层请求方会话，完成模式的直接交付会先 解析任何已绑定的对话/话题串路由和钩子覆盖，然后从请求方会话存储的路由中 补充缺失的渠道目标字段。 这样，即使完成事件的来源只标识了渠道，也能确保完成结果发送到正确的聊天/主题。

构建嵌套完成结果时，子级完成聚合仅限于当前请求方运行， 可防止先前运行中过期的子级输出泄漏到当前通知中。渠道适配器支持时， 通知回复会保留话题串/主题路由。

通知上下文

通知上下文会被规范化为稳定的内部事件块：

以失败告终的运行会报告失败状态，而不会重放捕获的 回复文本。工具/工具结果输出不会被提升为子级结果文本。

统计行

通知载荷末尾包含统计行（即使经过包装）：

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

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

为什么首选 sessions_history

sessions_history 是在 Agent 轮次中读取子级 记录的更安全编排路径：

• 即使通用日志脱敏功能已禁用，也会隐去类似凭据/Token 的文本。
• 截断较长的文本块（每块 4000 个字符），并丢弃思维签名、推理重放载荷和内联图像数据。
• 强制执行 80 KB 的响应上限；超大行会替换为 [sessions_history omitted: message too large]。
• 如果存在 nextOffset，使用它向后翻页查看更早的记录窗口。
• sessions_history 不会从消息文本中去除推理标签、<relevant-memories> 脚手架或工具调用 XML——它返回接近原始记录格式的结构化内容块，只进行脱敏并限制大小。/subagents log 会应用更严格的文本清理器（去除推理标签、记忆脚手架和工具调用 XML），因为它呈现的是纯聊天行，而不是结构化块。
• 当需要完整、逐字节一致的记录时，直接检查磁盘上的原始记录是后备方案。

工具策略

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

无论深度或角色如何，子智能体始终无法使用 gateway、agents_list、session_status 和 cron（系统级/交互式工具，或应由主智能体协调的 工具）。叶级子智能体（默认的深度 1 行为，以及深度 2 下的所有情况） 还无法使用 subagents、sessions_list、sessions_history 和 sessions_spawn。子智能体永远 不会获得 message 工具——它在生成时即被禁用，而不是由 此拒绝列表过滤——并且 sessions_send 始终被拒绝，因此子智能体 只能通过通知链通信。

sessions_history 在此处仍是一个有界且经过清理的回忆视图——它 不是原始记录转储。

当 maxSpawnDepth >= 2 时，深度为 1 的编排器子智能体还会 获得 sessions_spawn、subagents、sessions_list 和 sessions_history，以便管理其子级。

通过配置覆盖

{  agents: {    defaults: {      subagents: {        maxConcurrent: 1,      },    },  },  tools: {    subagents: {      tools: {        // 拒绝规则优先        deny: ["gateway", "cron"],        // 如果设置了 allow，则仅允许其中所列工具（拒绝规则仍然优先）        // allow: ["read", "exec", "process"]      },    },  },}

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

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

如果只有一个智能体应获得浏览器自动化能力，请使用按智能体配置的 agents.entries.*.tools.alsoAllow: ["browser"]。

并发

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

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

活跃性与恢复

OpenClaw 不会将缺少 endedAt 视为子智能体仍然存活的 永久证据。超过陈旧运行时间窗口仍未结束的运行 （2 小时，或配置的运行超时时间加上一小段宽限期， 取两者中较长者）将不再计入 /subagents list、 状态摘要、后代完成门控和按会话执行的 并发检查中的活动或待处理运行。

Gateway 网关重启后，会清理已恢复但陈旧且未结束的运行，除非 其子会话被标记为 abortedLastRun: true。因重启中止的 运行仍会注册在子智能体孤立运行恢复流程中：陈旧 运行会直接结束而不恢复，而较新的子会话会先收到 一条合成的恢复消息，之后才会清除中止标记。

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

停止

• 在请求方聊天中发送 /stop 会中止请求方会话，并停止由其生成的所有活动子智能体运行，此操作会级联至嵌套子智能体。

限制

• 子智能体通知是尽力而为的。如果 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）。Codex 原生子智能体遵循相同的边界：TOOLS.md 保留在继承的 Codex 线程指令中，而仅属于父级的角色设定、身份和用户文件会作为轮次范围的协作指令注入，因此子智能体不会复制它们。
• 最大嵌套深度为 5（maxSpawnDepth 范围：1-5）。对于大多数使用场景，建议使用深度 2。
• maxChildrenPerAgent 限制每个会话的活动子智能体数量（默认值为 5，范围为 1-20）。

相关内容

• 会话工具和状态变更
• ACP 智能体
• 智能体发送
• 后台任务
• 多 Agent 沙盒工具