Claude Code 网关拒绝工具搜索怎么修

Claude Code 2.1.305 针对网关拒绝 ToolSearch 的场景补上了自动回退：请求带有工具搜索相关字段失败时，客户端会去掉这部分能力再试一次；但这不是所有兼容性问题的通用修复，接入 ANTHROPIC_BASE_URL、中转 API 或自建兼容层时，仍应把 ENABLE_TOOL_SEARCH=false 作为可验证的手动回退路径，并检查 MCP 工具名是否超过官方限制。

这次版本具体改了什么

Claude Code 的 MCP 工具搜索不是简单地把所有工具定义一次性塞进请求。启用工具搜索后，客户端可以先发送工具搜索能力，再按需加载匹配到的 MCP 工具。这样做改变了请求里出现的字段：工具可能带有 defer_loading，后续对话还可能出现 tool_reference。如果请求要经过的网关只实现了旧版 Anthropic Messages 形状，或者会主动拒绝这些字段，客户端就可能在第一步收到 400，而不是等到真正调用 MCP 工具时才失败。

Claude Code v2.1.305 的发布说明明确写了一个针对性修复：当 Vertex、Bedrock 或其他提供商的端点或网关拒绝工具搜索时，客户端会不带工具搜索重试；发布说明还特别提到，工具搜索被网关禁止、或没有出现在 --tools 中时，原本可能导致每个请求都失败，这个回退路径用于处理该回归。这里的关键不是“网关突然支持了 ToolSearch”，而是客户端在检测到拒绝后，尝试退回到不依赖该能力的请求形状。

这个变化对开发者有两个直接影响。第一，升级到 2.1.305 或更高版本后，部分原本第一请求就失败的网关不必立刻改后端就能恢复到基础 MCP 调用路径。第二，自动重试只覆盖客户端能够识别的拒绝情形；它不能把一个只支持部分 Anthropic API 的网关变成完整的 MCP 代理，也不能修复网关丢失工具结果、错误改写流式事件或错误保存工具引用的问题。

如果你需要先确认 RouterHub 上有哪些可用的 Claude API 渠道，可以从模型与平台目录开始，再根据实际端点核对其文档；不要把“能返回普通文本”直接当成“支持 Claude Code 的 MCP 工具搜索”。

先区分三类报错

1．请求字段被端点拒绝

这类错误通常在请求刚发出时出现，响应会指向 defer_loading、工具搜索 beta 能力，或提示额外输入不允许。它说明请求形状超出了当前端点或网关接受的范围。对于这类错误，优先验证 Claude Code 版本，再让客户端自动回退；如果仍然失败，显式关闭工具搜索后重试。

在 shell 中可以先执行：

export ENABLE_TOOL_SEARCH=false
claude

也可以把它写进项目或用户级设置中的环境变量配置。关闭后，Claude Code 会走 MCP 工具预加载路径，而不是依赖 ToolSearch 按需加载。代价是工具定义会更早进入上下文，请求可能变大；收益是网关不再需要理解工具搜索相关字段。这个选择是兼容性回退，不等于工具调用本身一定可用，后续仍要验证工具调用、结果回传和流式结束事件。

2．工具引用找不到

另一类错误是：

400 Tool reference 'mcp__...__...' not found in available tools

Anthropic 的 Tool Search 文档说明，搜索结果会以 tool_reference 返回，API 再把引用扩展为完整工具定义。也就是说，引用并不是普通文本；它必须和当前请求中可用的工具集合准确对应。如果中间的网关删除、改名或重排了相关字段，客户端下一轮就可能拿着一个服务端不认识的引用继续请求。

Claude Code 仓库中的公开 issue 还记录了一个更具体的边界：某些 MCP 工具的完整名称超过 64 个字符时，ToolSearch 可以先选中它，但下一次请求会因为找不到工具引用而失败。该 issue 的复现环境是 Claude Code 2.1.283，问题报告于 2026 年 9 月 27 日；它不是 2.1.305 发布说明中“网关拒绝 ToolSearch”的同一个问题，不能因为升级后有自动回退，就断言长工具名问题已经解决。

排查时应在 /mcp 中查看完整工具名，特别留意插件自动加入的前缀，例如 mcp__plugin_<plugin>_<server>__<tool>。如果名字过长，可以把同一个 MCP 端点以较短的服务器名写入项目 .mcp.json，并确认客户端是否抑制了插件重复项；也可以暂时关闭该服务器或避免让 ToolSearch 选中超长名称。不要只改显示名称后就认为问题消失，必须用一次真实工具调用确认引用能在下一请求中被解析。

3．工具搜索成功，但工具调用仍失败

如果日志能看到 ToolSearch 返回结果，随后实际工具调用才收到 401、403、404、429 或 5xx，那么问题已经越过“工具搜索字段兼容”这一层。此时要分别核对 MCP 服务端认证、网关对上游 URL 的放行、请求体是否完整转发，以及错误响应有没有被包装成普通文本。

