Codex Switch：DeepSeek接入Codex的协议转换工具详解

引言：第三方模型接入Codex的痛点

OpenAI的Codex CLI是一款强大的AI编程工具，但它原生只支持OpenAI自家的模型。Codex CLI是OpenAI在2025年推出的开源命令行AI编程助手，它运行在终端中，能够读取本地代码库、执行命令、修改文件，本质上是一个具备代码执行能力的Agent。它默认使用OpenAI的Responses API进行通信——这是OpenAI在2025年初推出的新一代API格式，原生支持工具调用、多模态输入、流式输出等高级特性，并与OpenAI的Agent SDK深度集成。

如果你想用DeepSeek、GLM、MIMO等国产模型来驱动Codex，往往会遇到协议不兼容、无法处理图片、缺乏联网搜索等一系列问题。这些问题的根源在于：第三方模型通常只实现了Chat Completions接口，而Codex CLI发送的是Responses API格式的请求，两者在数据结构、工具调用方式和流式传输格式上都存在显著差异。

一位B站UP主分享了一个名为Codex Switch的开源工具，它通过本地代理的方式，不仅解决了协议转换问题，还为纯文本模型补齐了视觉理解和联网搜索能力。本文将完整梳理这套工具的核心机制和实际使用流程。

从零开始：将DeepSeek接入Codex

第一步：获取API Key并确认接口信息

接入任何第三方模型的第一步，都是在对应的开放平台创建API Key。以DeepSeek为例，进入其开放平台的API Keys页面，新建一个Key（注意：Key只显示一次，务必立即保存）。

接下来需要确认三个关键信息：

• Base URL：API的请求地址
• 可用模型列表：确认你要调用的具体模型名称
• 请求格式：DeepSeek使用的是Chat Completions格式

Chat Completions API是OpenAI最早推出的对话接口格式，请求体以messages数组为核心，每条消息包含role和content字段。由于其简洁性和先发优势，几乎所有第三方大模型厂商（包括DeepSeek、智谱GLM、Anthropic等）都选择兼容这一格式，使其成为事实上的行业标准。

这三个信息直接决定了后续配置能否跑通。遇到接入问题时，建议先回到官方文档确认，不要靠猜。

第二步：在Codex Switch中创建Provider

打开Codex Switch的Providers页面，新建一个DeepSeek Provider。Provider可以理解为一套API连接信息的封装，配置一次后，其他功能模块调用DeepSeek时就不用重复填写。

需要填写的字段包括：服务商类型、Base URL和API Key。其中最关键的是Wire Format——它告诉本地代理应该按哪种协议来处理请求。Wire Format的选择决定了代理在转发请求时如何进行数据结构的映射：是按Chat Completions的messages格式发送，还是按Responses API的input格式发送，亦或是其他自定义协议。

第三步：常见踩坑与排错思路

在实际演示中，UP主故意没有将Wire Format设置为正确的Chat Completions，结果出现了一个非常典型的问题：模型列表能正常刷新，但实际对话时失败。

这个现象在接入第三方模型时极为常见。正确的排查思路是：

1. 模型列表能返回 → Base URL和API Key大概率没问题（因为列表接口通常是简单的GET请求，不涉及复杂的请求体格式）
2. 对话失败 → 优先检查模型名称和Wire Format（请求协议）（因为对话接口需要正确的请求体结构）

将Wire Format改为Chat Completions后，DeepSeek立刻正常返回结果。

核心机制：Codex Switch协议转换代理原理

这里值得深入理解Codex Switch的工作原理。Codex原生发送的是Responses API请求，而DeepSeek接收的是Chat Completions格式，两者协议不同。

具体来说，Responses API使用input数组替代messages，支持更复杂的内容类型（如file_search、code_interpreter等内置工具），响应格式也从单一的choices数组变为包含output items的结构。两者在工具调用的声明方式、流式传输的SSE事件格式、多模态内容的编码方式上都存在显著差异，这就是为什么简单修改Base URL无法让第三方模型接入Codex的根本原因。

Codex Switch在本机启动了一个兼容代理（监听127.0.0.1:47632），这是一种经典的反向代理/协议网关模式。工作流程如下：

1. Codex按自己的方式发送Responses API请求
2. 请求先到达本地代理
3. 代理将请求转换为DeepSeek能识别的Chat Completions格式（包括将input结构映射为messages结构、重写认证头、转换工具声明格式等）
4. DeepSeek返回结果后，代理再将响应转换回Codex需要的格式（将choices包装为output items，转换流式事件格式等）

这种架构对Codex CLI完全透明——它认为自己在和一个支持Responses API的服务通信，而实际后端可以是任何兼容Chat Completions的模型。

Codex Switch解决的不仅仅是配置集中管理的问题，更核心的价值在于弥合了不同API协议之间的差异。这意味着理论上任何兼容Chat Completions的模型，都可以通过这种方式接入Codex。

能力补齐：视觉理解与联网搜索

给纯文本模型"装上眼睛"

DeepSeek的文本模型本身不能直接理解图片，但在实际编程场景中，经常需要处理截图、界面图、报错图片等视觉内容。Codex Switch提供了一个优雅的解决方案：

