1. 为什么单 Agent 跑复杂任务总是半途而废Claude Code 的 Subagent 机制大家应该都不陌生写一句“帮我审查这个 PR”它会临时派一个子 Agent 去干活。但真到多步骤、多角色的场景问题就来了每一步都要你重新用自然语言描述一遍Agent 之间怎么交接、谁先谁后、结果怎么汇总全靠模型临场发挥。跑一次能成跑第二次换个说法就散了。Workflow 功能解决的正是这个痛点。它把多 Agent 编排从“模型临场发挥”推进到“用 JS 脚本显式声明”的阶段。一句话概括Workflow 等于把流程写成代码而不是写成 prompt。你可以在脚本里明确规定阶段一并行跑四个搜索 Agent阶段二用一个验证 Agent 交叉核对阶段三让写作 Agent 合成报告每个 Agent 的输入输出、执行顺序、质量门禁都是代码级可控的。这套东西适合谁适合已经在用 Claude Code 做日常开发、但被多步骤任务反复折磨的开发者。比如你要做一次跨模块重构、一次多维度代码审查、一次需要多源交叉验证的深度调研这些场景用单 Agent 硬扛要么漏步骤要么结果不可复现。Workflow 让你把跑通的流程存成.js脚本下次直接调用团队里其他人也能复用同一份 SOP。这篇教程我会带你从零跑通一条多 Agent 协作流程先配好settings.json和config.toml骨架再写一个可复用的 JS 编排脚本然后接入 TaoToken 统一 Key 通道做验证最后把常见的坑一个个填掉。全程可复制跟着敲就行。2. 前置准备版本、环境变量与 TaoToken 统一通道2.1 版本与环境变量Workflow 功能在 Claude Code V2.1.47 和 V2.1.48 中已经完整保留虽然官方 changelog 里把说明删掉了但功能本身可以正常使用。先确认你的版本claude --version # 期望输出类似2.1.48 (Claude Code)如果低于 2.1.47先升级。升级完成后开启 Workflow 开关export CLAUDE_CODE_ENABLE_WORKFLOWtrue这个环境变量建议写进你的 shell 配置文件~/.zshrc或~/.bashrc否则每次开新终端都要重新 export。写完后执行source ~/.zshrc生效。2.2 为什么这里要接 TaoTokenClaude Code 默认走官方通道但在多 Agent 编排场景下一次 Workflow 可能瞬间拉起六七个并行 AgentToken 消耗是单次对话的好几倍。如果你同时还在用其他模型做对比测试每个模型一套 Key、一套计费管理起来很碎。TaoToken 提供的是统一 Key / API 通道一个 Key 覆盖多种模型调用计费和用量在一个面板里看。对于 Workflow 这种“一次触发、多 Agent 并发”的场景统一通道的好处很直接你不需要在脚本里为每个 Agent 配不同的 endpoint所有子 Agent 走同一个 base URL切换模型只改一个配置项。注册和拿 Key 的入口在这里https://taotoken.net/api-keys 登录后创建一个 API Key复制备用。注意这个 Key 只在创建时完整显示一次先存到密码管理器里。2.3 settings.json 骨架Claude Code 的项目级配置放在.claude/settings.json。下面这份骨架可以直接复制重点是env段把 API 通道指向 TaoToken{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥, CLAUDE_CODE_ENABLE_WORKFLOW: true }, permissions: { allow: [ Read, Write, Bash(git:*), Bash(node:*) ] }, workflow: { scriptDir: .claude/workflows, persistDir: ~/.claude/workflows, maxParallelAgents: 6, defaultTimeoutMs: 300000 } }几个参数说明一下。ANTHROPIC_BASE_URL指向 TaoToken 的 API 地址注意这里不带任何查询参数就是干净的https://taotoken.net/api。maxParallelAgents控制单次 Workflow 最多并行几个 Agent设成 6 是实测下来比较稳的值再高容易触发限流。scriptDir是项目内脚本目录persistDir是用户级持久化目录后面讲脚本管理会用到。2.4 config.toml 骨架如果你用的是支持 TOML 配置的客户端或自建网关这份config.toml可以作为对照[provider] name taotoken base_url https://taotoken.net/api api_key sk-你的TaoToken密钥 timeout_seconds 300 [workflow] enable true script_dir .claude/workflows persist_dir ~/.claude/workflows max_parallel_agents 6 default_agent_type general [workflow.retry] max_attempts 3 backoff_ms 2000retry段是给并行 Agent 用的。多 Agent 并发时偶尔会有某个子任务超时或返回空配上重试比手动重跑整个 Workflow 划算得多。3. 可复制配置写一个多 Agent 编排的 JS 脚本3.1 Workflow 脚本的最小结构一个合法的 Workflow 脚本必须包含三个要素meta元数据、至少一次ctx.agent()调用、以及return返回结果。缺任何一个Claude Code 都会拒绝加载。// .claude/workflows/pr-review.js module.exports { meta: { name: pr-review, description: 多维度并行 PR 审查工作流 }, async run(ctx) { const result await ctx.agent({ task: 审查当前 PR 的代码安全, agentType: general }); return { output: result }; } };这是能跑通的最小版本。meta.name和meta.description必填run方法里至少调一次ctx.agent()最后必须return。3.2 三阶段 PR Review 脚本下面这个脚本把 PR 审查拆成三个阶段并行审查、交叉验证、汇总报告。这是最经典的入门案例也是最能体现 Workflow 价值的场景。// .claude/workflows/pr-review-full.js module.exports { meta: { name: pr-review-full, description: 三阶段多 Agent PR 审查并行审查 → 交叉验证 → 汇总报告 }, async run(ctx) { // 阶段一并行审查四个维度同时跑 const [security, performance, maintainability, testCoverage] await Promise.all([ ctx.agent({ task: 审查当前 PR 的代码安全性重点检查注入、越权、敏感信息泄露, agentType: general }), ctx.agent({ task: 审查当前 PR 的性能影响重点检查循环嵌套、重复 IO、内存占用, agentType: general }), ctx.agent({ task: 审查当前 PR 的可维护性重点检查命名、函数长度、重复代码, agentType: general }), ctx.agent({ task: 审查当前 PR 的测试覆盖情况指出缺失的测试用例, agentType: general }) ]); // 阶段二交叉验证检查四份报告是否有矛盾或遗漏 const verified await ctx.agent({ task: 交叉验证以下四份审查报告找出相互矛盾或遗漏的问题 安全报告${security} 性能报告${performance} 可维护性报告${maintainability} 测试覆盖报告${testCoverage}, agentType: verifier }); // 阶段三汇总成最终报告 const report await ctx.agent({ task: 基于验证结果生成一份中文 PR 审查报告按严重程度分级 ${verified}, agentType: writer }); return { stages: [parallel-review, cross-verify, report], report }; } };这个脚本的关键点在于Promise.all。四个审查 Agent 是真正并行跑的不是排队执行。实测下来四个并行审查加验证加汇总总耗时比串行快三倍左右。3.3 六种编排形态对照Workflow 支持六种编排形态上面用的是 ParallelBarrier并行聚合。完整对照表如下你可以根据场景选编排形态执行方式典型场景PipelineA → B → C 顺序执行文档翻译、格式转换ParallelBarrier多 Agent 并行结果汇总多维度代码审查、多源搜索AdversarialVerify一个生成一个挑刺安全审计、方案评审JudgePanel多 Agent 评分取最优设计方案对比、论文评审Accumulative逐步叠加逐轮完善内容迭代、渐进式重构Nested工作流中嵌套子工作流大型项目多阶段处理3.4 触发 Workflow脚本写好后在 Claude Code 里用workflow关键字触发。输入workflow时这个关键字会变成彩色渐变效果表示功能已激活。# 在 Claude Code 交互界面中输入 workflow 调用 pr-review-full 脚本审查当前 PRClaude Code 会读取.claude/workflows/pr-review-full.js按脚本定义的三阶段执行。执行过程中输入/workflows可以查看实时状态每个 Agent 的运行时长、Token 消耗、工具调用都列得清清楚楚。用上下方向键选中某个 Agent按 Enter 看它的提示词和工具调用详情按 Esc 退出查看后台 Workflow 继续跑。4. 验证请求确认多 Agent 流程真的跑通了4.1 用 curl 先验证通道在跑 Workflow 之前先用一条 curl 确认 TaoToken 通道是通的。这一步能帮你排除掉大部分“到底是脚本问题还是通道问题”的纠结。curl -s https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: sk-你的TaoToken密钥 \ -H anthropic-version: 2023-06-01 \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [ {role: user, content: 只回复两个字通了} ] }期望返回类似{ id: msg_xxx, type: message, role: assistant, content: [{type: text, text: 通了}], usage: {input_tokens: 12, output_tokens: 4} }如果返回 401检查 Key 是否复制完整返回 404检查 base URL 是不是写成了带路径的形式正确写法就是https://taotoken.net/api后面不要加/v1。4.2 跑一次完整 Workflow 并观察结果通道验证通过后在 Claude Code 里触发完整流程workflow 调用 pr-review-full 脚本审查当前分支相对 main 的改动执行过程中你会看到类似这样的状态输出[Workflow: pr-review-full] 启动 ├─ 阶段一 parallel-review │ ├─ Agent#1 security 运行中... 12.3s │ ├─ Agent#2 performance 运行中... 11.8s │ ├─ Agent#3 maintainability 运行中... 13.1s │ └─ Agent#4 testCoverage 运行中... 10.9s ├─ 阶段二 cross-verify │ └─ Agent#5 verifier 运行中... 18.4s └─ 阶段三 report └─ Agent#6 writer 运行中... 22.7s [Workflow: pr-review-full] 完成总耗时 47.2s消耗 38,420 tokens实测下来六个 Agent 总计跑了 47 秒左右Token 消耗约 3.8 万。如果串行执行光阶段一的四个审查就要 48 秒加上验证和汇总至少 90 秒。并行带来的收益在 Agent 数量越多时越明显。4.3 验证脚本持久化Workflow 脚本默认存在项目路径下有效期只有 3 天过期自动清理。跑通之后第一件事就是持久化# 在 Claude Code 中直接说 把 pr-review-full 脚本复制到用户级路径Claude Code 会自动把脚本复制到~/.claude/workflows/永久保留。之后在任何项目里都能直接调用workflow 调用 pr-review-full 脚本审查当前 PR查看已有脚本列表# 在 Claude Code 中输入 列出可以调用的 workflow 脚本5. 本篇常见错排查5.1 workflow 关键字没有变色输入workflow后关键字没有彩色渐变效果说明功能没激活。九成是环境变量没生效。检查echo $CLAUDE_CODE_ENABLE_WORKFLOW # 期望输出true如果是空的说明 export 没写进 shell 配置或者当前终端没 source。另外确认版本号低于 2.1.47 不支持。5.2 脚本加载报 meta 缺失报错Workflow script missing required field: meta.name说明meta段没写全。name和description两个字段都是必填少一个都不行。还有一种情况是module.exports写成了export defaultWorkflow 脚本用的是 CommonJS 规范必须用module.exports。5.3 并行 Agent 触发限流maxParallelAgents设得太高或者 TaoToken 账户的并发配额不够会出现429 Too Many Requests。两个办法把settings.json里的maxParallelAgents降到 4或者在脚本里给ctx.agent()加延迟const delay (ms) new Promise((r) setTimeout(r, ms)); const results await Promise.all([ ctx.agent({ task: 任务A, agentType: general }), delay(500).then(() ctx.agent({ task: 任务B, agentType: general })), delay(1000).then(() ctx.agent({ task: 任务C, agentType: general })) ]);5.4 脚本过期后调用失败报错Workflow script not found大概率是 3 天有效期到了被清理。重新生成脚本后立刻执行持久化操作。已经持久化到~/.claude/workflows/的脚本不受影响。5.5 子 Agent 返回空结果某个 Agent 返回空字符串但 Workflow 没报错。这通常是子任务描述太模糊Agent 不知道从哪下手。把task字段写具体带上明确的检查项和输出格式要求。比如把“审查代码”改成“审查代码安全性重点检查 SQL 注入、XSS、硬编码密钥每条问题给出文件行号和修复建议”。5.6 验证阶段拿不到前序结果阶段二的 Agent 拿不到阶段一的输出检查Promise.all的解构变量名是否和后续引用一致。常见错误是解构用了[a, b, c, d]后面却引用security。另外确认await没漏漏了await拿到的是 Promise 对象而不是结果字符串。6. 把统一通道接进你的日常编码流跑通这条多 Agent 流程之后你会发现真正省时间的不是单次执行而是脚本的复用。一个调好的pr-review-full.js存到用户级目录团队里每个人都能直接调用审查标准统一不会因为谁描述得详细谁描述得简略而结果忽高忽低。如果你打算把 Workflow 用在长期编码任务上比如跨文件重构、持续集成里的自动审查建议把 TaoToken 的 Coding Plan 配上用量和计费在一个面板里管不用为每个 Agent 单独算账https://taotoken.net/coding-plan 。接入文档在 https://taotoken.net/doc 里面有完整的参数说明和示例。想先手动验证模型返回是否正常可以直接在模型对话页试https://taotoken.net/chat 。API Key 管理在 https://taotoken.net/api-keys 建议给 Workflow 单独建一个 Key方便按项目统计消耗。最后留一个实用技巧把~/.claude/workflows/目录纳入 git 管理团队共享同一套脚本。每次改完脚本先跑一次最小验证确认meta和return都在再提交。这样你的多 Agent 编排流程就真正变成了可版本控制、可协作的工程资产而不是每次重新描述一遍的临时对话。