• 作者: 作者
  • 时间:
  • 分类: 文章

在使用 Claude Code 进行开发时，为了追求更高的性价比或特定的模型能力，很多开发者会选择接入第三方模型（比如 DeepSeek）。最近有朋友遇到一个很有意思的 bug：直接调用 DeepSeek 官方 API 时，Web Search（联网搜索）功能一切正常；但一旦切到自己搭建的 CPA 反代（如 Codex），这个功能就直接“哑火”了。这到底是为什么？又该怎么解决？今天就来和大家聊聊这个问题的排查思路。

现象回顾：直连可用，反代失效

首先，我们简单复盘一下问题的现象。在终端中执行 cc switch 切换模型后：

  1. 官方直连：配置 DeepSeek 官方 API Key，发送需要联网的指令，一切顺利。
  2. 自建反代：配置 CPA 反代（Codex）的地址和 Key，模型能正常对话，逻辑推理也没问题，唯独 Web Search 毫无反应，仿佛它“断网”了。

API反代架构示意图

反代服务数据流向示意图，展示客户端、反代服务器与官方API之间的交互关系。

既然模型本身的推理能力正常，说明基础的 API 通信（Chat Completion）是没有问题的，问题大概率出在“工具调用”或者“参数透传”这个环节。

深度分析：为什么反代会“吃掉”联网能力？

既然官方直连能用，说明 DeepSeek 的 API 标准是支持 Web Search 的。当你使用反代服务时，数据流经过了你的中转服务器。Web Search 无法使用，主要有以下几种可能的原因：

1. 参数透传缺失

Claude Code 在触发联网搜索时，通常会在请求体中携带特定的 tools 参数或者配置项来告诉后端：“嘿，我需要联网查资料”。 如果你的反代后端代码写得比较简单，只透传了 messages 和基础模型参数，而过滤掉了这些与“工具调用”相关的参数，那么 DeepSeek 的后端就收不到联网指令，自然也就不会开启搜索。

2. 模型能力映射错误

有些反代服务是为了兼容 OpenAI 格式而存在的。如果你的 CPA 反代主要是为了兼容 OpenAI SDK，它可能会错误地把你请求的某个支持联网的 DeepSeek 模型，映射成了一个不支持联网的通用模型版本。 这就像是你要打车去机场（需要联网），结果司机非要把你当成去菜市场（仅需对话）处理，目的地完全错了。

API参数配置示例

展示包含 tools 和 tool_choice 参数的 JSON 请求体示例，帮助理解参数透传的重要性。

3. Headers 或 Metadata 处理不当

有时候，API 的能力开关是通过 HTTP Header 或者特定的 Metadata 字段来控制的。反代服务如果没有完整复制这些上下文信息，或者服务器端的 Nginx/网关层过滤掉了某些特殊的 Header，也会导致功能失效。

实战排查与解决方案

针对以上原因，我们可以按照以下步骤进行排查和修复。

方案一：检查反代后端配置（推荐）

这是最根本的解决办法。你需要检查搭建 CPA Codex 反代时的后端代码（通常是 Node.js, Python 或 Go 写的转发层）。

  • 透传检查：确认代码中是否将接收到的原始请求体完整转发给了 DeepSeek 官方 API。尽量避免在中间层做字段过滤，除非是为了做格式转换（如将 OpenAI 格式转为 DeepSeek 格式）。
  • 日志对比：开启反代服务的 Debug 日志。对比“官方直连”成功时的请求包和“经过反代”失败时的请求包。重点查看 tools、tool_choice 以及 model 参数是否一致。你会发现反代时的请求大概率少了某些字段。

方案二：尝试显式启用工具（如果 CLI 支持）

有些版本的 Claude Code CLI 或者配置文件可能允许显式声明工具使用。检查一下你的配置文件（通常是 .claude_code_config 或类似的配置文件），看看有没有关于 enable_search 或类似的开关，确保在第三方模型模式下没有被自动关闭。

方案三：降级使用或更换反代节点

  • 更换反代：如果你使用的是公开的第三方反代节点，可能是该节点的维护者还没有适配 Web Search 功能的透传。可以尝试更换一个维护更活跃的反代节点，或者自己搭建一个完全透传的反代服务。
  • API 版本检查：确保你的反代调用的是 DeepSeek 最新的 API 版本。旧版本的 API 接口定义可能本身就还不支持联网工具调用。

总结

遇到“直连能用，反代不行”这类问题，核心思路就是抓包对比。既然 DeepSeek 是支持 Web Search 的，那么问题一定出在中间的转发环节。绝大多数情况下，修复方法就是在你的反代服务中，把原本被忽略的 tools 相关参数老老实实地转发给官方 API 即可。 希望这篇排查笔记能帮到正在折腾 Claude Code 和 DeepSeek 的你！

标签: none

评论已关闭