这个区分很重要。把所有错误都归因于“Claude Code 不支持中转 API”，会掩盖真正的故障点；反过来，把一次自动回退成功当成完整兼容，也可能让团队在生产环境里遇到更晚、更难定位的工具结果丢失。此前的Claude Code 流式 ECONNRESET 排查记录也说明，客户端版本、操作系统和网关转发行为需要分层验证。

一套可复现的接入排查顺序

第一步：记录客户端与请求边界

先记录 Claude Code 的确切版本、运行平台、模型、是否设置了 ANTHROPIC_BASE_URL，以及是否启用了 MCP。不要只写“最新版”或“某个 Claude 模型”，因为 2.1.304 与 2.1.305 的工具搜索回退行为不同，模型端点也可能由不同的提供商实现。

同时保存一次失败请求的状态码、响应体和请求时间。敏感的 API Key、Cookie、用户标识和完整提示词应先脱敏。对网关侧则要确认实际收到的字段：是否包含 defer_loading，是否包含工具搜索工具，是否出现 tool_reference，以及网关有没有在转发前把它们删除。

第二步：用最小配置做 A／B 测试

把 MCP 配置缩减到一个服务器和一个简单工具，先验证普通对话，再验证工具搜索，最后验证真实工具调用。每次只改变一个变量：

# A：保持默认行为，观察网关是否接受工具搜索
claude -p "列出可用的 MCP 工具，不要调用它们。"

# B：关闭工具搜索，观察预加载路径是否能工作
ENABLE_TOOL_SEARCH=false claude -p "调用一个无副作用的 MCP 工具并返回结果。"

A 失败、B 成功，优先说明网关或端点不接受工具搜索请求形状。A 和 B 都失败，则继续查认证、MCP 连接和工具本身；A 成功但真实调用失败，则检查工具参数、上游权限和结果转发。命令只是最小化示意，实际测试应替换成不会写入数据、不会发送消息的只读工具。

第三步：确认版本回退没有制造重复副作用

2.1.305 的回退会重新发起一次请求。对于普通文本请求，这通常是一次兼容性重试；但如果网关在失败前已经把请求转发给上游，或者某个自建层对工具调用不是幂等的，就不能把“自动重试”当成无条件安全。网关日志应使用请求 ID 或等价关联字段，区分第一次拒绝和第二次不带工具搜索的请求。

如果团队使用自定义代理，建议在兼容层明确记录：收到工具搜索字段时是原样转发、稳定拒绝并返回可识别错误，还是转换为预加载模式。最危险的状态是静默删除一部分字段，让客户端误以为工具已被加载，随后在下一轮才报 tool_reference 不存在。

第四步：为生产配置保留显式开关

即使自动回退已经恢复，也建议把开关作为部署配置而不是个人 shell 习惯。可以为不同端点建立两组配置：支持工具搜索的端点保持默认，旧网关或只支持基础 Messages API 的端点设置 ENABLE_TOOL_SEARCH=false。切换时同时记录 MCP 工具数量、工具名长度、请求体大小和失败状态码，避免把一次偶然成功误判为长期兼容。

如果关闭工具搜索后请求体过大，再从 MCP 服务器侧减少暴露工具、缩短服务器名与工具名，或按项目拆分服务器。不要为了绕过字段限制，把全部工具继续预加载到每一个会话；那会把一个协议兼容问题转化为上下文、权限和审计问题。

对中转 API 使用者的实际结论

这次修复把 Claude Code 的网关兼容从“一遇到 ToolSearch 拒绝就整轮失败”推进到“先尝试能力路径，失败后回退基础路径”。选择渠道时，应该把检查项写成可执行的兼容矩阵：普通 Messages 请求是否成功，MCP 预加载是否成功，ToolSearch 请求是否被接受，tool_reference 是否能跨请求解析，工具结果是否完整返回，流式响应是否正常结束。

其中任何一项没有证据，都不要在配置文档里写成“支持 MCP”或“兼容 Claude Code”。可以先在平台目录查看候选渠道，再通过渠道自己的文档和一次最小只读测试确认边界。对需要特定站点信息的读者，也应以该站点公开的模型、端点和限制说明为准，而不是仅凭模型名称相同就推断工具搜索能力一致。

最后，升级 Claude Code 后仍然遇到 400 时，按以下顺序处理最省时间：先看是否命中 defer_loading 或工具搜索拒绝；再用 ENABLE_TOOL_SEARCH=false 做对照；然后检查 tool_reference 是否被网关改写；最后才排查 MCP 认证、工具名长度、上游权限和流式传输。这样可以把“客户端能力变化”“协议字段兼容”和“具体工具服务故障”分开，避免反复更换模型或渠道却没有得到新的证据。