1. 为什么我要把 Agent 流程从提示词搬进 settings.json
Claude 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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 端点为 https://taotoken.net/api 。
你需要先拿到一个 API Key。操作路径：登录后进入控制台，在 API Keys 页面创建一个新 Key。地址是 https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_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: "你是性能审查专家，关注时间复杂度、内存分配、N+1 查询、缓存失效。", 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_WORKFLOW=1 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 的状态都是completed，Token 消耗有具体数值。
如果 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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。
7. 把配置和脚本沉淀成团队资产
跑通一次之后，建议把.claude/settings.json和.claude/workflows/一起提交到 Git 仓库。settings.json 里的${ANTHROPIC_AUTH_TOKEN}保持环境变量引用，不要写死 Key。团队成员 clone 后，只需要在本地 export 自己的 Key，就能复现同一套 Workflow。
如果你需要更细的接入文档，可以参考 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。想直接验证模型对话效果，可以用 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。长期跑编码类 Agent 任务的话，Coding Plan 页面在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。
最后一个小技巧：Workflow 脚本默认存在临时目录，生命周期三天。如果你调好了一个脚本，直接让 Claude Code 复制到.claude/workflows/下，下次用ultra work 调用 <脚本名>就能直接复用，不用重新生成。脚本里的metadata.name就是调用时的脚本名，保持简短好记。