在视觉设置中，可以额外配置一个支持图片输入的Provider和模型。常见的视觉语言模型（VLM）包括GPT-4o、Claude 3.5 Sonnet、Qwen-VL等，它们通过Vision Transformer等架构将图像编码为token序列，与文本token一起送入语言模型进行理解。这个视觉模型不替代DeepSeek，而是专门负责"看图"：

1. Codex遇到图片任务时，图片先交给视觉模型
2. 视觉模型读取图片内容，生成文本描述（包括UI元素位置、文字内容、布局关系、报错信息等）
3. Codex Switch将描述作为上下文交给DeepSeek
4. DeepSeek基于文本描述进行后续分析和代码修改

本质上，DeepSeek并没有"突然会看图"，而是前面多了一步视觉描述，把它原本缺少的信息补上了。这种"模型级联"策略虽然会损失一些视觉细节，但对于代码相关的场景（如截图中的报错信息、UI布局参考）已经足够实用，且避免了要求主模型必须具备多模态能力的限制。视觉模型和主模型可以使用不同的Provider，灵活性很高。

联网搜索：工具负责取信息，模型负责思考

很多第三方模型没有原生联网搜索能力。Codex Switch通过配置WebSearch工具来解决这个问题，演示中使用了Tavily作为搜索服务。Tavily是一个专为AI Agent设计的搜索API，与传统搜索引擎API不同，它返回的结果经过了针对LLM消费的优化处理，包括内容摘要提取、相关性排序和结构化输出，使得模型能更高效地利用搜索结果。

实际工作链路是：

1. 模型判断需要联网信息时，调用本地提供的WebSearch工具
2. 如果需要读取具体网页内容，继续调用WebFetch工具
3. 工具将搜索结果和网页内容返回
4. DeepSeek根据这些内容整理答案，并保留信息来源

从技术实现角度看，搜索能力是通过Function Calling（函数调用）机制注入的：代理在转发请求时，会在工具列表中声明WebSearch和WebFetch两个可用函数及其参数schema。当模型判断需要外部信息时，它会在响应中生成一个工具调用请求（包含函数名和参数），代理拦截这个请求并实际执行搜索操作，将结果作为工具响应返回给模型继续推理。这种"模型决策+工具执行"的分离架构是当前AI Agent的主流设计模式。

这个过程的一大优势是便于排查。在终端中可以清楚看到调用了哪个工具、搜索了哪些结果、读取了哪些页面。如果回答不对，可以精确判断问题出在搜索关键词、网页内容还是模型理解环节。

联网能力不是直接塞进模型里，而是通过本地工具补给Agent——模型负责思考，工具负责把最新信息拿回来。

附加功能：图片生成、对话测试与会话管理

Drawing：统一管理图片生成

Codex Switch还集成了图片生成功能。选择已保存的Provider和图片模型，输入提示词（可附加参考图），即可调用图片生成接口。

生成结果保存在本地记录中，方便后续查看。虽然不是专业绘图软件，但将图片生成接口纳入同一个工作台，省去了在多个工具间切换的麻烦。

Talking：快速对话测试

如果只是想确认某个Provider能否正常调用，Talking页面比重新启动Agent要快得多。直接选择Provider和模型，即可进行快速对话测试，适合在配置阶段快速验证连通性。

Sessions：会话管理与Handoff

Codex Switch会读取Agent保存在本机的会话记录并集中显示。一个特别实用的功能是Handoff——它不是把整个会话复制一遍，而是将下一段工作最需要知道的内容提炼出来：当前进度、修改了哪些文件、接下来要验证什么、还有哪些风险未处理。

Handoff（交接）是Agent工程中的一个重要概念，源自人类团队协作中的工作交接场景。在长期运行的编程项目中，单次对话的上下文窗口有限（即使是128K token的模型，面对大型代码库也会溢出），而且开发者可能在不同时间段、使用不同模型继续同一个任务。Handoff机制通过对历史会话进行智能摘要，提取出关键的状态信息，保留的是"决策相关信息"而非"对话过程信息"。在OpenAI的Agent SDK中，Handoff也是一个核心原语，用于在多个Agent之间传递任务控制权。

这对长期项目非常有用，因为真正做项目时，很多上下文不是一句"继续刚才的工作"就能说清楚的。

总结：Codex Switch适合哪些开发者

Codex Switch的价值可以归纳为三个层面：

1. 协议转换：让原本接不进Codex的模型（DeepSeek、GLM、MIMO等）通过本地代理实现无缝接入
2. 能力补齐：为纯文本模型补上视觉理解和联网搜索能力，通过工具链而非模型本身来扩展功能边界
3. 统一管理：Provider、模型配置、会话记录、图片生成都在同一个工作台中组织

该工具已在GitHub上开源发布，Windows版本可从GitHub Releases下载。对于想要在Codex或Claude Code中使用国产模型的开发者来说，这是一个值得关注的开源项目。

不过需要注意的是，协议转换本身会引入额外的延迟（请求需要经过本地代理的解析、转换和重新封装），且不同模型的能力差异仍然存在——工具能解决接口兼容问题，但模型本身的推理质量还是取决于模型自身。选择合适的模型组合（主模型+视觉模型+搜索工具），才是发挥这套方案最大价值的关键。