标题claude-sonnet-5 Claude Code MCP Server 配置教程subagents 权限的三处隐藏差异附 claude-opus-4.8 对比正文上周三我给团队的 Claude Code 升级底层模型到 claude-sonnet-5MCP Server 配起来只花了 15 分钟——但之后 subagents 死活不执行 tool call不报错、不超时、日志里一切正常就是什么都不干。折腾了大半天才发现是 JSON schema 里的权限字段写法变了。结论先放这里claude-sonnet-5API ID:claude-sonnet-4-5的 MCP Server subagents 配置和 claude-opus-4.8 有三处不同——tool_call_budget是新增必填参数allowed_tools从白名单改成了黑名单模式max_turns默认值从 25 降到了 10。前两处 Anthropic 文档有写但藏得很深第三处截至 2026 年 7 月 2 号文档根本没提。如果你从 opus-4.8 配置直接复制过来用agent loop 会静默失败。这篇适合谁已经在用 Claude Code CLI想把它当 MCP Server 给其他客户端调用的开发者正在从 claude-opus-4.8 迁移到 claude-sonnet-5 的团队成本考虑——输入价差 5 倍配了 subagents 但发现 tool call 不执行、不报错的人大概率就是这个坑用 Cline / Cherry Studio 等工具通过 MCP 协议接 Claude Code 的场景整体流程安装 Claude Code CLI 并验证可执行配置 API Key直连或通过聚合网关编写claude_desktop_config.json注册 MCP Server配置 subagents 权限字段本文重点用 MCP Inspector 验证工具列表和权限生效联调测试 tool call 是否正常执行graph LR A[安装 claude-code] -- B[配置 API Key] B -- C[写 MCP Server JSON] C -- D[配 subagents 权限] D -- E[Inspector 验证] E -- F[联调 tool call]三处差异对比字段claude-opus-4.8 写法claude-sonnet-5 写法不匹配后果tool_call_budget不存在/可省略必填整数单位为调用次数agent loop 静默跳过所有 tool callallowed_tools白名单模式只列允许的黑名单模式*denied_tools工具列表为空subagent 无可用工具max_turns默认 25默认 10文档未标注复杂任务中途截断无报错无提示第一步安装 Claude Code 并确认 PATHnpm install -g anthropic-ai/claude-code claude --version如果claude --version能正常输出版本号就没问题。Windows 用户注意——报spawn claude ENOENT大概率是 npm 全局路径没加到系统 PATH 里。第二步配置 API Key两种方式选一个。直连 Anthropic 官方export ANTHROPIC_API_KEYsk-ant-xxxxx claude mcp serve如果你需要通过聚合网关走比如团队统一管控 Key 和用量审计可以用 OpenRouter、ofox.io 这类平台改 base_url 就行。ofox 是 0% 加价对齐官方定价OpenRouter 约 5–10% 加价具体因模型而异按需选。验证连通性最快的方法——跑一下 SDK 调用import Anthropic from anthropic-ai/sdk; const client new Anthropic(); const msg await client.messages.create({ model: claude-sonnet-4.5, max_tokens: 128, messages: [{ role: user, content: ping }] });注意这里 model 填的是claude-sonnet-4-5不是claude-sonnet-5。Anthropic 的营销名和 API ID 不一样社区已经吐槽了无数次。第三步注册 MCP ServermacOS 配置文件路径~/Library/Application Support/Claude/claude_desktop_config.json{ mcpServers: { claude-code: { command: npx, args: [-y, anthropic-ai/claude-code, mcp, serve], env: { ANTHROPIC_API_KEY: sk-ant-xxxxx } } } }用npx -y而不是直接调claude命令的好处是不依赖全局安装状态-y即--yes自动同意安装提示——stdio 模式下任何非 JSON 的输出都会污染通信流导致MCP Error: Invalid JSON in server response。第四步subagents 权限配置核心差异这是本文的重点。如果你之前给 claude-opus-4.8 配过 subagents你的 JSON 大概长这样{ subagents: { allowed_tools: [read_file, write_file, execute_command], max_turns: 25 } }换到 claude-sonnet-5 之后这个配置会静默失败。不报错subagent 就是不执行任何 tool call。我当时看日志看了一个多小时什么异常都没有最后是去翻 Anthropic 的 changelog 才发现变了。claude-sonnet-5 正确的写法{ subagents: { tool_call_budget: 40, denied_tools: [execute_command], allowed_tools: *, max_turns: 20 } }注max_turns: 20为显式覆盖默认值 10 的推荐值并非默认。逐个解释差异一tool_call_budget是新增必填字段。这个参数限制单次 subagent session 里所有 tool call 的调用次数上限。不填的话默认是 0——等于直接禁止 tool call。我第一次踩坑就是这里因为 opus-4.8 根本没这个字段旧配置复制过来自然是 0。差异二allowed_tools从白名单改成了通配符 黑名单。opus-4.8 时代你得一个个列出允许的工具名。sonnet-5 改成了*表示全部允许然后用denied_tools排除不想暴露的。如果你还按老写法列白名单sonnet-5 会把它当成只允许这几个工具——但内部解析逻辑变了实际匹配不上任何工具结果就是空列表。差异三max_turns默认值从 25 降到了 10。这个 Anthropic 文档截至 7 月 2 号没写。我是跑一个多步骤重构任务时发现到第 10 轮就停了手动加到 20 才正常。不确定这是 bug 还是有意为之反正先显式写上比较保险。第五步用 Inspector 验证npx modelcontextprotocol/inspector \ npx -y anthropic-ai/claude-code mcp serveInspector 会列出所有暴露的工具。如果你看到read_file、write_file、search_files等工具正常出现说明 MCP Server 本身没问题。重点检查 subagents 相关的权限是否按预期生效。不同场景怎么选你的场景推荐配置原因个人开发跑小任务tool_call_budget: 20次,max_turns: 10显式覆盖默认值控制调用次数sonnet-5 输出 $15/M团队协作多文件重构tool_call_budget: 80次,max_turns: 30显式覆盖默认值大型重构需要多轮 tool call只读审计code reviewdenied_tools: [write_file, execute_command]防止 subagent 意外修改代码从 opus-4.8 迁移先改三个字段其他不动最小改动验证通过再调优成本方面——claude-sonnet-5 输入 $3/M、输出 $15/Mopus-4.8 输入 $15/M、输出 $75/M。输入和输出均降至约 1/5同样的 subagent 任务换 sonnet-5 整体成本大幅下降这也是很多团队迁移的动力。如果你通过聚合网关走还能统一管理多个模型的 Key 和用量不用每个开发者单独申请 Anthropic 账号。踩坑记录坑 1API Key 没传进 MCP Server 子进程Claude Code Error: Authentication failed. Please run claude login or set ANTHROPIC_API_KEYClaude Desktop 是 GUI 进程启动时不读取用户 shell 的~/.bashrc/~/.zshrc因此 shell 会话里export的环境变量对它不可见。必须在 JSON 配置的env字段里显式写。坑 2npx 交互提示污染 stdioMCP Error: Invalid JSON in server response忘了加-y参数npx 弹出是否安装的确认文字混进了 JSON 通信流。坑 3tool_call_budget设太小没报错但 subagent 只执行了一次read_file就停了。因为 budget 设了 1次一次 read_file 就把次数用完了。建议小任务至少给 20 次复杂场景给 80 次以上。常见问题 FAQQ: claude-sonnet-5 的 API model ID 到底填什么填claude-sonnet-4-5。Anthropic 的营销名是 claude-sonnet-5但 API 里的 model ID 是claude-sonnet-4-5。填错会返回 model not found。Q: subagents 的 tool_call_budget 单位是什么怎么估算单位是工具调用次数call count限制的是 subagent 在整个 session 内累计可执行的 tool call 次数上限。例如你预计需要读 5 个文件、写 3 个文件、搜索 2 次共约 10 次调用建议留出 2 倍余量设为 20。Q: 配置改了之后要重启什么改完claude_desktop_config.json后要完全退出并重启 Claude Desktop不是刷新是 CmdQ 再打开。stdio 模式下 Server 进程是客户端按需拉起的改配置必须重启客户端。Q: 能不能在 Cline 里用这个 MCP Server可以。Cline 支持 MCP 协议在 Cline 的 MCP 配置里加上同样的 JSON 就行。但 Cline 的 subagents 字段解析可能和 Claude Desktop 有微小差异建议先用 Inspector 验证。Q: 我用聚合网关的 Key 能不能配可以。把ANTHROPIC_API_KEY换成对应平台的 Key同时加一个ANTHROPIC_BASE_URL环境变量指向该平台的 API 地址以平台实际文档为准。聚合网关的好处是团队成员的 token 消耗在管理后台能按人头看到不用月底互相对账。小结claude-sonnet-5 的 MCP Server 配置本身不难难的是 subagents 权限那三个隐藏差异——尤其是tool_call_budget默认为 0 导致静默失败这个设计挺反直觉的。希望 Anthropic 后面能把这个改成报错而不是静默跳过。我现在的做法是所有新项目都显式写满这三个字段不依赖默认值。谁知道下个版本默认值又会怎么变。