From 29dd8c371edfd86ffc45ae2224081819f416bbc0 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Tue, 21 Apr 2026 19:02:07 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/automation/tasks.md | 175 +++++++++--------- docs/zh-CN/tools/subagents.md | 328 ++++++++++++++++----------------- 2 files changed, 246 insertions(+), 257 deletions(-) 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）。