diff --git a/docs/zh-CN/automation/tasks.md b/docs/zh-CN/automation/tasks.md
index 1ba9ad57a..6531be979 100644
--- a/docs/zh-CN/automation/tasks.md
+++ b/docs/zh-CN/automation/tasks.md
@@ -1,43 +1,43 @@
---
read_when:
- - 检查正在进行中或刚刚完成的后台工作
- - 调试已分离的智能体运行的交付失败问题
+ - 检查正在进行中或最近已完成的后台工作
+ - 调试分离式智能体运行的交付失败问题
- 了解后台运行与会话、cron 和心跳之间的关系
-summary: 用于跟踪 ACP 运行、子智能体、隔离的 cron 作业和 CLI 操作的后台任务
+summary: ACP 运行、子智能体、隔离的 cron 作业和 CLI 操作的后台任务跟踪
title: 后台任务
x-i18n:
- generated_at: "2026-04-20T18:24:53Z"
+ generated_at: "2026-04-21T19:01:00Z"
model: gpt-5.4
provider: openai
- source_hash: ba5511b1c421bdf505fc7d34f09e453ac44e85213fcb0f082078fa957aa91fe7
+ source_hash: a4cd666b3eaffde8df0b5e1533eb337e44a0824824af6f8a240f18a89f71b402
source_path: automation/tasks.md
workflow: 15
---
# 后台任务
-> **在找调度功能?** 请参阅 [Automation & Tasks](/zh-CN/automation) 以选择合适的机制。本页介绍的是如何**跟踪**后台工作,而不是如何调度它。
+> **在找调度功能?** 请参阅 [Automation & Tasks](/zh-CN/automation),以选择合适的机制。本页介绍的是如何**跟踪**后台工作,而不是如何调度它。
后台任务用于跟踪**在你的主会话之外**运行的工作:
-ACP 运行、子智能体生成、隔离的 cron 作业执行,以及由 CLI 发起的操作。
+ACP 运行、子智能体派生、隔离的 cron 作业执行,以及由 CLI 发起的操作。
-任务**不会**替代会话、cron 作业或心跳——它们是记录已分离工作发生了什么、何时发生以及是否成功的**活动账本**。
+任务**不会**替代会话、cron 作业或心跳——它们是记录这些分离式工作“发生了什么、何时发生、以及是否成功”的**活动台账**。
-并非每次智能体运行都会创建任务。心跳轮次和普通交互式聊天不会。所有 cron 执行、ACP 生成、子智能体生成和 CLI 智能体命令都会。
+并非每次智能体运行都会创建任务。心跳轮次和普通交互式聊天不会。所有 cron 执行、ACP 派生、子智能体派生以及 CLI 智能体命令都会创建任务。
## TL;DR
-- 任务是**记录**,不是调度器——cron 和心跳决定工作_何时_运行,任务跟踪_发生了什么_。
+- 任务是**记录**,不是调度器——cron 和心跳决定工作**何时**运行,任务跟踪**发生了什么**。
- ACP、子智能体、所有 cron 作业和 CLI 操作都会创建任务。心跳轮次不会。
- 每个任务都会经历 `queued → running → terminal`(succeeded、failed、timed_out、cancelled 或 lost)。
-- 只要 cron 运行时仍拥有该作业,cron 任务就会保持活动状态;基于聊天的 CLI 任务仅在其所属运行上下文仍然活跃时保持活动状态。
-- 完成采用推送驱动:已分离工作完成时可以直接通知,或唤醒请求方会话/心跳,因此状态轮询循环通常不是正确方式。
-- 隔离的 cron 运行和子智能体完成时,会尽力在最终清理记账前清理其子会话所跟踪的浏览器标签页/进程。
-- 隔离的 cron 交付会在后代子智能体工作仍在收尾时抑制过期的中间父级回复,并在后代最终输出先于交付到达时优先使用它。
-- 完成通知会直接投递到某个渠道,或排队等待下一次心跳。
-- `openclaw tasks list` 显示所有任务;`openclaw tasks audit` 会暴露问题。
+- 只要 cron 运行时仍然拥有该作业,cron 任务就会保持活动状态;而由聊天支持的 CLI 任务只有在其所属运行上下文仍处于活动状态时才会保持活动状态。
+- 完成采用推送驱动:分离式工作完成后可以直接通知,或唤醒请求方会话/心跳,因此状态轮询循环通常不是合适的模式。
+- 隔离的 cron 运行和子智能体完成时,会尽力在最终清理记账前,为其子会话清理已跟踪的浏览器标签页/进程。
+- 隔离的 cron 交付会在后代子智能体工作仍在收尾时抑制过时的父级中间回复,并在后代最终输出先于交付到达时优先使用该最终输出。
+- 完成通知会直接发送到渠道,或排队等待下一次心跳。
+- `openclaw tasks list` 显示所有任务;`openclaw tasks audit` 用于发现问题。
- 终态记录会保留 7 天,之后自动清理。
## 快速开始
@@ -46,7 +46,7 @@ ACP 运行、子智能体生成、隔离的 cron 作业执行,以及由 CLI
# 列出所有任务(最新的在前)
openclaw tasks list
-# 按运行时或状态过滤
+# 按运行时或状态筛选
openclaw tasks list --runtime acp
openclaw tasks list --status running
@@ -76,23 +76,23 @@ openclaw tasks flow cancel
| 来源 | 运行时类型 | 何时创建任务记录 | 默认通知策略 |
| ---------------------- | ------------ | ------------------------------------------------------ | --------------------- |
-| ACP 后台运行 | `acp` | 生成子 ACP 会话时 | `done_only` |
-| 子智能体编排 | `subagent` | 通过 `sessions_spawn` 生成子智能体时 | `done_only` |
-| cron 作业(所有类型) | `cron` | 每次 cron 执行时(主会话和隔离执行均包括) | `silent` |
+| ACP 后台运行 | `acp` | 派生 ACP 子会话时 | `done_only` |
+| 子智能体编排 | `subagent` | 通过 `sessions_spawn` 派生子智能体时 | `done_only` |
+| cron 作业(所有类型) | `cron` | 每次 cron 执行时(主会话和隔离式均包括) | `silent` |
| CLI 操作 | `cli` | 通过 Gateway 网关运行的 `openclaw agent` 命令 | `silent` |
-| 智能体媒体作业 | `cli` | 基于会话的 `video_generate` 运行 | `silent` |
+| 智能体媒体作业 | `cli` | 由会话支持的 `video_generate` 运行 | `silent` |
-主会话 cron 任务默认使用 `silent` 通知策略——它们会创建用于跟踪的记录,但不会生成通知。隔离的 cron 任务默认也为 `silent`,但由于它们在自己的会话中运行,因此更容易被看到。
+主会话 cron 任务默认使用 `silent` 通知策略——它们会创建记录以供跟踪,但不会生成通知。隔离的 cron 任务同样默认使用 `silent`,但由于它们在自己的会话中运行,因此更容易被看到。
-基于会话的 `video_generate` 运行同样使用 `silent` 通知策略。它们仍会创建任务记录,但完成结果会作为内部唤醒交还给原始智能体会话,以便智能体自己编写后续消息并附上生成完成的视频。如果你启用了 `tools.media.asyncCompletion.directSend`,异步 `music_generate` 和 `video_generate` 完成时会先尝试直接向渠道投递,失败后再回退到唤醒请求方会话的路径。
+由会话支持的 `video_generate` 运行也使用 `silent` 通知策略。它们仍会创建任务记录,但完成结果会通过内部唤醒返还给原始智能体会话,以便智能体自行写入后续消息并附加已完成的视频。如果你启用了 `tools.media.asyncCompletion.directSend`,异步 `music_generate` 和 `video_generate` 完成时会先尝试直接发送到渠道,失败后再回退到唤醒请求方会话的路径。
-当某个基于会话的 `video_generate` 任务仍在活动时,该工具还会充当一道保护措施:在同一会话中重复调用 `video_generate` 会返回活动任务状态,而不是启动第二个并发生成任务。当你希望从智能体侧显式查询进度/状态时,请使用 `action: "status"`。
+当某个由会话支持的 `video_generate` 任务仍处于活动状态时,该工具也会充当护栏:在同一会话中重复调用 `video_generate` 时,不会启动第二个并发生成,而是返回当前活动任务的状态。当你希望从智能体侧显式查询进度/状态时,请使用 `action: "status"`。
-**不会创建任务的情况:**
+**以下情况不会创建任务:**
- 心跳轮次——主会话;请参阅 [Heartbeat](/zh-CN/gateway/heartbeat)
- 普通交互式聊天轮次
-- 直接 `/command` 响应
+- 直接的 `/command` 响应
## 任务生命周期
@@ -111,47 +111,47 @@ stateDiagram-v2
| 状态 | 含义 |
| ----------- | -------------------------------------------------------------------------- |
| `queued` | 已创建,等待智能体启动 |
-| `running` | 智能体轮次正在积极执行 |
+| `running` | 智能体轮次正在执行 |
| `succeeded` | 已成功完成 |
-| `failed` | 因错误而结束 |
-| `timed_out` | 超出配置的超时时间 |
-| `cancelled` | 由操作员通过 `openclaw tasks cancel` 停止 |
-| `lost` | 在 5 分钟宽限期后,运行时丢失了权威的后备状态 |
+| `failed` | 以错误结束 |
+| `timed_out` | 超过配置的超时时间 |
+| `cancelled` | 操作员通过 `openclaw tasks cancel` 停止 |
+| `lost` | 运行时在 5 分钟宽限期后失去了权威性支撑状态 |
-状态转换会自动发生——当关联的智能体运行结束时,任务状态会更新为匹配的结果。
+状态转换会自动发生——当关联的智能体运行结束时,任务状态会更新为对应结果。
-`lost` 是运行时感知的:
+`lost` 具备运行时感知能力:
-- ACP 任务:后备 ACP 子会话元数据消失。
-- 子智能体任务:后备子会话从目标智能体存储中消失。
-- cron 任务:cron 运行时不再将该作业视为活动状态。
-- CLI 任务:隔离的子会话任务使用子会话;基于聊天的 CLI 任务则改为使用活动运行上下文,因此残留的渠道/群组/直接会话行不会让它们继续保持活动。
+- ACP 任务:支撑它的 ACP 子会话元数据已消失。
+- 子智能体任务:支撑它的子会话已从目标智能体存储中消失。
+- cron 任务:cron 运行时不再将该作业标记为活动状态。
+- CLI 任务:隔离子会话任务使用子会话;由聊天支持的 CLI 任务则改为使用实时运行上下文,因此残留的渠道/群组/私聊会话行不会让它们继续保持活动状态。
## 交付与通知
-当任务进入终态时,OpenClaw 会通知你。有两种交付路径:
+当任务进入终态时,OpenClaw 会通知你。存在两种交付路径:
-**直接交付**——如果任务有渠道目标(`requesterOrigin`),完成消息会直接发送到该渠道(Telegram、Discord、Slack 等)。对于子智能体完成,OpenClaw 还会在可用时保留已绑定的线程/话题路由,并可在直接交付前尝试从请求方会话的存储路由(`lastChannel` / `lastTo` / `lastAccountId`)中补全缺失的 `to` / account。
+**直接交付**——如果任务具有渠道目标(`requesterOrigin`),完成消息会直接发送到该渠道(Telegram、Discord、Slack 等)。对于子智能体完成,OpenClaw 还会在可用时保留已绑定的线程/话题路由,并可在直接交付前,从请求方会话存储的路由(`lastChannel` / `lastTo` / `lastAccountId`)中补全缺失的 `to` / account。
-**会话排队交付**——如果直接交付失败,或未设置来源,则更新会作为系统事件排入请求方会话,并在下一次心跳时呈现。
+**会话排队交付**——如果直接交付失败或未设置来源,更新将作为系统事件排入请求方会话,并在下一次心跳时呈现。
-任务完成会立即触发一次心跳唤醒,因此你可以快速看到结果——无需等到下一次计划中的心跳 tick。
+任务完成会立即触发一次心跳唤醒,因此你可以快速看到结果——不必等待下一次计划中的心跳触发。
-这意味着常见工作流是基于推送的:只需启动一次已分离工作,然后让运行时在完成时唤醒或通知你。只有在你需要调试、干预或进行显式审计时,才去轮询任务状态。
+这意味着常见工作流是基于推送的:只需启动一次分离式工作,然后让运行时在完成时唤醒你或通知你。只有在你需要调试、干预或执行显式审计时,才需要轮询任务状态。
### 通知策略
-控制你会收到多少关于每个任务的信息:
+控制你希望收到每个任务多少信息:
| 策略 | 交付内容 |
| --------------------- | ----------------------------------------------------------------------- |
-| `done_only`(默认) | 仅终态(succeeded、failed 等)——**这就是默认值** |
+| `done_only`(默认) | 仅终态(succeeded、failed 等)——**这是默认值** |
| `state_changes` | 每次状态转换和进度更新 |
| `silent` | 完全不通知 |
-在任务运行期间更改策略:
+可在任务运行期间更改策略:
```bash
openclaw tasks notify state_changes
@@ -173,7 +173,7 @@ openclaw tasks list [--runtime ] [--status ] [--j
openclaw tasks show
```
-查找令牌接受任务 ID、运行 ID 或会话键。显示完整记录,包括时间、交付状态、错误和终态摘要。
+查找令牌支持任务 ID、运行 ID 或会话键。会显示完整记录,包括时间信息、交付状态、错误和终态摘要。
### `tasks cancel`
@@ -181,7 +181,7 @@ openclaw tasks show
openclaw tasks cancel
```
-对于 ACP 和子智能体任务,这会终止子会话。对于由 CLI 跟踪的任务,取消操作会记录到任务注册表中(不存在单独的子运行时句柄)。状态会转换为 `cancelled`,并在适用时发送交付通知。
+对于 ACP 和子智能体任务,这会终止子会话。对于由 CLI 跟踪的任务,取消会记录到任务注册表中(不存在单独的子运行时句柄)。状态会转换为 `cancelled`,并在适用时发送交付通知。
### `tasks notify`
@@ -195,16 +195,16 @@ openclaw tasks notify
openclaw tasks audit [--json]
```
-暴露运行问题。检测到问题时,结果也会出现在 `openclaw status` 中。
+用于发现运维问题。检测到问题时,这些发现也会出现在 `openclaw status` 中。
| 发现项 | 严重级别 | 触发条件 |
| ------------------------- | -------- | ----------------------------------------------------- |
-| `stale_queued` | warn | 排队超过 10 分钟 |
-| `stale_running` | error | 运行超过 30 分钟 |
-| `lost` | error | 运行时支撑的任务归属已消失 |
+| `stale_queued` | warn | 处于 queued 超过 10 分钟 |
+| `stale_running` | error | 处于 running 超过 30 分钟 |
+| `lost` | error | 由运行时支撑的任务所有权已消失 |
| `delivery_failed` | warn | 交付失败且通知策略不是 `silent` |
| `missing_cleanup` | warn | 终态任务没有清理时间戳 |
-| `inconsistent_timestamps` | warn | 时间线冲突(例如结束时间早于开始时间) |
+| `inconsistent_timestamps` | warn | 时间线违反约束(例如结束时间早于开始时间) |
### `tasks maintenance`
@@ -213,20 +213,20 @@ openclaw tasks maintenance [--json]
openclaw tasks maintenance --apply [--json]
```
-使用它来预览或应用针对任务和 Task Flow 状态的对账、清理标记和修剪。
+用它来预览或应用任务及 Task Flow 状态的对账、清理时间戳补写和清理裁剪。
-对账是运行时感知的:
+对账具备运行时感知能力:
-- ACP/子智能体任务会检查其后备子会话。
+- ACP/子智能体任务会检查其支撑的子会话。
- cron 任务会检查 cron 运行时是否仍拥有该作业。
-- 基于聊天的 CLI 任务会检查所属的活动运行上下文,而不只是聊天会话行。
+- 由聊天支持的 CLI 任务会检查所属的实时运行上下文,而不只是聊天会话行。
-完成清理同样是运行时感知的:
+完成清理同样具备运行时感知能力:
-- 子智能体完成时,会尽力在宣布清理继续之前关闭该子会话所跟踪的浏览器标签页/进程。
-- 隔离的 cron 完成时,会尽力在该运行彻底拆除前关闭该 cron 会话所跟踪的浏览器标签页/进程。
-- 隔离的 cron 交付会在需要时等待后代子智能体的后续工作完成,并抑制过期的父级确认文本,而不是直接宣布它。
-- 子智能体完成交付会优先使用最新的可见 assistant 文本;如果为空,则回退到已净化的最新 tool/toolResult 文本,而仅包含超时工具调用的运行可收缩为简短的部分进度摘要。
+- 子智能体完成时,会尽力先关闭该子会话已跟踪的浏览器标签页/进程,然后再继续公告清理。
+- 隔离的 cron 完成时,会尽力先关闭该 cron 会话已跟踪的浏览器标签页/进程,然后再让该运行完全结束。
+- 隔离的 cron 交付会在需要时等待后代子智能体后续处理完成,并抑制过时的父级确认文本,而不是将其作为结果公告。
+- 子智能体完成交付会优先使用最新的可见助手文本;如果该文本为空,则回退到经清理的最新 tool/toolResult 文本;仅包含超时工具调用的运行可折叠为简短的部分进度摘要。终态失败的运行会公告失败状态,而不会重放已捕获的回复文本。
- 清理失败不会掩盖真实的任务结果。
### `tasks flow list|show|cancel`
@@ -237,19 +237,20 @@ openclaw tasks flow show [--json]
openclaw tasks flow cancel
```
-当你关心的是编排中的 Task Flow,而不是某一条单独的后台任务记录时,请使用这些命令。
+当你关心的是编排中的 Task Flow,而不是单个后台任务记录时,请使用这些命令。
-## 聊天任务看板(`/tasks`)
+## 聊天任务面板(`/tasks`)
-在任何聊天会话中使用 `/tasks` 可查看链接到该会话的后台任务。看板会显示活动中和最近完成的任务,包括运行时、状态、时间,以及进度或错误详情。
+在任意聊天会话中使用 `/tasks`,可查看与该会话关联的后台任务。该面板会显示活动中和最近已完成的任务,包括运行时、状态、时间信息,以及进度或错误详情。
-当当前会话没有可见的关联任务时,`/tasks` 会回退为显示智能体本地任务计数,这样你仍能获得概览,同时不会泄露其他会话的详细信息。
+当当前会话没有可见的关联任务时,`/tasks` 会回退为显示智能体本地任务计数,
+这样你仍然可以获得概览,而不会泄露其他会话的详细信息。
-如需查看完整的操作员账本,请使用 CLI:`openclaw tasks list`。
+如需查看完整的操作员台账,请使用 CLI:`openclaw tasks list`。
## 状态集成(任务压力)
-`openclaw status` 包含一个可快速浏览的任务摘要:
+`openclaw status` 包含一个可快速查看的任务摘要:
```
Tasks: 3 queued · 2 running · 1 issues
@@ -257,57 +258,57 @@ Tasks: 3 queued · 2 running · 1 issues
该摘要报告:
-- **active** — `queued` + `running` 的数量
-- **failures** — `failed` + `timed_out` + `lost` 的数量
-- **byRuntime** — 按 `acp`、`subagent`、`cron`、`cli` 分类的明细
+- **active** —— `queued` + `running` 的数量
+- **failures** —— `failed` + `timed_out` + `lost` 的数量
+- **byRuntime** —— 按 `acp`、`subagent`、`cron`、`cli` 的细分统计
-`/status` 和 `session_status` 工具都使用具备清理感知能力的任务快照:优先显示活动任务,隐藏陈旧的已完成记录,且仅在没有活动工作残留时才显示最近失败项。这让状态卡片聚焦于当前真正重要的内容。
+`/status` 和 `session_status` 工具都会使用带清理感知的任务快照:优先显示活动任务,隐藏陈旧的已完成记录,并且仅在没有活动工作剩余时才显示最近失败的任务。这样可以让状态卡聚焦于当前真正重要的内容。
## 存储与维护
### 任务存储位置
-任务记录会持久化到 SQLite,位置如下:
+任务记录持久化保存在以下 SQLite 路径中:
```
$OPENCLAW_STATE_DIR/tasks/runs.sqlite
```
-注册表会在 Gateway 网关启动时加载到内存中,并将写入同步到 SQLite,以确保重启后仍具备持久性。
+注册表会在 Gateway 网关启动时加载到内存中,并将写入同步到 SQLite,以便在重启后仍能保持持久性。
### 自动维护
-清理器每 **60 秒** 运行一次,并处理三件事:
+清扫器每 **60 秒** 运行一次,处理以下三件事:
-1. **对账** — 检查活动任务是否仍有权威运行时后备状态。ACP/子智能体任务使用子会话状态,cron 任务使用活动作业归属状态,基于聊天的 CLI 任务使用其所属运行上下文。如果该后备状态消失超过 5 分钟,任务会被标记为 `lost`。
-2. **清理标记** — 为终态任务设置 `cleanupAfter` 时间戳(`endedAt + 7 days`)。
-3. **修剪** — 删除超过其 `cleanupAfter` 日期的记录。
+1. **对账** —— 检查活动任务是否仍有权威性的运行时支撑。ACP/子智能体任务使用子会话状态,cron 任务使用活动作业所有权,由聊天支持的 CLI 任务使用所属运行上下文。如果该支撑状态消失超过 5 分钟,任务会被标记为 `lost`。
+2. **清理时间戳补写** —— 为终态任务设置 `cleanupAfter` 时间戳(`endedAt + 7 days`)。
+3. **裁剪** —— 删除超过其 `cleanupAfter` 日期的记录。
-**保留期**:终态任务记录会保留 **7 天**,之后自动修剪。无需任何配置。
+**保留期**:终态任务记录会保留 **7 天**,之后自动清理。无需配置。
## 任务与其他系统的关系
### 任务与 Task Flow
-[Task Flow](/zh-CN/automation/taskflow) 是位于后台任务之上的流程编排层。单个 flow 在其生命周期内可能通过托管或镜像同步模式协调多个任务。使用 `openclaw tasks` 检查单个任务记录,使用 `openclaw tasks flow` 检查编排 flow。
+[Task Flow](/zh-CN/automation/taskflow) 是位于后台任务之上的流程编排层。单个 flow 在其生命周期内可能通过受管或镜像同步模式协调多个任务。使用 `openclaw tasks` 检查单个任务记录,使用 `openclaw tasks flow` 检查编排中的 flow。
详情请参阅 [Task Flow](/zh-CN/automation/taskflow)。
### 任务与 cron
-cron 作业的**定义**位于 `~/.openclaw/cron/jobs.json`;运行时执行状态则位于同目录旁边的 `~/.openclaw/cron/jobs-state.json`。**每一次** cron 执行都会创建一条任务记录——无论是主会话还是隔离执行。主会话 cron 任务默认使用 `silent` 通知策略,因此它们会被跟踪,但不会生成通知。
+cron 作业**定义**保存在 `~/.openclaw/cron/jobs.json`;运行时执行状态保存在其旁边的 `~/.openclaw/cron/jobs-state.json` 中。**每一次** cron 执行都会创建一条任务记录——无论是主会话还是隔离式执行。主会话 cron 任务默认使用 `silent` 通知策略,因此它们会被跟踪,但不会生成通知。
请参阅 [Cron Jobs](/zh-CN/automation/cron-jobs)。
### 任务与心跳
-心跳运行属于主会话轮次——它们不会创建任务记录。任务完成时,它可以触发一次心跳唤醒,让你及时看到结果。
+心跳运行属于主会话轮次——它们不会创建任务记录。当任务完成时,它可以触发一次心跳唤醒,以便你及时看到结果。
请参阅 [Heartbeat](/zh-CN/gateway/heartbeat)。
### 任务与会话
-任务可能会引用 `childSessionKey`(工作运行的位置)和 `requesterSessionKey`(发起者)。会话是对话上下文;任务是在其之上的活动跟踪层。
+一个任务可能会引用 `childSessionKey`(工作运行的位置)和 `requesterSessionKey`(发起它的人)。会话是对话上下文;任务是在其之上的活动跟踪。
### 任务与智能体运行
@@ -315,8 +316,8 @@ cron 作业的**定义**位于 `~/.openclaw/cron/jobs.json`;运行时执行状
## 相关内容
-- [Automation & Tasks](/zh-CN/automation) — 一览所有自动化机制
-- [Task Flow](/zh-CN/automation/taskflow) — 位于任务之上的流程编排
-- [Scheduled Tasks](/zh-CN/automation/cron-jobs) — 调度后台工作
-- [Heartbeat](/zh-CN/gateway/heartbeat) — 周期性的主会话轮次
-- [CLI: Tasks](/cli/index#tasks) — CLI 命令参考
+- [Automation & Tasks](/zh-CN/automation) —— 所有自动化机制总览
+- [Task Flow](/zh-CN/automation/taskflow) —— 位于任务之上的流程编排
+- [Scheduled Tasks](/zh-CN/automation/cron-jobs) —— 调度后台工作
+- [Heartbeat](/zh-CN/gateway/heartbeat) —— 周期性的主会话轮次
+- [CLI: Tasks](/cli/index#tasks) —— CLI 命令参考
diff --git a/docs/zh-CN/tools/subagents.md b/docs/zh-CN/tools/subagents.md
index d6fd3e41e..3c6d00327 100644
--- a/docs/zh-CN/tools/subagents.md
+++ b/docs/zh-CN/tools/subagents.md
@@ -1,26 +1,26 @@
---
read_when:
- - 你想通过智能体进行后台/并行工作时
- - 你正在更改 `sessions_spawn` 或 sub-agent 工具策略时
- - 你正在实现或排查绑定到线程的 subagent 会话时
-summary: Sub-agents:生成隔离的智能体运行,并将结果回报到请求者聊天
-title: Sub-Agents
+ - 你希望通过智能体进行后台/并行工作
+ - 你正在更改 `sessions_spawn` 或子智能体工具策略
+ - 你正在实现或排查线程绑定的子智能体会话
+summary: 子智能体:启动隔离的智能体运行,并将结果回传到请求者聊天中
+title: 子智能体
x-i18n:
- generated_at: "2026-04-05T10:13:07Z"
+ generated_at: "2026-04-21T19:01:00Z"
model: gpt-5.4
provider: openai
- source_hash: 9df7cc35a3069ce4eb9c92a95df3ce5365a00a3fae92ff73def75461b58fec3f
+ source_hash: 218913f0db88d40e1b5fdb0201b8d23e7af23df572c86ff4be2637cb62498281
source_path: tools/subagents.md
workflow: 15
---
-# Sub-agents
+# 子智能体
-Sub-agents 是从现有智能体运行中生成的后台智能体运行。它们在自己的会话中运行(`agent::subagent:`),并在完成后**将**其结果**回报**到请求者聊天渠道。每个 sub-agent 运行都会作为一个[后台任务](/zh-CN/automation/tasks)进行跟踪。
+子智能体是从现有智能体运行中派生出来的后台智能体运行。它们在各自独立的会话中运行(`agent::subagent:`),并且在完成后,会将结果**回传**到请求者聊天渠道。每个子智能体运行都会作为一个[后台任务](/zh-CN/automation/tasks)进行跟踪。
## 斜杠命令
-使用 `/subagents` 检查或控制**当前会话**的 sub-agent 运行:
+使用 `/subagents` 来检查或控制**当前会话**的子智能体运行:
- `/subagents list`
- `/subagents kill `
@@ -40,128 +40,125 @@ Sub-agents 是从现有智能体运行中生成的后台智能体运行。它们
- `/session idle `
- `/session max-age `
-`/subagents info` 会显示运行元数据(状态、时间戳、会话 id、转录路径、清理信息)。
-使用 `sessions_history` 获取一个有界、经过安全过滤的回忆视图;当你需要原始完整转录时,
-请检查磁盘上的转录路径。
+`/subagents info` 会显示运行元数据(状态、时间戳、会话 id、转录路径、清理)。
+使用 `sessions_history` 获取有边界且经过安全过滤的回溯视图;当你需要原始完整转录时,请查看磁盘上的转录路径。
-### 生成行为
+### 启动行为
-`/subagents spawn` 会以用户命令而非内部中继的方式启动一个后台 sub-agent,并在运行完成时向请求者聊天发送一条最终完成更新。
+`/subagents spawn` 会以用户命令而不是内部中继的方式启动一个后台子智能体,并且在运行完成时,会向请求者聊天发送一条最终完成更新。
-- spawn 命令是非阻塞的;它会立即返回一个运行 id。
-- 完成时,sub-agent 会向请求者聊天渠道回报一条摘要/结果消息。
-- 完成通知是基于推送的。生成后,不要只是为了等待其完成而循环轮询 `/subagents list`、
- `sessions_list` 或 `sessions_history`;仅在按需调试或干预时检查状态。
-- 完成时,OpenClaw 会尽力关闭该 sub-agent 会话所打开并被跟踪的 browser 标签页/进程,然后再继续回报清理流程。
-- 对于手动生成,投递具备弹性:
- - OpenClaw 会先使用稳定的幂等键尝试直接 `agent` 投递。
- - 如果直接投递失败,则回退到队列路由。
- - 如果队列路由仍不可用,则会在最终放弃前以短暂的指数退避重试该回报。
-- 完成投递会保留解析后的请求者路由:
- - 如可用,则优先使用线程绑定或会话绑定的完成路由
- - 如果完成来源仅提供渠道,OpenClaw 会从请求者会话已解析的路由(`lastChannel` / `lastTo` / `lastAccountId`)中补齐缺失的目标/账号,这样直接投递仍可生效
-- 向请求者会话进行的完成交接是运行时生成的内部上下文(不是用户编写的文本),其中包括:
- - `Result`(最新可见的 `assistant` 回复文本;否则为经过净化的最新 tool/toolResult 文本)
+- 启动命令是非阻塞的;它会立即返回一个运行 id。
+- 完成时,子智能体会向请求者聊天渠道回传一条摘要/结果消息。
+- 完成通知基于推送。一旦启动,不要为了等待其完成而循环轮询 `/subagents list`、`sessions_list` 或 `sessions_history`;只有在调试或干预时才按需查看状态。
+- 完成时,OpenClaw 会尽力在回传清理流程继续之前,关闭该子智能体会话所打开并被跟踪的浏览器标签页/进程。
+- 对于手动启动,投递具有韧性:
+ - OpenClaw 会先尝试使用稳定的幂等键直接投递到 `agent`
+ - 如果直接投递失败,则回退到队列路由
+ - 如果队列路由仍不可用,则在最终放弃前,使用短时指数退避重试回传
+- 完成投递会保留已解析的请求者路由:
+ - 在线程绑定或会话绑定的完成路由可用时,优先使用它们
+ - 如果完成来源仅提供一个渠道,OpenClaw 会从请求者会话已解析的路由(`lastChannel` / `lastTo` / `lastAccountId`)中补齐缺失的 target/account,以便直接投递仍然可用
+- 向请求者会话移交完成信息时,会使用运行时生成的内部上下文(不是用户编写的文本),其中包括:
+ - `Result`(最新可见的 `assistant` 回复文本;否则为已清理的最新 `tool/toolResult` 文本;终态失败运行不会复用已捕获的回复文本)
- `Status`(`completed successfully` / `failed` / `timed out` / `unknown`)
- - 精简的运行时/token 统计信息
- - 一条投递指令,告诉请求者智能体以正常助手语气改写,而不是转发原始内部元数据
+ - 精简的运行时/令牌统计
+ - 一条投递指令,告知请求者智能体用正常的 assistant 语气重写内容(而不是转发原始内部元数据)
- `--model` 和 `--thinking` 会覆盖该次运行的默认值。
-- 使用 `info`/`log` 可在完成后检查详细信息和输出。
-- `/subagents spawn` 是一次性模式(`mode: "run"`)。对于持久的线程绑定会话,请使用带有 `thread: true` 和 `mode: "session"` 的 `sessions_spawn`。
-- 对于 ACP harness 会话(Codex、Claude Code、Gemini CLI),请使用带有 `runtime: "acp"` 的 `sessions_spawn`,并参见 [ACP Agents](/tools/acp-agents)。
+- 完成后,使用 `info`/`log` 查看详细信息和输出。
+- `/subagents spawn` 是一次性模式(`mode: "run"`)。对于持久线程绑定会话,请使用 `sessions_spawn`,并设置 `thread: true` 和 `mode: "session"`。
+- 对于 ACP harness 会话(Codex、Claude Code、Gemini CLI),请使用 `sessions_spawn` 并设置 `runtime: "acp"`,参见 [ACP Agents](/zh-CN/tools/acp-agents)。
主要目标:
-- 将“研究 / 长任务 / 慢工具”类工作并行化,而不阻塞主运行。
-- 默认保持 sub-agents 隔离(会话隔离 + 可选沙箱隔离)。
-- 让工具表面难以被误用:默认情况下,sub-agents **不会**获得会话工具。
-- 支持为编排器模式配置可嵌套深度。
+- 并行处理“研究 / 长任务 / 慢工具”类工作,而不阻塞主运行。
+- 默认保持子智能体隔离(会话隔离 + 可选沙箱隔离)。
+- 让工具表面不易被误用:默认情况下,子智能体**不会**获得会话工具。
+- 支持可配置的嵌套深度,以实现编排器模式。
-成本说明:每个 sub-agent 都有其**自己的**上下文和 token 用量。对于繁重或重复性
-任务,请为 sub-agents 设置一个更便宜的模型,并让主智能体保留较高质量模型。
-你可以通过 `agents.defaults.subagents.model` 或按智能体覆盖来配置。
+成本说明:每个子智能体都有其**自己的**上下文和令牌使用量。对于高负载或重复性任务,请为子智能体设置更便宜的模型,同时让你的主智能体保留在更高质量的模型上。
+你可以通过 `agents.defaults.subagents.model` 或按智能体覆盖来进行配置。
## 工具
使用 `sessions_spawn`:
-- 启动一个 sub-agent 运行(`deliver: false`,全局 lane:`subagent`)
-- 然后运行一个回报步骤,并将回报回复发布到请求者聊天渠道
-- 默认模型:继承调用者,除非你设置了 `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`(无超时)。
+- 启动一个子智能体运行(`deliver: false`,全局 lane:`subagent`)
+- 然后执行回传步骤,并将回传回复发布到请求者聊天渠道
+- 默认模型:继承调用方,除非你设置了 `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`(不超时)。
工具参数:
-- `task`(必需)
+- `task`(必填)
- `label?`(可选)
-- `agentId?`(可选;如果允许,则在另一个智能体 id 下生成)
-- `model?`(可选;覆盖 sub-agent 模型;无效值会被跳过,sub-agent 会使用默认模型运行,并在工具结果中附带警告)
-- `thinking?`(可选;覆盖 sub-agent 运行的 thinking 级别)
-- `runTimeoutSeconds?`(设置时默认使用 `agents.defaults.subagents.runTimeoutSeconds`,否则为 `0`;设置后,sub-agent 运行会在 N 秒后中止)
-- `thread?`(默认 `false`;为 `true` 时,会为该 sub-agent 会话请求渠道线程绑定)
+- `agentId?`(可选;如果允许,可在另一个智能体 id 下启动)
+- `model?`(可选;覆盖子智能体模型;无效值会被跳过,子智能体会使用默认模型运行,并在工具结果中给出警告)
+- `thinking?`(可选;覆盖子智能体运行的 thinking 级别)
+- `runTimeoutSeconds?`(默认在已设置时使用 `agents.defaults.subagents.runTimeoutSeconds`,否则为 `0`;设置后,子智能体运行会在 N 秒后中止)
+- `thread?`(默认 `false`;当为 `true` 时,请求为该子智能体会话启用渠道线程绑定)
- `mode?`(`run|session`)
- - 默认为 `run`
- - 如果 `thread: true` 且省略 `mode`,默认值会变为 `session`
+ - 默认是 `run`
+ - 如果 `thread: true` 且省略 `mode`,默认变为 `session`
- `mode: "session"` 要求 `thread: true`
- `cleanup?`(`delete|keep`,默认 `keep`)
-- `sandbox?`(`inherit|require`,默认 `inherit`;`require` 会在目标子运行时不是沙箱时拒绝生成)
-- `sessions_spawn` **不**接受渠道投递参数(`target`、`channel`、`to`、`threadId`、`replyTo`、`transport`)。如需投递,请在生成出的运行中使用 `message`/`sessions_send`。
+- `sandbox?`(`inherit|require`,默认 `inherit`;`require` 会在目标子运行时未启用沙箱时拒绝启动)
+- `sessions_spawn` **不接受**渠道投递参数(`target`、`channel`、`to`、`threadId`、`replyTo`、`transport`)。对于投递,请从派生出的运行中使用 `message`/`sessions_send`。
## 线程绑定会话
-当某个渠道启用了线程绑定时,sub-agent 可以保持绑定到某个线程,因此该线程中的后续用户消息会继续路由到同一个 sub-agent 会话。
+在线程绑定已为某个渠道启用时,子智能体可以保持绑定到一个线程,因此该线程中的后续用户消息会继续路由到同一个子智能体会话。
### 支持线程的渠道
-- Discord(当前唯一支持的渠道):支持持久的线程绑定 subagent 会话(`sessions_spawn` 配合 `thread: true`)、手动线程控制(`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`),以及适配器键 `channels.discord.threadBindings.enabled`、`channels.discord.threadBindings.idleHours`、`channels.discord.threadBindings.maxAgeHours` 和 `channels.discord.threadBindings.spawnSubagentSessions`。
+- Discord(当前唯一支持的渠道):支持持久线程绑定的子智能体会话(`sessions_spawn` 配合 `thread: true`)、手动线程控制(`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`),以及适配器键 `channels.discord.threadBindings.enabled`、`channels.discord.threadBindings.idleHours`、`channels.discord.threadBindings.maxAgeHours` 和 `channels.discord.threadBindings.spawnSubagentSessions`。
快速流程:
-1. 使用 `sessions_spawn` 并设置 `thread: true`(以及可选的 `mode: "session"`)来生成。
-2. OpenClaw 会在当前活动渠道中为该会话目标创建或绑定一个线程。
+1. 使用 `sessions_spawn` 启动,并设置 `thread: true`(可选同时设置 `mode: "session"`)。
+2. OpenClaw 会在当前活跃渠道中创建一个线程,或将一个线程绑定到该会话目标。
3. 该线程中的回复和后续消息会路由到绑定的会话。
-4. 使用 `/session idle` 检查/更新非活动自动取消聚焦设置,使用 `/session max-age` 控制硬上限。
+4. 使用 `/session idle` 查看/更新因不活跃而自动取消焦点的设置,使用 `/session max-age` 控制硬性上限。
5. 使用 `/unfocus` 手动解除绑定。
手动控制:
-- `/focus ` 将当前线程(或创建一个线程)绑定到某个 sub-agent/会话目标。
+- `/focus ` 将当前线程(或新建一个线程)绑定到某个子智能体/会话目标。
- `/unfocus` 移除当前已绑定线程的绑定关系。
-- `/agents` 会列出活动运行和绑定状态(`thread:` 或 `unbound`)。
+- `/agents` 列出活跃运行和绑定状态(`thread:` 或 `unbound`)。
- `/session idle` 和 `/session max-age` 仅适用于已聚焦的绑定线程。
配置开关:
- 全局默认值:`session.threadBindings.enabled`、`session.threadBindings.idleHours`、`session.threadBindings.maxAgeHours`
-- 渠道覆盖和 spawn 自动绑定键是适配器特定的。参见上方的**支持线程的渠道**。
+- 渠道覆盖和启动时自动绑定的键为适配器专用。参见上方的**支持线程的渠道**。
-当前适配器详情请参见 [Configuration Reference](/zh-CN/gateway/configuration-reference) 和 [斜杠命令](/zh-CN/tools/slash-commands)。
+当前适配器详情参见 [Configuration Reference](/zh-CN/gateway/configuration-reference) 和 [Slash commands](/zh-CN/tools/slash-commands)。
-Allowlist:
+允许列表:
-- `agents.list[].subagents.allowAgents`:可通过 `agentId` 定向的智能体 id 列表(`["*"]` 表示允许任意)。默认:仅允许请求者智能体。
-- `agents.defaults.subagents.allowAgents`:当请求者智能体未设置自己的 `subagents.allowAgents` 时使用的默认目标智能体 allowlist。
-- 沙箱继承保护:如果请求者会话处于沙箱中,`sessions_spawn` 会拒绝那些会以非沙箱方式运行的目标。
-- `agents.defaults.subagents.requireAgentId` / `agents.list[].subagents.requireAgentId`:为 true 时,会阻止省略 `agentId` 的 `sessions_spawn` 调用(强制显式 profile 选择)。默认:false。
+- `agents.list[].subagents.allowAgents`:可通过 `agentId` 指定的智能体 id 列表(`["*"]` 表示允许任意智能体)。默认值:仅允许请求者智能体。
+- `agents.defaults.subagents.allowAgents`:当请求者智能体未设置自己的 `subagents.allowAgents` 时使用的默认目标智能体允许列表。
+- 沙箱继承保护:如果请求者会话处于沙箱中,`sessions_spawn` 会拒绝那些将在非沙箱中运行的目标。
+- `agents.defaults.subagents.requireAgentId` / `agents.list[].subagents.requireAgentId`:当为 true 时,阻止省略 `agentId` 的 `sessions_spawn` 调用(强制显式选择配置文件)。默认值:false。
发现:
-- 使用 `agents_list` 查看当前哪些智能体 id 被允许用于 `sessions_spawn`。
+- 使用 `agents_list` 查看当前哪些智能体 id 允许用于 `sessions_spawn`。
自动归档:
-- Sub-agent 会话会在 `agents.defaults.subagents.archiveAfterMinutes` 之后自动归档(默认:60)。
+- 子智能体会话会在 `agents.defaults.subagents.archiveAfterMinutes` 之后自动归档(默认:60)。
- 归档使用 `sessions.delete`,并将转录重命名为 `*.deleted.`(同一文件夹)。
-- `cleanup: "delete"` 会在回报后立即归档(仍会通过重命名保留转录)。
-- 自动归档是尽力而为;如果 gateway 重启,待处理定时器会丢失。
-- `runTimeoutSeconds` **不会**自动归档;它只会停止运行。会话会保留直到自动归档。
-- 自动归档对 depth-1 和 depth-2 会话同样适用。
-- Browser 清理与归档清理分离:运行结束时,即使保留转录/会话记录,也会尽力关闭已跟踪的 browser 标签页/进程。
+- `cleanup: "delete"` 会在回传后立即归档(仍会通过重命名保留转录)。
+- 自动归档采用尽力而为的方式;如果 Gateway 网关重启,待处理的定时器会丢失。
+- `runTimeoutSeconds` **不会**自动归档;它只会停止运行。会话会保留,直到自动归档发生。
+- 自动归档同样适用于 depth-1 和 depth-2 会话。
+- 浏览器清理与归档清理是分开的:当运行结束时,即使转录/会话记录被保留,被跟踪的浏览器标签页/进程也会尽力关闭。
-## 嵌套 Sub-Agents
+## 嵌套子智能体
-默认情况下,sub-agents 不能生成它们自己的 sub-agents(`maxSpawnDepth: 1`)。你可以通过设置 `maxSpawnDepth: 2` 来启用一层嵌套,从而允许**编排器模式**:主智能体 → 编排 sub-agent → 工作 sub-sub-agents。
+默认情况下,子智能体不能再启动自己的子智能体(`maxSpawnDepth: 1`)。你可以通过设置 `maxSpawnDepth: 2` 来启用一层嵌套,这样就允许**编排器模式**:主智能体 → 编排器子智能体 → 工作子子智能体。
### 如何启用
@@ -170,10 +167,10 @@ Allowlist:
agents: {
defaults: {
subagents: {
- maxSpawnDepth: 2, // 允许 sub-agents 生成子级(默认:1)
- maxChildrenPerAgent: 5, // 每个智能体会话的活动子级上限(默认:5)
+ maxSpawnDepth: 2, // 允许子智能体启动子级(默认:1)
+ maxChildrenPerAgent: 5, // 每个智能体会话的最大活跃子级数(默认:5)
maxConcurrent: 8, // 全局并发 lane 上限(默认:8)
- runTimeoutSeconds: 900, // 省略时 sessions_spawn 的默认超时(0 = 无超时)
+ runTimeoutSeconds: 900, // `sessions_spawn` 省略时的默认超时(0 = 不超时)
},
},
},
@@ -182,123 +179,114 @@ Allowlist:
### 深度级别
-| 深度 | 会话键形状 | 角色 | 可以生成? |
-| ----- | ------------------------------------------ | --------------------------------------- | --------------------------- |
-| 0 | `agent::main` | 主智能体 | 始终可以 |
-| 1 | `agent::subagent:` | Sub-agent(在允许 depth 2 时为编排器) | 仅当 `maxSpawnDepth >= 2` |
-| 2 | `agent::subagent::subagent:` | Sub-sub-agent(叶子工作者) | 永远不可以 |
+| 深度 | 会话键形态 | 角色 | 可以启动子级? |
+| ----- | ------------------------------------------ | -------------------------------------------- | ---------------------------- |
+| 0 | `agent::main` | 主智能体 | 始终可以 |
+| 1 | `agent::subagent:` | 子智能体(在允许 depth 2 时可作为编排器) | 仅当 `maxSpawnDepth >= 2` 时 |
+| 2 | `agent::subagent::subagent:` | 子子智能体(叶子工作节点) | 永远不可以 |
-### 回报链
+### 回传链
-结果会沿链路向上流动:
+结果会沿链路逐级返回:
-1. 深度 2 的 worker 完成 → 向其父级(深度 1 编排器)回报
-2. 深度 1 编排器接收回报、综合结果、完成 → 向主级回报
-3. 主智能体接收回报并向用户投递
+1. depth-2 工作节点完成 → 向其父级(depth-1 编排器)回传
+2. depth-1 编排器接收回传、综合结果、完成 → 向主智能体回传
+3. 主智能体接收回传并将其投递给用户
-每一层只能看到其直接子级的回报。
+每一层只能看到其直接子级的回传。
-运维指导:
+操作指南:
-- 让子级工作启动一次,然后等待完成事件,而不是围绕 `sessions_list`、`sessions_history`、`/subagents list` 或
- `exec` sleep 命令构建轮询循环。
-- 如果子级完成事件在你已经发出最终答案之后才到达,
- 正确的后续处理是精确的静默令牌 `NO_REPLY` / `no_reply`。
+- 子任务启动一次后就等待完成事件,而不是围绕 `sessions_list`、`sessions_history`、`/subagents list` 或 `exec` sleep 命令构建轮询循环。
+- 如果在你已经发送最终答案之后,某个子级完成事件才到达,正确的后续操作是输出精确的静默令牌 `NO_REPLY` / `no_reply`。
### 按深度划分的工具策略
-- 角色和控制范围会在生成时写入会话元数据。这可以防止扁平化或恢复后的会话键意外重新获得编排器权限。
-- **深度 1(编排器,当 `maxSpawnDepth >= 2` 时)**:获得 `sessions_spawn`、`subagents`、`sessions_list`、`sessions_history`,以便管理其子级。其他会话/系统工具仍被拒绝。
-- **深度 1(叶子,当 `maxSpawnDepth == 1` 时)**:没有会话工具(当前默认行为)。
-- **深度 2(叶子工作者)**:没有会话工具 —— 在深度 2 时始终拒绝 `sessions_spawn`。不能进一步生成子级。
+- 角色和控制范围会在启动时写入会话元数据。这样可以防止扁平化或恢复后的会话键意外重新获得编排器权限。
+- **Depth 1(编排器,当 `maxSpawnDepth >= 2` 时)**:获得 `sessions_spawn`、`subagents`、`sessions_list`、`sessions_history`,以便管理其子级。其他会话/系统工具仍然被拒绝。
+- **Depth 1(叶子节点,当 `maxSpawnDepth == 1` 时)**:没有会话工具(当前默认行为)。
+- **Depth 2(叶子工作节点)**:没有会话工具 —— 在 depth 2 下始终拒绝 `sessions_spawn`。不能继续启动更多子级。
-### 每个智能体的生成上限
+### 每个智能体的启动上限
-每个智能体会话(任何深度)同时最多只能有 `maxChildrenPerAgent`(默认:5)个活动子级。这可以防止单个编排器失控式扇出。
+每个智能体会话(任意深度)同一时间最多只能有 `maxChildrenPerAgent`(默认:5)个活跃子级。这可以防止单个编排器发生失控式扇出。
### 级联停止
-停止一个深度 1 编排器会自动停止其所有深度 2 子级:
+停止一个 depth-1 编排器会自动停止它的所有 depth-2 子级:
-- 在主聊天中发送 `/stop` 会停止所有深度 1 智能体,并级联停止它们的深度 2 子级。
-- `/subagents kill ` 会停止某个特定 sub-agent,并级联停止其子级。
-- `/subagents kill all` 会停止该请求者的所有 sub-agents,并进行级联。
+- 在主聊天中执行 `/stop` 会停止所有 depth-1 智能体,并级联停止它们的 depth-2 子级。
+- `/subagents kill ` 会停止指定的子智能体,并级联停止其子级。
+- `/subagents kill all` 会停止该请求者的所有子智能体,并执行级联停止。
## 认证
-Sub-agent 认证按**智能体 id**解析,而不是按会话类型:
+子智能体认证按**智能体 id**解析,而不是按会话类型:
-- Sub-agent 会话键是 `agent::subagent:`。
+- 子智能体会话键为 `agent::subagent:`。
- 认证存储从该智能体的 `agentDir` 加载。
-- 主智能体的认证配置文件会作为**回退**合并进来;若发生冲突,则智能体配置文件覆盖主配置文件。
+- 主智能体的认证配置文件会作为**回退**合并进来;若发生冲突,智能体配置文件会覆盖主配置文件。
-注意:这种合并是增量式的,因此主配置文件始终可作为回退项。当前尚不支持每个智能体完全隔离的认证。
+注意:这种合并是增量式的,因此主配置文件始终可作为回退使用。当前尚不支持每个智能体完全隔离的认证。
-## 回报
+## 回传
-Sub-agents 通过回报步骤进行结果上报:
+子智能体通过一个回传步骤进行结果上报:
-- 回报步骤在 sub-agent 会话内部运行(而不是在请求者会话中)。
-- 如果 sub-agent 精确回复 `ANNOUNCE_SKIP`,则不会发布任何内容。
-- 如果最新的助手文本是精确的静默令牌 `NO_REPLY` / `no_reply`,
- 即使之前存在可见的进度,回报输出也会被抑制。
-- 否则投递取决于请求者深度:
- - 顶层请求者会话使用一个带外部投递的后续 `agent` 调用(`deliver=true`)
- - 嵌套的请求者 subagent 会话会接收一个内部后续注入(`deliver=false`),以便编排器在会话内综合子级结果
- - 如果某个嵌套的请求者 subagent 会话已不存在,OpenClaw 会在可能时回退到该会话的请求者
-- 对于顶层请求者会话,完成模式的直接投递会首先解析任何绑定的会话/线程路由和 hook 覆盖值,然后从请求者会话已存储的路由中补齐缺失的渠道目标字段。这样即使完成来源仅标识了渠道,也能将完成消息保留在正确的聊天/主题中。
-- 在构建嵌套完成发现结果时,子级完成聚合会限定在当前请求者运行范围内,从而防止先前运行中陈旧的子级输出泄露到当前回报中。
-- 在渠道适配器可用时,回报回复会保留线程/主题路由。
-- 回报上下文会被规范化为稳定的内部事件块:
- - source(`subagent` 或 `cron`)
- - 子会话键/id
- - 回报类型 + 任务标签
- - 从运行时结果推导的状态行(`success`、`error`、`timeout` 或 `unknown`)
- - 从最新可见助手文本中选取的结果内容;否则为经过净化的最新 tool/toolResult 文本
- - 一条后续指令,说明何时回复、何时保持静默
+- 回传步骤在子智能体会话内部运行(不是在请求者会话中)。
+- 如果子智能体的回复精确等于 `ANNOUNCE_SKIP`,则不会发布任何内容。
+- 如果最新的 assistant 文本是精确的静默令牌 `NO_REPLY` / `no_reply`,即使此前存在可见进度,也会抑制回传输出。
+- 否则,投递方式取决于请求者深度:
+ - 顶层请求者会话使用带外部投递的后续 `agent` 调用(`deliver=true`)
+ - 嵌套的请求者子智能体会话接收一次内部后续注入(`deliver=false`),以便编排器在会话内综合子级结果
+ - 如果某个嵌套的请求者子智能体会话已经不存在,OpenClaw 会在可用时回退到该会话的请求者
+- 对于顶层请求者会话,完成模式下的直接投递会先解析任何已绑定的会话/线程路由和 hook 覆盖,然后从请求者会话存储的路由中补齐缺失的渠道目标字段。这样即使完成来源只标识了渠道,也能把完成消息发送到正确的聊天/话题中。
+- 在构建嵌套完成结果时,子级完成聚合会限定在当前请求者运行范围内,从而防止先前运行中遗留的子级输出泄漏到当前回传中。
+- 在渠道适配器可用时,回传回复会保留线程/话题路由。
+- 回传上下文会规范化为稳定的内部事件块:
+ - 来源(`subagent` 或 `cron`)
+ - 子级会话 key/id
+ - 回传类型 + 任务标签
+ - 从运行时结果推导出的状态行(`success`、`error`、`timeout` 或 `unknown`)
+ - 从最新可见 assistant 文本中选取的结果内容;否则使用经过清理的最新 `tool/toolResult` 文本;终态失败运行会报告失败状态,而不会重放已捕获的回复文本
+ - 一条后续指令,说明何时应回复、何时应保持静默
- `Status` 不是从模型输出推断的;它来自运行时结果信号。
-- 超时时,如果子级只执行到了工具调用阶段,回报可以将那段历史折叠为简短的部分进度摘要,而不是重放原始工具输出。
+- 超时时,如果子级只执行到了工具调用阶段,回传可以将这段历史折叠为简短的部分进展摘要,而不是重放原始工具输出。
-回报载荷在末尾包含一行统计信息(即使被包装):
+回传负载在末尾包含一行统计信息(即使被包装也是如此):
-- 运行时(例如 `runtime 5m12s`)
-- Token 用量(input/output/total)
-- 当配置了模型定价时的估算成本(`models.providers.*.models[].cost`)
-- `sessionKey`、`sessionId` 和转录路径(这样主智能体可以通过 `sessions_history` 获取历史,或在磁盘上检查文件)
-- 内部元数据仅用于编排;面向用户的回复应以正常助手语气改写。
+- 运行时长(例如 `runtime 5m12s`)
+- 令牌使用量(输入/输出/总计)
+- 如果已配置模型定价(`models.providers.*.models[].cost`),则包含估算成本
+- `sessionKey`、`sessionId` 和转录路径(这样主智能体就可以通过 `sessions_history` 获取历史记录,或直接检查磁盘上的文件)
+- 内部元数据仅用于编排;面向用户的回复应使用正常 assistant 语气重新表述。
`sessions_history` 是更安全的编排路径:
-- 会先对 assistant 回忆进行规范化:
- - 移除 thinking 标签
- - 移除 `` / `` 脚手架块
- - 移除纯文本工具调用 XML 载荷块,如 `...`、
- `...`、`...` 和
- `...`,包括那些从未正常闭合的截断载荷
- - 移除已降级的工具调用/结果脚手架和历史上下文标记
- - 移除泄露的模型控制令牌,例如 `<|assistant|>`、其他 ASCII
- `<|...|>` 令牌,以及全角 `<|...|>` 变体
- - 移除格式错误的 MiniMax 工具调用 XML
-- 类似凭证/token 的文本会被脱敏
-- 长块可能会被截断
-- 非常大的历史可能会丢弃较早的行,或者用
- `[sessions_history omitted: message too large]`
- 替换一个过大的行
-- 当你需要完整逐字节转录时,回退方案是在磁盘上检查原始转录
+- assistant 回溯会先进行规范化:
+ - 去除 thinking 标签
+ - 去除 `` / `` 脚手架块
+ - 去除纯文本工具调用 XML 负载块,例如 `...`、`...`、`...` 和 `...`,包括那些从未正常闭合的截断负载
+ - 去除降级后的工具调用/结果脚手架和历史上下文标记
+ - 去除泄漏的模型控制令牌,例如 `<|assistant|>`、其他 ASCII `<|...|>` 令牌,以及全角变体 `<|...|>`
+ - 去除格式错误的 MiniMax 工具调用 XML
+- 类凭证/令牌的文本会被脱敏
+- 长内容块可能会被截断
+- 非常大的历史记录可能会丢弃较旧的行,或用 `[sessions_history omitted: message too large]` 替换过大的行
+- 当你需要完整逐字节转录时,回退方案是直接检查磁盘上的原始转录文件
-## 工具策略(sub-agent 工具)
+## 工具策略(子智能体工具)
-默认情况下,sub-agents 获得**除会话工具**和系统工具之外的**所有工具**:
+默认情况下,子智能体获得**除会话工具和系统工具之外的所有工具**:
- `sessions_list`
- `sessions_history`
- `sessions_send`
- `sessions_spawn`
-这里的 `sessions_history` 仍然是一个有界、经过净化的回忆视图;它
-不是原始转录转储。
+这里的 `sessions_history` 仍然是一个有边界、经过清理的回溯视图;它不是原始转录转储。
-当 `maxSpawnDepth >= 2` 时,深度 1 的编排型 sub-agents 还会额外获得 `sessions_spawn`、`subagents`、`sessions_list` 和 `sessions_history`,以便管理其子级。
+当 `maxSpawnDepth >= 2` 时,depth-1 编排器子智能体还会额外获得 `sessions_spawn`、`subagents`、`sessions_list` 和 `sessions_history`,以便管理其子级。
可通过配置覆盖:
@@ -316,7 +304,7 @@ Sub-agents 通过回报步骤进行结果上报:
tools: {
// deny 优先生效
deny: ["gateway", "cron"],
- // 如果设置 allow,则变为仅 allow 模式(deny 仍然优先生效)
+ // 如果设置了 allow,则变为仅允许 allow 中的工具(deny 仍然优先)
// allow: ["read", "exec", "process"]
},
},
@@ -326,21 +314,21 @@ Sub-agents 通过回报步骤进行结果上报:
## 并发
-Sub-agents 使用一个专用的进程内队列 lane:
+子智能体使用专用的进程内队列 lane:
-- Lane 名称:`subagent`
+- lane 名称:`subagent`
- 并发数:`agents.defaults.subagents.maxConcurrent`(默认 `8`)
## 停止
-- 在请求者聊天中发送 `/stop` 会中止请求者会话,并停止由其生成的任何活动 sub-agent 运行,同时级联到嵌套子级。
-- `/subagents kill ` 会停止某个特定 sub-agent,并级联到其子级。
+- 在请求者聊天中发送 `/stop` 会中止请求者会话,并停止所有由其启动的活跃子智能体运行,同时级联停止嵌套子级。
+- `/subagents kill ` 会停止指定的子智能体,并级联停止其子级。
## 限制
-- Sub-agent 回报是**尽力而为**的。如果 gateway 重启,待处理的“回报给上游”工作会丢失。
-- Sub-agents 仍共享同一个 gateway 进程资源;请将 `maxConcurrent` 视为一个安全阀。
+- 子智能体回传是**尽力而为**的。如果 Gateway 网关重启,待处理的“回传结果”工作会丢失。
+- 子智能体仍然共享同一个 Gateway 网关进程资源;请将 `maxConcurrent` 视为安全阀。
- `sessions_spawn` 始终是非阻塞的:它会立即返回 `{ status: "accepted", runId, childSessionKey }`。
-- Sub-agent 上下文只会注入 `AGENTS.md` + `TOOLS.md`(不包括 `SOUL.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md` 或 `BOOTSTRAP.md`)。
-- 最大嵌套深度为 5(`maxSpawnDepth` 范围:1–5)。大多数使用场景推荐深度 2。
-- `maxChildrenPerAgent` 限制每个会话的活动子级数量(默认:5,范围:1–20)。
+- 子智能体上下文只会注入 `AGENTS.md` + `TOOLS.md`(不会注入 `SOUL.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md` 或 `BOOTSTRAP.md`)。
+- 最大嵌套深度为 5(`maxSpawnDepth` 范围:1–5)。大多数场景建议使用 depth 2。
+- `maxChildrenPerAgent` 限制每个会话的活跃子级数量(默认:5,范围:1–20)。