使用动态工作流大规模编排子智能体
Orchestrate subagents at scale with dynamic workflows
原文:Orchestrate subagents at scale with dynamic workflows
所有付费套餐均提供动态工作流;通过 Anthropic API 访问时,以及在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上,也都可以使用。在 Pro 套餐中,请通过 /config中的 Dynamic workflows 行开启它们。
动态工作流是一种 JavaScript 脚本,可以一次编排许多子智能体。Claude 会为你描述的任务编写脚本,运行时则在后台执行它,而你的会话始终保持响应。
当任务所需的智能体数量超出单次对话能够协调的范围,或者你希望把编排固化成一个可读、可重跑的脚本时,就该使用工作流。示例包括全代码库缺陷清扫、500 个文件的迁移、需要让来源相互交叉核对的研究问题,以及值得在拍板前从多个独立角度起草的棘手计划。
何时使用工作流
子智能体、技能、智能体团队和工作流都能执行多步骤任务。区别在于由谁掌握计划:
| 子智能体 | 技能 | 智能体团队 | 工作流 | |
|---|---|---|---|---|
| 它是什么 | 由 Claude 生成的执行者 | Claude 遵循的指令 | 监督同级会话的主导智能体 | 由运行时执行的脚本 |
| 谁决定接下来运行什么 | Claude,逐轮决定 | Claude,按提示词执行 | 主导智能体,逐轮决定 | 脚本 |
| 中间结果所在的位置 | Claude 的上下文窗口 | Claude 的上下文窗口 | 共享任务列表 | 脚本变量 |
| 可复用的内容 | 执行者的定义 | 指令 | 团队定义 | 编排本身 |
| 规模 | 每轮少量委派任务 | 与子智能体相同 | 少数长时间运行的同级智能体 | 每次运行数十到数百个智能体 |
| 中断 | 重新开始当前轮次 | 重新开始当前轮次 | 队友会继续运行 | 可在同一会话中恢复 |
工作流把计划移入代码。使用子智能体、技能和智能体团队时,Claude 是编排者:它逐轮决定接下来启动或分派什么,而每个结果都会进入上下文窗口。工作流脚本自身保存循环、分支和中间结果,因此 Claude 的上下文只保留最终答案。
把计划移入代码还让工作流能够应用可重复的质量模式,而不只是运行更多智能体:它可以先让彼此独立的智能体在汇报前对抗性地审查对方的发现,也可以从多个角度起草计划并相互权衡,从而得到比单轮执行更可信的结果。
运行内置工作流
体验工作流实际运行的最快方式,是运行 /deep-research——即内置工作流,由 Claude Code 提供,用于跨多个来源调查一个问题。你会在后台看到智能体依次推进各个阶段,而你的会话保持空闲,最后拿到一份报告,而不是逐轮记录。
1. 运行工作流
运行 /deep-research 来调查你想了解的问题。它会从多个角度扇出网络搜索,抓取并交叉核对找到的来源,并综合成一份带引用的报告。
/deep-research What changed in the Node.js permission model between v20 and v22?
2. 允许工作流
Claude Code 会询问是否允许该工作流。请选择 是 以继续。具体提示取决于你的权限模式。参见在运行前批准计划以了解各模式下的选项。
3. 查看进度
运行会在后台启动。运行 /workflows 以打开其进度视图:
/workflows
如果 /workflows 显示的是运行列表,请选择你刚刚启动的运行并按 Enter。视图会显示每个阶段及其智能体数量。深入查看任意阶段,即可查看其中的智能体以及每个智能体发现了什么。参见查看运行了解完整的控制项。
你也可以在输入框下方的任务面板中查看:运行进行期间,那里会显示一行进度摘要。按向下箭头使其获得焦点,然后按 Enter 展开。
4. 阅读报告
运行完成后,报告会出现在你的会话中。报告会引用每项主张的来源,并且已经过滤掉未能通过交叉核对的主张。
当验证器智能体无法核查某项主张时(例如遇到速率限制或 API 错误后),报告会将该主张列为未核实,而不是将其计为已驳斥。
若想为自己的任务运行工作流,就让 Claude 编写一个;当某次运行实现你想要的效果后,你便可以将其保存为你自己的命令。
内置工作流
Claude Code 包含 /deep-research 作为内置工作流:
| 命令 | 作用 |
|---|---|
/deep-research <question> | 围绕一个问题从多个角度扇出网络搜索,抓取并交叉核对找到的来源,对每项主张进行投票,并返回一份带引用的报告,其中已过滤掉未通过交叉核对的主张。需要WebSearch 工具可用 |
/deep-research 只在你调用它时运行。
你自己保存的工作流也会以同样方式成为命令,并出现在 / 自动补全中,与内置工作流并列。
查看运行
工作流在后台运行,因此智能体工作时会话仍保持响应。随时运行 /workflows 即可列出正在运行和已完成的工作流,然后选择其中一个打开其进度视图。当会话中只有一次运行时,/workflows 会跳过列表并直接打开该次运行。若要从列表中停止正在运行的工作流而不打开它,请选中它并按 x。
进度视图会显示每个阶段及其智能体数量。页脚列出了每项操作的按键:
| 按键 | 操作 |
|---|---|
↑ / ↓ | 选择一个阶段或智能体 |
Enter 或 → | 深入查看所选阶段,然后进入智能体详情。在详情中,Enter 可展开或折叠该详情 |
Esc 或 ← | 返回上一层 |
j / k | 当智能体详情内容溢出时,在其中滚动 |
f | 按状态筛选所选阶段中的智能体列表。再次按下可循环切换 |
p | 暂停或恢复运行 |
x | 停止所选智能体;当焦点位于该次运行时,停止整个工作流 |
r | 重新启动所选且正在运行的智能体 |
s | 将本次运行的脚本保存为命令 |
智能体详情会列出该智能体的提示词、最近的工具调用及其结果。每次调用都会显示其状态,例如仍在运行或已失败。当智能体自己维护任务列表时,详情中也会显示该列表以及每个任务的状态。
按 Enter 展开详情。随后提示词和结果会完整显示,列出的每次调用也会显示其输入和结果开头。
让 Claude 编写工作流
你可以通过两种方式让 Claude 为你的任务编写工作流:
- 要请求工作流,可在提示词中用自己的话,或包含关键词
ultracode,Claude 就会为这项任务编写一个工作流。 - 让 Claude 用 ultracode 自行决定:设置
/effort ultracode,Claude 就会为会话中的每项实质性任务规划一个工作流。
你也可以运行一个已经存在的工作流命令:一个内置工作流,例如 /deep-research,或者你已保存的那个。
在提示词中请求工作流
若要把单个任务作为工作流运行而不改变会话的投入等级,请在提示词中包含关键词 ultracode。用自己的话提出也可以,例如“使用工作流”或“运行工作流”:Claude 会把直接请求视为同样的主动启用。
ultracode: audit every API endpoint under src/routes/ for missing auth checks
Claude Code 会在你的输入中高亮该关键词,并且 Claude 会为该任务编写工作流脚本,而不是逐轮处理它。该关键词只决定 Claude 如何组织工作:智能体的工具调用会接受相同的权限检查和沙箱隔离,与会话中的其他任何工具调用一样。
如果这次运行达到你想要的效果,你可以把它保存为命令;之后,如果你已经用其他方式构建了编排器,例如一个装满子智能体提示词的文件夹,或一个可扇出工作的技能,你可以把它指给 Claude,并让它编写一个做同样事情的工作流。
忽略或关闭关键词
如果你并不想启动工作流,请按 Option+W(macOS)或 Alt+W(Windows 和 Linux)来清除此提示词中的高亮,或者当光标正好位于高亮关键词之后时按退格键。若要彻底阻止该关键词触发,请在 /config中关闭“Ultracode 关键词触发”。
关键词的适用范围
该关键词仅在你亲自输入的提示词中才算主动启用:在交互式提示符中、在 IDE 扩展面板中、在远程控制客户端中,或在会将你的键盘输入的origin标记为 { kind: "human" }的 Agent SDK 应用中。当它以其他方式到达会话时,它不会启动工作流:
- 通过以下参数传入的提示词
-p - Agent SDK 应用在发送时未将其标记为人工输入的提示词
- 计划任务的提示词
- 被转发到会话中的 webhook 载荷或拉取请求评论
让 Claude 用 ultracode 自行决定
Ultracode 是一项 Claude Code 设置,可为此会话开启自动工作流编排,无论会话以何种投入等级运行。开启后,Claude 会为每项实质性任务规划工作流,而不是等你提出请求。可在 Claude Code 提示符中开启它:
/effort ultracode
要启动会话时预先开启 ultracode,请使用 claude --effort ultracode启动,这也会将投入等级设为 xhigh。
要从 /effort 滑块开启它,请按 Tab 切换 Ultracode 开关,然后按 Enter 应用。调整投入等级列出了开启 ultracode 的各种方式。
开启 ultracode 后,Claude 会判断任务何时值得使用工作流。一个请求可能接连变成多个工作流:一个用于理解代码,一个用于做出更改,一个用于验证更改。这适用于会话中的每项任务,因此每个请求都会比不使用工作流时消耗更多 token 并耗时更长。在订阅套餐中,这些 token 会占用你的用量限制,因此开启 ultracode 的会话会比关闭时执行同样的工作更早达到会话或每周用量限制。
开启 ultracode 本身即表示你同意进行大规模运行,因此开启期间不会应用这些检查:
- 该
Large workflow警告在工作流运行期间不会出现 - 会话的并发子智能体上限不会对 Claude 通过 Agent 工具启动的子智能体强制执行
- 在自动权限模式下,不会要求你批准首次工作流启动
/effort ultracode 仅对当前会话有效;若要让每个会话都以此开始,请设置ultracode设置。当你回归日常工作时,用 /effort ultracode off 将其关闭。/effort 滑块仅在ultracode 可用时提供该开关。
在运行前批准计划
在 CLI 中,每次运行的提示会显示计划阶段和以下选项:
- 是,运行它:开始运行
- 是,并且不再询问
<name>在<path>中:启动,并从此在本项目中跳过此工作流的这一提示。当你按名称运行内置、已保存或插件工作流时,Claude Code 会提供此选项;但 Claude 为当前任务编写的脚本不会获得此选项。 - 查看原始脚本:在做出决定前阅读脚本
- 否:取消
Ctrl+G 会在你的编辑器中打开脚本。在选中 是,运行它 或 否 后,按 Tab 来添加一条注释到你的回答中。
你是否会看到此提示取决于你的权限模式:
| 权限模式 | 何时提示你 |
|---|---|
| 自动 | 仅首次启动。选择 是 后,会在你的用户设置中记录同意,之后的启动将不再提示。启用 ultracode 时会完全跳过此步骤 |
| 手动,接受编辑 | 每次运行都会提示,除非你已选择 是,并且不再询问 在本项目中针对该工作流 |
| 绕过权限 | Claude Code 不会提示你。运行会立即开始 |
claude -p,Agent SDK | Claude Code 不会提示你 |
在 claude -p 和 Agent SDK 中,Claude Code 从不显示此提示。它会像会话的其余部分一样,对 Workflow 工具调用执行相同的权限评估,因此拒绝规则、询问规则和 dontAsk 模式会像适用于每次工具调用一样适用于工作流的启动。要在这些运行中允许工作流启动,请使用以下任一方式:
- 权限规则:将
Workflow添加到允许规则中即可批准所有工作流,或Workflow(<name>)来按名称批准某个已保存的工作流。 - 自动权限模式:在自动模式下运行,此时分类器会审查该调用,并可以批准它。
- 绕过权限模式:在绕过权限模式下运行。
- 钩子:返回
"allow",用于来自PreToolUse钩子的调用。在计划模式下,仅凭钩子的批准,工作流不会启动,因此请改用权限规则或你的宿主提供的批准。 - 你的宿主:使用
--permission-prompt-tool,或者在使用 Agent SDK 时,由canUseTool回调批准。
在桌面应用中,审批卡片会显示工作流名称、阶段列表和 token 用量提醒,并提供 仅一次、 始终和 拒绝 操作。进度视图会显示在“后台任务”侧窗格中。
工作流派生的子智能体使用你的权限规则,而 Claude Code 会依据子智能体在何种权限模式下运行的规则来选择它们的权限模式。为避免长时间运行期间出现提示,请在开始前将智能体所需的工具加入你的允许规则。
保存工作流以便复用
当 Claude 为你会重复执行的任务编写工作流时,你可以把该次运行的脚本保存为命令。这样,诸如你在每个分支上都要执行的审查之类的流程,每次都会运行相同的编排。
运行 /workflows,选择要保留的运行,然后按 s。在保存对话框中,Tab 可在两个保存位置之间切换:
.claude/workflows/在项目中:与所有克隆该仓库的人共享~/.claude/workflows/在你的主目录中:在每个项目中都可用,且仅对你可见。如果你设置了CLAUDE_CONFIG_DIR,那么此位置就是该路径下的workflows/目录。
保存对话框会显示个人位置的解析后路径。
按 Enter 保存。该工作流会在未来会话中从任一位置以 /<name> 的形式运行。
Claude Code 在写入前会检查保存位置是否存在符号链接,若存在则显示错误,而不是通过链接写入。检查内容取决于你的保存位置:
- 项目位置:如果
.claude、.claude/workflows,或目标文件是符号链接,Claude Code 就会拒绝。 - 个人位置:仅当目标文件本身是符号链接时,Claude Code 才会拒绝,因此由 dotfiles 工具管理的
~/.claude目录仍然可用。
在 v2.1.216 之前,Claude Code 会跟随该链接,这可能会把文件放到你所选位置之外。
在包含多个 .claude/ 目录的 monorepo 中,你可以把工作流与其适用的包放在一起。保存到项目位置时,会写入你的工作目录与仓库根目录之间已存在的最近一个 .claude/workflows/ 目录;如果尚不存在这样的目录,则写入仓库根目录。项目工作流还会从该路径上的每一个 .claude/workflows/ 加载,当多个同名定义并存时,Claude Code 会运行最接近工作目录的那个。
如果项目工作流和个人工作流同名,会运行项目工作流。
在插件中分发工作流
要在团队或仓库之间共享工作流,请将其包含在插件中。将脚本放在插件根目录下的 workflows/ 目录中,或使用workflows 清单字段指向其他位置。
插件工作流以插件名称作为命名空间。一个名为 acme-tools 的插件包含一个脚本,其 meta.name 为 release-audit 运行为 /acme-tools:release-audit。
向已保存的工作流传递输入
已保存的工作流可以通过 args 参数接受输入。脚本会将其读取为名为 args的全局变量。在调用时,你可以用它提供研究问题、目标路径列表或配置对象,而不必为每次运行修改脚本。
以下提示会用一组议题编号来运行已保存的工作流:
Run /triage-issues on issues 1024, 1025, and 1030
Claude 会将列表作为结构化数据传入,因此脚本可以直接在 args 上调用数组和对象方法,而无需先解析它。如果 args 被省略,则脚本内的全局变量为 undefined。
工作流提示词示例
当任务大到单个智能体无法在上下文中容纳,或同一步骤需要跨多个条目运行时,工作流最为合适。下面的提示展示了常见形态。每一条都要求 Claude 为该任务编写并运行工作流;脚本不需要你亲自编写。
审查多个文件是否存在同一问题
为每个文件扇出一个智能体,然后收集并核实发现。
use a workflow to audit every route handler under src/routes/ for missing authentication checks, and adversarially verify each finding before reporting it
持续修复,直到检查通过
运行检查器,修复失败项,然后重复,直到它通过或不再取得进展。
use a workflow to run npx tsc --noEmit and keep fixing the reported errors until the type check passes or two rounds in a row make no progress
并行迁移多个文件
找出需要迁移的文件,在隔离副本中逐个转换,以免编辑冲突,并验证每个结果。
use a workflow to migrate every component under src/components/ from JavaScript to TypeScript, working on each file in its own isolated copy
审查每个变更文件并撰写一份总结
为每个文件运行一个审查者,然后将所有发现交给一个智能体,由它对这些发现进行排序和去重。
use a workflow to review every file changed in this PR for correctness issues, then merge the per-file findings into one ranked summary
跨多个来源研究一个主题
在变更日志、议题和文档之间扇出阅读者,然后进行综合。内置的 /deep-research 工作流会这样做;你也可以描述一个范围更窄的版本。
use a workflow to research how our three competitors handle rate limiting: read their public docs and recent changelog entries in parallel, then compare the approaches
持续查找问题,直到列表不再增长
持续分轮搜索,当新的轮次没有发现任何新内容时停止。
use a workflow to find flaky tests in this repo: run the suite repeatedly, record which tests fail intermittently, and stop once two rounds in a row find nothing new
保存后的脚本是什么样子
当你保存工作流时,.claude/workflows/ 中的文件会包含一个 meta 块,后面是一个编排子智能体的脚本主体。你通常不需要编辑它,但下面给出一个小型工作流的形态,方便你辨认 Claude 生成了什么:
export const meta = {
name: 'audit-routes',
description: 'Audit every route handler for missing auth checks',
}
const found = await agent('List every .ts file under src/routes/.', {
schema: { type: 'object', required: ['files'], properties: { files: { type: 'array', items: { type: 'string' } } } },
})
const audits = await pipeline(found.files, file =>
agent(`Audit ${file} for missing authentication checks.`, { label: file }),
)
return audits.filter(Boolean)
主体是纯 JavaScript,使用顶层 await。agent() 会派生一个子智能体,pipeline() 会为列表中的每个条目运行一个,而 parallel() 会同时运行一组智能体任务,并等待它们全部完成。
一次 agent() 调用会解析为 null,前提是你在运行中途停止它,或它遇到不可恢复的 API 错误。pipeline() 会在结果数组中保留每个 null,这就是示例最后使用 .filter(Boolean) 来丢弃这些条目的原因,包括一个在每次尝试中都停滞的智能体所占的槽位。
在自动模式下,当分类器审查该子智能体的操作时,脚本传给 agent() 的提示不会被计为你发出的请求,因为 Claude Code 会将其标记为脚本计算出的文本。
如果你传入 schema 作为 agent() 调用的参数,该子智能体会返回符合该结构的 JSON,而不是散文。Claude Code 会在启动子智能体之前检查 schema:当它能证明 schema 自相矛盾时,调用会失败,并给出一个指明该矛盾的错误,子智能体永远不会启动。它能证明的一种矛盾是,一个 required 键被 additionalProperties: false 排除在外。
如果子智能体的输出在五次尝试后仍未通过验证,调用就会失败,错误中会包含最后一次验证失败的信息。要更改尝试次数,请设置MAX_STRUCTURED_OUTPUT_RETRIES。
编辑已保存的脚本
要修改一个你保存的工作流,请编辑其 .js 文件,或让 Claude 进行修改。在编辑或提出请求之前,请先运行 /workflow-authoring 这个内置技能,以加载 Claude 编写脚本时所依据的参考文档。该技能要求 Claude Code v2.1.248 或更高版本。
要在当前会话中运行编辑后的版本,请运行/reload-skills以重新读取工作流目录,然后再次运行 /<name>。
Claude Code 在加载并运行脚本时,会对文件的每个部分应用以下规则:
meta代码块:保留export const meta作为第一条语句,并保持它是一个普通对象字面量,其中包含name和description。如果它包含字面值以外的任何内容,例如变量、函数调用或展开语法,Claude Code 会把/<name>从/自动补全中移除。- 主体:除了
agent()、pipeline()和parallel()之外,你还可以调用phase()在进度视图中将后续智能体归入某个标题下,调用log()在各阶段上方显示一条消息,并读取args全局变量。如果主体存在语法错误,Claude Code 会在你运行工作流时报告该错误。 phases:如果你在meta中列出它们,请让每个条目的标题与传给phase()的标题完全一致。没有对应条目的phase()标题会拥有自己的进度分组。- 时间戳与随机性:Claude Code 会让
Date.now()、Math.random()以及不带参数的new Date()在脚本内抛出错误,这样一次重新启动的运行就会重复相同的agent()调用。请改为通过args传入时间戳。
你也可以编辑单次运行的脚本,而不是已保存的副本。暂停后恢复介绍了当你重新启动编辑后的脚本时,哪些智能体会再次运行。有关 Workflow 工具的输入,请参阅Agent SDK 参考中的相应条目。
工作流如何运行
工作流运行时会在与你的对话相隔离的环境中执行脚本。中间结果会留在脚本变量中,而不会进入 Claude 的上下文。
每次运行都会将脚本写入 ~/.claude/projects/中你的会话目录下的一个文件。运行开始时,Claude 会收到该路径,因此你可以向它询问。你可以打开该文件,阅读 Claude 编写的编排逻辑,将其与上一次运行的脚本做差异比较,或者编辑它,并让 Claude 从编辑后的版本重新启动。
Claude 只能从会话已被允许读取的脚本文件启动工作流。要运行保存在工作目录之外的脚本,请先用/add-dir添加其目录,或先添加一条Read 允许规则。
运行时会随着运行进展跟踪每个智能体的结果,这正是让一次运行可恢复的原因,但仅限于同一会话内。
扇出中的提示缓存
同一次运行中的智能体可以读取彼此的提示缓存。使用相同模型、投入等级、智能体类型、工具、输出 schema 和工作目录运行的两个智能体,会构建相同的工具与系统提示前缀,因此,如果某个智能体在一个配置匹配的同级智能体开始响应之后才启动,它就会在首次请求时读取该同级智能体的缓存。
工作流智能体的请求不在主对话的缓存 TTL 分桶内,因此其缓存默认保留五分钟,包括在 Claude 订阅中也是如此。要保留一小时,请设置subagentPromptCacheTtl为 1h。API 对 1 小时缓存写入按更高费率计费。
当一次扇出同时启动多个配置匹配的智能体时,Claude Code 会暂缓除第一个之外的所有智能体,直到第一个智能体开始响应,然后一起释放被暂缓的智能体,使它们的首次请求读取共享前缀,而不是各自在未缓存的情况下处理该前缀。Claude Code 将此暂缓的上限设为CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS毫秒,5000 为默认值。将其设置为 0 即可禁用暂缓。
行为与限制
运行时会应用以下约束:
| 约束 | 原因 |
|---|---|
| 运行过程中没有用户输入 | 一次运行只会在遇到智能体权限提示和用量限制等待时自行暂停。若要在各阶段之间进行确认,请将每个阶段作为独立工作流运行 |
| 工作流本身无法直接访问文件系统或 shell | 智能体负责读取、写入和运行命令。脚本负责协调这些智能体 |
不支持加载模块:包含 import() 的脚本会在运行开始前失败 | 脚本主体是纯 JavaScript。请把需要用到库的工作放进智能体的任务里 |
默认最多 16 个并发智能体;如果 Claude Code 可用的 CPU 更少,并发数也会减少,在受 CPU 限制的容器内同样如此。要更改此限制,请将CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS设为 1 到 256 之间的值,这需要 Claude Code v2.1.269 或更高版本 | 限制本地资源使用 |
| 在扇出中,共享首个智能体提示缓存前缀的智能体,默认会在首个智能体之后最多 5 秒内启动 | 除第一个之外的所有智能体都会读取第一个智能体缓存的前缀,而不是各自以未缓存的方式处理该前缀 |
最多 4,096 项,在单次 parallel() 或 pipeline() 调用中:运行时会对更长的列表报错并拒绝 | 静默上限会在不告知脚本的情况下丢弃部分工作负载 |
| 每次运行总共 1,000 个智能体 | 防止失控循环 |
管理运行
运行开始后,你可以从 /workflows 视图中管理它,也可以展开输入框下方任务面板中的进度行来管理。
当你停止一次运行时,只要其任一智能体的进程仍在运行,该运行就会留在任务面板中。如果你再次停止它,Claude Code 会重新向这些进程发送信号。
暂停后恢复
要从 /workflows 恢复已暂停的运行,请选择该运行并按 p。对于你停止的运行,请让 Claude 使用同一脚本重新启动工作流。如果已停止运行中的智能体尚未退出,Claude Code 会拒绝重新启动,直到它们退出,从而避免这些智能体的第二份副本与它们同时运行。
哪些智能体会再次运行
Claude Code 会按智能体启动的顺序重放该运行,每个智能体要么返回其保存的结果,要么再次运行:
- 已完成:返回其已保存的结果。第一个提示词与上一次运行不同的智能体——因为你编辑了脚本,或较早的智能体返回了不同内容——会再次运行,它之后的每个智能体也会再次运行,即使是已经完成的智能体。
- 停止时仍在运行:会从头开始。停止整个运行不会将任何智能体计为失败。
- 失败:会再次运行,在它之后启动的每个智能体也会再次运行,即使它们已经完成。单独停止一个智能体,即在
/workflows中选择该智能体并按x,会被视为失败。
最后一种情况意味着,扇出中途的失败会重跑已经完成的工作。如果一个脚本按 A、B、C、D 的顺序启动,而 B 失败,重新启动会从缓存返回 A,并再次运行 B、C、D。
如果你编辑一个曾启动 A、B、C、D 的脚本,使其启动 A、C、B、D,那么第二个启动的智能体现在是 C,而上一次运行启动的是 B。重新启动会从缓存返回 A,并再次运行 C、B、D。
离开会话后恢复
你可以在同一个 Claude Code 会话内恢复一次运行。当你离开会话时,正在运行的工作流会怎样,取决于你离开的方式:
- 如果你将会话转入后台,Claude Code 会在后台会话中以相同方式重放这次运行并继续执行。
- 如果你在工作流运行期间退出 Claude Code,并且智能体视图已开启,退出对话框会提供
Move to background and exit,它会以相同方式延续这次运行。如果你选择Exit and stop tasks,或者没有提供该选项,这次运行会随会话一起停止。Claude Code 会将这次运行的已保存结果保留在该会话的目录下,该目录位于~/.claude/projects/,因此你用claude --resume恢复的会话,可以在你要求 Claude 重新启动工作流时重放这些结果。在你全新启动的会话中,Claude 没有可重新启动的先前运行,因此会将工作流作为一次新的运行重新开始。
在云会话中,Claude Code 还会将运行结果与会话的对话历史一起保存,即使会话的 VM 被回收,这些内容也会保留下来。当你重新打开这样的会话并要求 Claude 重新启动工作流时,已完成的智能体仍会返回其保存的结果。
无论本地会话还是云会话,当 Claude 重新启动一次较早的运行,而 Claude Code 完全找不到该运行保存的结果时,重新启动会失败,并返回一个 nothing to resume 错误,而不是自行从头开始该运行。请让 Claude 将该工作流作为一次新运行重新开始。
当运行达到你的用量限制时
当某个智能体触及你的 claude.ai 用量限制时,运行会暂停,而不是让该智能体失败:触及限制的智能体会等待重置,并且不会启动新的智能体。限制重置后不久,等待中的智能体会再次运行,运行会自行继续。需要 Claude Code v2.1.271 或更高版本;在更早版本中,受影响的智能体会失败。
在运行等待期间,任务面板中的进度行以及/workflows标题会显示限制何时重置。
仅当以下条件全部成立时,运行才会暂停;如果有一项不成立,受影响的智能体会改为失败:
- 会话是交互式的,并且已通过 claude.ai 订阅登录。在以下情形中,运行不会暂停:非交互模式下使用
claude -p或Agent SDK时,在后台会话中,或在远程控制或智能体团队队友会话中。 autoContinueAtUsageLimit已开启,这是让会话自身等待用量限制重置的同一项设置。如果你在等待期间将其关闭,等待会结束,等待中的智能体将失败。- 该限制会在 24 小时内重置。每周限制可能要到更晚才会重置。
- 本次运行尚未等待过两次。当它第三次触及该限制时,智能体会失败。
当智能体停滞并重新启动时
如果某个智能体的输出停止到达的时间足够长,它就会从同一提示重新开始。在/workflows中,其名称会增加一个 (retry 1) 后缀,详细信息会显示 attempt 2 (stalled)。重启是自动的,因此你无需进行任何操作。
新一次尝试开始时不会包含停滞尝试的转录记录。停滞尝试已经更改的文件会保持已更改状态,它消耗的 token 仍会计入该运行的总量。停滞窗口是指 Claude Code 在结束该尝试之前等待智能体输出的时长。智能体等待自身工具调用或等待用量限制重置所花的时间不计入停滞窗口。
一个智能体最多重启五次,其中计入你通过 r请求的任何重启。如果第六次尝试也停滞,那么 agent() 调用会失败,错误开头会说明原因:
agent stalled on all 6 attempts:每次尝试在整个窗口期内都没有任何输出。如果智能体的工作会使其静默那么久,请延长该窗口agent lost its reply on all 6 attempts:每次尝试的响应流都归于静默,Claude Code 因此放弃了等待。延长停滞窗口没有帮助,因为流式空闲看门狗先结束了该响应,而CLAUDE_STREAM_IDLE_TIMEOUT_MS用于设置该看门狗的超时时间agent abandoned after 6 attempts:这些尝试以不同方式结束,错误信息会按顺序列出这些方式
为了让智能体在停滞窗口结束前有更多时间生成输出:
- 单个智能体:传入
stallMs(单位为毫秒),用于该智能体的agent()调用,例如agent(prompt, { stallMs: 1800000 })表示 30 分钟 - 每个智能体:设置
CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS,这同样适用于工作流之外的子智能体
失败后运行是否继续,取决于你的脚本如何调用智能体:
- 发生在
parallel()或pipeline()内部时:本次运行会继续,并以null替代该智能体的结果 - 直接 await:本次运行会以该错误结束
要重试,请让 Claude 重新启动工作流。暂停后恢复介绍了哪些内容会再次运行。
成本
工作流会生成许多智能体,因此单次运行使用的 token 可能明显多于在对话中完成同一任务。运行会计入你套餐的用量和速率限制。
要在投入大型任务前估算开销,请先在一个小范围上运行工作流:用一个目录代替整个仓库,或用范围更窄的问题代替宽泛的问题。/workflows 视图会显示每个智能体在运行过程中的 token 使用情况,并且你可以随时在那里停止运行,通常不会丢失已完成的工作。暂停后恢复介绍了停止的运行会保留哪些内容。运行时的智能体上限限制了单次运行可以生成的智能体数量,从而限制失控脚本造成的成本。要减少每次运行中的智能体数量,请选择 small 规模指南。
Claude Code 还会标记规模异常增大的运行。当工作流调度超过 25 个智能体,或其预计 token 总量超过 150 万时,该运行在输入框下方任务面板中的进度行会显示 Large workflow 警告。该警告会指引你前往/workflows,你可以在那里停止运行。
该警告仅供参考:它不会暂停或限制运行。有两项设置会改变你看到它的时机:
- 如果你自己选择一个规模指南,其中的智能体数量会取代 25 个智能体的阈值。内置默认指南会让该阈值保持在 25。
- 启用了ultracode的会话不会显示该警告,因为开启 ultracode 本身就已让你选择加入大型运行。
Claude Code 会采用与为子智能体选择模型时相同的顺序,为每个工作流智能体选择模型。脚本为某个阶段指定的模型,在该顺序中算作单次调用的模型。当没有其他设置指定模型时,智能体会使用你会话的模型运行。
要控制模型成本:
- 在大型运行前检查
/model,前提是你通常会在处理日常工作时切换到更小的模型 - 在描述任务时,请要求 Claude 对不需要最强模型的阶段使用较小的模型
当你组织的availableModels 允许列表阻止脚本为某个智能体请求的模型时,该智能体会改用替代模型运行,并遵循与子智能体相同的替换规则。
设置规模指南
规模指南会告诉 Claude 在编写动态工作流时应以多少个智能体为目标。Claude Code 会将指南作为建议而非上限发送给 Claude,因此要求不同规模的提示词仍会覆盖它。
每个值对应一个智能体数量:
| 值 | Claude 力求达到的智能体数量 |
|---|---|
unrestricted | 没有规模指南:Claude 会根据任务调整工作流规模 |
small | 少于 5 个智能体 |
medium | 少于 10 个智能体 |
large | 少于 50 个智能体 |
默认值为 medium;如果你在 Claude Code v2.1.271 或更高版本上登录 Pro 套餐,则为 small。在你选择某个值之前,/config 行会将该值标记为默认值,工作流的 Running in background 行会说明当前生效的规模。需要 Claude Code v2.1.219 或更高版本;更早的版本默认为 unrestricted。
要更改该指南,请在 /config中为 Dynamic workflow size 设置选择一个值,或运行 /config workflowSizeGuideline=small。在 v2.1.219 及更高版本中,你还可以在任何设置文件中设置workflowSizeGuideline 键;该值优先于 /config,并且 Claude Code 会隐藏 /config 行,只要设置文件提供了该值。
更改会在下一个提示词生效。运行时智能体上限仍会应用,不受该设置影响。
关闭工作流
工作流可在 CLI、桌面应用、IDE 扩展、非交互模式中与 claude -p一起使用,也可在Agent SDK中使用。相同的禁用设置适用于所有界面。
要为自己关闭工作流:
- 在
/config中关闭动态工作流。该设置会在各会话之间保留。 - 将
"disableWorkflows": true写入~/.claude/settings.json。该设置会在各会话之间保留。 - 设置
CLAUDE_CODE_DISABLE_WORKFLOWS=1。该变量在启动时读取,因此无论你在哪里设置它都会生效。
要为整个组织关闭工作流,请将 "disableWorkflows": true 设置于托管设置中,或使用Claude Code 管理员设置页面上的开关。
关闭工作流后:
/workflows、工作流命令以及/workflow-authoring技能都不可用- 关键词
ultracode不再触发运行,并且 Ultracode 开关已从以下设置中移除:/effort
已经开始的运行会继续执行。
关闭工作流还会使ultracode不可用。没有任何托管设置会单独禁用 ultracode:凡是它可用的地方,用户都可以运行以下命令来开启它:/effort ultracode。投入等级上限会降低开启 ultracode 的会话的投入等级,但不会关闭 ultracode。