1. 为什么我要把 Agent 流程从提示词搬进 settings.jsonClaude Code 的 Workflow 功能简单说就是让你用 JavaScript 脚本显式定义多 Agent 协作流程而不是靠自然语言临时“派活”。它适合谁适合那些已经被“同一个 Prompt 跑出不同结果”折磨过的开发者——你写了一个看起来很完美的审查指令第一次跑得挺好第二次模型换了条路径第三次干脆漏掉了安全检查。Workflow 把阶段、Agent 角色、执行顺序、结果聚合全部固化成代码可观测、可复跑、可分享。但真正落地到项目里光会写 Workflow 脚本还不够。你还需要一个稳定的配置骨架让 Claude Code 每次启动时自动加载正确的模型端点、MCP 服务、权限策略。这就是 settings.json 的价值——它相当于整个 Agent 工作流的“启动清单”。我试过把 settings.json、MCP 配置和 Workflow 脚本串起来之后团队里任何人 clone 仓库、跑一条命令就能复现同一套多 Agent 审查流程不再依赖某个人本地环境里的临时配置。这篇内容会从 settings.json 的配置骨架出发串联 MCP 服务接入与 JavaScript Agent 脚本编排给出可复制的配置片段并演示一次完整工作流触发与结果验证。核心检索词Claude Code Workflow、settings.json、MCP、JavaScript Agent。2. 前置准备TaoToken 接入与 Claude Code 环境在写 settings.json 之前需要先确认模型调用链路是通的。Claude Code 本身是一个客户端它需要指向一个兼容 Anthropic API 的服务端点。这里用 TaoToken 作为接入层官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点为 https://taotoken.net/api 。你需要先拿到一个 API Key。操作路径登录后进入控制台在 API Keys 页面创建一个新 Key。地址是 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。创建时建议给 Key 起一个能识别用途的名字比如claude-code-workflow-dev方便后续轮换。拿到 Key 之后不要直接硬编码在 settings.json 里。推荐用环境变量注入settings.json 中通过${ANTHROPIC_AUTH_TOKEN}引用。这样配置文件可以进 Git 仓库Key 留在本地 shell 或 CI 的 secret 里。如果你还没安装 Claude Code先通过 npm 全局安装npm install -g anthropic-ai/claude-code安装完成后验证版本claude --version确认版本在 V2.1.47 及以上因为 Workflow 功能是在这个版本区间加入的。如果版本过低先升级再继续。3. settings.json 配置骨架从零搭出可复现结构Claude Code 的 settings.json 可以放在项目级.claude/settings.json也可以放在用户级~/.claude/settings.json。项目级配置会覆盖用户级适合团队共享。下面是一个完整的项目级配置骨架包含模型端点、权限策略、MCP 服务注册和 Workflow 相关环境变量。{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: ${ANTHROPIC_AUTH_TOKEN}, ANTHROPIC_WORKFLOW: 1, ANTHROPIC_MODEL: claude-sonnet-4-20250514 }, permissions: { allow: [ Read, Write, Bash(git diff:*), Bash(git log:*), Bash(npm test:*), mcp__filesystem__read_file, mcp__filesystem__list_directory ], deny: [ Bash(rm -rf:*), Bash(curl:*) ] }, mcpServers: { filesystem: { command: npx, args: [ -y, modelcontextprotocol/server-filesystem, ${workspaceFolder} ] }, git: { command: npx, args: [ -y, modelcontextprotocol/server-git, --repository, ${workspaceFolder} ] } }, workflow: { scriptDir: .claude/workflows, tempDir: /tmp/claude-workflows, maxParallelAgents: 4, defaultTimeout: 300000 } }几个关键点说明。ANTHROPIC_WORKFLOW设为1是启用 Workflow 功能的开关没有这个环境变量ultra work关键词不会触发脚本生成。ANTHROPIC_BASE_URL指向 TaoToken 的 API 端点ANTHROPIC_AUTH_TOKEN从环境变量读取避免明文泄露。permissions.allow里我显式放行了mcp__filesystem__read_file和mcp__filesystem__list_directory这样 Workflow 脚本里的 Agent 才能通过 MCP 读取项目文件。deny里禁掉了rm -rf和curl防止 Agent 在自动化流程中执行危险操作。mcpServers注册了两个服务filesystem 和 git。filesystem 让 Agent 能读写工作目录git 让 Agent 能查看 diff、log、branch 信息。这两个是代码审查类 Workflow 最常用的 MCP 服务。workflow.scriptDir指定了 Workflow 脚本的存放目录我设为.claude/workflows这样脚本可以随项目一起提交到 Git团队成员共享。maxParallelAgents设为 4控制并行 Agent 数量避免一次性打满 API 配额。配置写完后在项目根目录执行一次验证export ANTHROPIC_AUTH_TOKEN你的Key claude --settings .claude/settings.json --print 列出当前目录文件如果返回了文件列表说明 settings.json 加载成功模型端点和 MCP 服务都通了。4. MCP 服务接入与 JavaScript Agent 脚本编排MCP 服务注册好之后Workflow 脚本里的 Agent 就可以通过tools字段引用这些服务。下面是一个完整的 Workflow 脚本示例放在.claude/workflows/pr-review.js实现 PR 多维度审查。export default { metadata: { name: pr-review, description: 多 Agent 并行 PR 审查安全、性能、可读性、架构四个维度 }, stages: [ { id: review, description: 四个专业审查 Agent 并行运行, parallel: true, agents: [ { id: security, tools: [mcp__git__diff, mcp__filesystem__read_file], systemPrompt: 你是安全审查专家关注注入、越权、敏感信息泄露、依赖漏洞。, prompt: 审查当前 PR 的 diff列出所有安全问题按严重程度排序。, maxTokens: 3000, temperature: 0.1 }, { id: performance, tools: [mcp__git__diff, mcp__filesystem__read_file], systemPrompt: 你是性能审查专家关注时间复杂度、内存分配、N1 查询、缓存失效。, prompt: 审查当前 PR 的 diff列出性能隐患和优化建议。, maxTokens: 3000, temperature: 0.2 }, { id: readability, tools: [mcp__git__diff], systemPrompt: 你是代码可读性审查专家关注命名、注释、函数长度、重复代码。, prompt: 审查当前 PR 的 diff给出可读性改进建议。, maxTokens: 2000, temperature: 0.3 }, { id: architecture, tools: [mcp__git__diff, mcp__filesystem__list_directory], systemPrompt: 你是架构审查专家关注模块边界、依赖方向、接口稳定性。, prompt: 审查当前 PR 的 diff评估架构影响和潜在耦合问题。, maxTokens: 3000, temperature: 0.2 } ] }, { id: verify, description: 交叉验证四个审查结果标记矛盾, dependsOn: [review], parallel: false, agents: [ { id: validator, tools: [], systemPrompt: 你是严格的技术评审员负责对比多个审查结果识别误报和矛盾。, prompt: 对比以下四个审查 Agent 的输出 1. security 2. performance 3. readability 4. architecture 输出一致确认的问题、相互矛盾的点、需要人工复核的项。, maxTokens: 4000, temperature: 0.0 } ] }, { id: report, description: 生成最终审查报告, dependsOn: [verify], parallel: false, agents: [ { id: writer, tools: [], systemPrompt: 你是技术报告撰稿人擅长将多源审查结果整合成可执行的 PR 评论。, prompt: 基于 verify 阶段的输出生成一份 Markdown 格式的 PR 审查报告包含问题清单、严重程度、修复建议。, maxTokens: 5000, temperature: 0.2 } ] } ], return: async (context) { const report context.stages.report.agents.writer.output; await context.saveFile(pr-review-report.md, report); return { summary: PR 审查完成, reportPath: pr-review-report.md, issueCount: context.stages.verify.agents.validator.output.length }; } };这个脚本定义了三个阶段review 阶段四个 Agent 并行跑verify 阶段做交叉验证report 阶段生成最终报告。每个 Agent 通过tools字段引用 MCP 服务mcp__git__diff来自 git MCP 服务mcp__filesystem__read_file来自 filesystem MCP 服务。脚本写好后在 Claude Code 中触发export ANTHROPIC_WORKFLOW1 claude进入交互界面后输入ultra work 调用 pr-review 脚本审查当前分支相对 main 的 diffClaude Code 会加载.claude/workflows/pr-review.js按脚本定义的阶段和 Agent 执行。你可以输入/workflows进入可视化监控界面查看每个阶段的进度、每个 Agent 的耗时和 Token 消耗。5. 验证请求与成功结果一次完整工作流触发为了验证整个链路我准备了一个包含小改动的测试分支。改动内容是一个简单的 Express 路由故意留了一个 SQL 拼接的写法方便安全 Agent 发现问题。触发命令git checkout -b test/pr-review-demo # 修改 routes/user.js加入一个不安全的查询 git add routes/user.js git commit -m test: add unsafe query for workflow demo然后在 Claude Code 中执行ultra work 调用 pr-review 脚本审查当前分支相对 main 的 diff预期结果Claude Code 先输出一段脚本加载日志然后进入 review 阶段。四个 Agent 并行运行大约 30 到 60 秒后完成。接着 verify 阶段启动validator Agent 对比四个结果。最后 report 阶段生成pr-review-report.md。成功标志有三个。第一终端出现Workflow pr-review completed字样。第二项目根目录生成了pr-review-report.md打开后能看到安全 Agent 标记的 SQL 注入风险。第三/workflows界面里每个 Agent 的状态都是completedToken 消耗有具体数值。如果 report 文件里安全部分明确写了“routes/user.js 存在 SQL 拼接建议使用参数化查询”说明 MCP 的 git diff 读取和 filesystem 读取都正常工作Workflow 编排链路完整。6. 本篇常见错排查报错一ANTHROPIC_WORKFLOW未生效ultra work无反应。检查 settings.json 的env字段里是否写了ANTHROPIC_WORKFLOW: 1。注意值必须是字符串1不是数字1。另外确认 Claude Code 版本在 V2.1.47 以上低版本不支持。报错二MCP 服务启动失败提示command not found: npx。确认 Node.js 和 npm 已安装npx在 PATH 中。如果用的是 pnpm 或 yarn把command改成对应路径或者直接用绝对路径。报错三Workflow 脚本里tools引用的 MCP 方法不存在。MCP 方法名格式是mcp__serverName__toolName。比如 filesystem 服务注册名为filesystem工具名为read_file完整引用是mcp__filesystem__read_file。检查 settings.json 里mcpServers的 key 和脚本里tools的拼写是否一致。报错四Agent 输出为空或超时。检查maxTokens是否设得太小复杂审查任务建议不低于 3000。另外workflow.defaultTimeout默认 300000 毫秒如果任务特别重可以调到 600000。报错五pr-review-report.md没有生成。检查return函数里context.saveFile的路径是否有写权限。如果项目目录只读改成/tmp下的路径测试。报错六并行 Agent 数量超过 API 限流。把workflow.maxParallelAgents从 4 降到 2或者在 TaoToken 控制台确认当前 Key 的并发配额。地址是 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。7. 把配置和脚本沉淀成团队资产跑通一次之后建议把.claude/settings.json和.claude/workflows/一起提交到 Git 仓库。settings.json 里的${ANTHROPIC_AUTH_TOKEN}保持环境变量引用不要写死 Key。团队成员 clone 后只需要在本地 export 自己的 Key就能复现同一套 Workflow。如果你需要更细的接入文档可以参考 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。想直接验证模型对话效果可以用 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。长期跑编码类 Agent 任务的话Coding Plan 页面在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后一个小技巧Workflow 脚本默认存在临时目录生命周期三天。如果你调好了一个脚本直接让 Claude Code 复制到.claude/workflows/下下次用ultra work 调用 脚本名就能直接复用不用重新生成。脚本里的metadata.name就是调用时的脚本名保持简短好记。