Codex 接入开源模型完整配置指南

预计字数：5300 字阅读时间：14 分钟难度等级：⭐⭐⭐（需要基础命令行经验）

核心价值：搞懂为什么 Codex 配国产模型总连不上，15 分钟跑通 CC Switch 代理，让 DeepSeek 替代 GPT-5 做日常编程主力

你配半天连不上的原因，不在你

最近不少伙伴在反馈一件事：

按照 Codex 官方文档配好了国产 API Key，填进了 ~/.codex/config.yaml

重启终端，满怀期待地输入第一条指令

结果连不上。

返回 400 错误，或者 404，或者干脆超时。

翻遍文档，检查了三遍 Key 没拼错，端口也没被占用，但就是不通。

问题出在哪？不是你配错了，而是两套协议根本不互通。

Codex 底层用的是 OpenAI 的 Responses API，这是 OpenAI 在 2025 年推出的新一代 API 协议。

而国产模型------DeepSeek、通义千问、智谱------走的都是 Chat Completions API，也就是我们熟悉的 /v1/chat/completions 那一套。

两套协议在请求结构、参数格式、流式响应的 SSE 事件类型上都有差异。

Codex 发出去的请求，DeepSeek 的服务器不认识；

DeepSeek 返回的响应格式，Codex 也解析不了。

就像你拿普通话对粤语使用者说了一段话，字都认识，但对方完全听不懂你在讲什么。

所以官方文档里写的那些配置方法，只对 OpenAI 自家模型有效。

你拿 DeepSeek 的 Key 填进去，自然连不上。

理解了这一点，你就不会再反复搜"为什么 Codex 配了 DeepSeek 报 400"了

答案很清楚：这不是 bug，这是架构层面的断层。

架构断层怎么补：中间层代理

既然两套协议不通，那就需要一个中间层来做翻译。这层翻译需要做到三件事：

1. 接收 Codex 的 Responses API 请求，把它拆解、转换成 Chat Completions API 能懂的格式
1. 转发给国产模型的 API 端点，拿到响应后，再把格式翻回来
1. 对 Codex 完全透明------Codex 以为自己还在跟 OpenAI 通信

这就是 CC Switch（github.com/farion1231/cc-switch）做的事情。

它是一个开源的本地代理工具，跑在你本机上，监听 Codex 的请求，在中间做协议转换，然后转发到实际的后端模型。

数据流向是这样的：

复制代码

Codex CLI → CC Switch（本地代理 + 协议转换）→ DeepSeek / 通义千问 API

为什么不直接改 Codex 的源码让它支持 Chat Completions？

可以，但你每次升级都得重新改。

代理方案的好处是解耦------Codex 怎么更新都跟你没关系，转换逻辑集中在代理层，维护成本低得多。

也有人问：不用 CC Switch，能不能自己写一个 Nginx 反向代理加脚本做转换？

理论上可以，但协议转换涉及请求体的字段映射、流式响应的事件类型重写、错误码的翻译，工程量不小，而且还要处理并发和连接池。

CC Switch 已经把这些都封装好了，没必要重复造轮子。

开始配置：你需要准备什么

在动手之前，确认三件事：

第一，Codex CLI 已安装。

复制代码

npm install -g @openai/codex

安装完后验证：

复制代码

codex --version

正常输出类似 codex/1.x.x darwin/arm64。

Codex 的配置文件位于 ~/.codex/config.yaml，后面会用到。

第二，拿到一个可用的 API Key。

推荐两个选择：

DeepSeek：去 platform.deepseek.com 注册，在 API Keys 页面创建新 Key。
- 目前 DeepSeek V4 Flash 价格极低，适合高频日常使用。
通义千问：去 dashscope.aliyun.com 开通，获取 API Key。
- 适合已经在阿里云生态内的开发者。

拿到 Key 后记在安全的地方，后面配置要用。

建议直接复制到剪贴板，不要手动输入------API Key 通常是一串长字符，手动打错一个字符就废了。

第三，安装 CC Switch。

macOS 用户最方便：

复制代码

brew install --cask cc-switch

如果 Homebrew 没有这个 cask 或者网络不通，直接去 GitHub Releases 页面下载安装包：

地址：github.com/farion1231/cc-switch/releases

选择对应系统的版本（macOS 选 .dmg，Windows 选 .exe，Linux 选 .AppImage）

下载后拖进 Applications 即可。

安装完成后打开 CC Switch，确认应用正常启动，界面上能看到 Provider 和 Routing 两个主要标签页。

配置 CC Switch：这里面坑最多

打开 CC Switch，你会看到一个 Provider 配置界面。点击添加新 Provider，接下来是最容易踩坑的环节。

第一步：选择模型预设

CC Switch 内置了几个常用模型的预设配置。

如果你用 DeepSeek，选择 DeepSeek V4 Flash 或 DeepSeek V4 Pro 预设。

🎯

踩坑提醒 #1：不要选错版本

DeepSeek 的模型版本迭代很快，V3 和 V4 的接口行为有差异。

CC Switch 的预设是针对 V4 做的适配。

如果你手动填了一个 V3 的模型名，协议转换会出问题，轻则报 400，重则请求能发出去但返回的响应 Codex 解析不了，表现为"发了消息没反应"。

第二步：填入 API Key

把你从 DeepSeek 或通义后台拿到的 Key 粘贴到 API Key 字段。

注意不要有多余的空格或换行------很多复制粘贴工具会自动带一个尾部空格，肉眼看不到，但会导致认证失败。

第三步：开启 Needs Local Routing

这是最关键的一步，也是最容易被忽略的。

在 Provider 配置页面，有一个开关叫 "Needs Local Routing"。这个开关决定了 CC Switch 是否会在本机启动一个监听端口，把 Codex 的流量拦截下来做转发。

必须打开它。如果不打开，CC Switch 只是存了个配置，但实际没有任何代理在运行，Codex 的请求直接发到 OpenAI 的服务器去了------当然连不上你的国产模型。

第四步：在路由页面确认开关状态

配置完 Provider 后，切到 CC Switch 的"路由"（Routing）页面。你应该能看到一个开关按钮。

如果按钮是绿色的，说明本地代理已经在运行，端口已监听。
如果按钮是灰色的，点一下打开它。

🎯

踩坑提醒 #2：按钮绿了不代表万事大吉

按钮变绿只说明 CC Switch 自己的代理服务启动了。

但你还需要确认 Codex 的请求确实经过了代理。后面我会讲怎么验证这一点。

重启 Codex，让它发现代理

CC Switch 配好之后，必须完全重启 Codex。

不是关一个终端窗口再开一个新的，而是要确保 Codex 进程彻底退出后重新启动。

复制代码

# 确认 Codex 没有残留进程
ps aux | grep codex

# 如果有残留，杀掉
pkill -f codex

# 重新启动
codex

启动后，进入模型列表查看。

如果你用的是 DeepSeek，列表中应该出现 DeepSeek V4 Flash 或 V4 Pro 的选项。

🎯

踩坑提醒 #3：重启终端窗口不够

有些开发者只是在当前终端窗口里 exit 再开一个新窗口，但 Codex 可能是以长驻进程的方式运行的（尤其在 VSCode 集成场景下）。

必须用 ps aux | grep codex 确认没有残留进程，或者直接 pkill -f codex 再启动。

否则旧进程用的还是之前的配置，不会重新读取 CC Switch 的代理设置。

验证：三层检查确保配置生效

配完之后，怎么确认真的通了？我建议做三层检查。

第一层：模型列表检查

在 Codex 中输入模型切换命令，看模型列表里是否出现了你在 CC Switch 中配置的模型名称。

如果列表里有，说明 Codex 已经成功识别到了代理提供的模型。

复制代码

# 启动时指定模型
codex --model deepseek/deepseek-chat

# 或在会话中用斜杠命令切换
/model deepseek/deepseek-chat

第二层：发送测试消息

随便给 Codex 发一条简单指令，比如：

复制代码

用 Python 写一个冒泡排序

如果 Codex 能正常返回代码并执行，

明整个链路------Codex → CC Switch → DeepSeek API → 响应返回------已经跑通。

第三层：路由计数验证

回到 CC Switch 的路由页面，查看请求计数。

如果计数器从 0 变成了 1 或更大，说明流量确实经过了代理。

如果第二层测试失败但第一层模型列表正常，问题大概率出在协议转换层或 API Key 上。

检查 CC Switch 的日志输出，看看具体的错误信息。

如果第二层和第三层都失败（计数器不变），说明请求根本没走到代理。

回到前面的排查：路由开关是否打开？Codex 是否完全重启？端口是否被其他进程占用？

复制代码

# 检查代理端口是否在监听（CC Switch 默认端口视配置而定）
lsof -i :<端口号>

# 如果被占用，看看是谁占的
lsof -i :<端口号> | grep LISTEN

常见问题诊断清单

把实际使用中遇到的高频问题整理如下：

|----------------------|---------------------------------|-----------------------------------------|
| 症状 | 可能原因 | 解决方法 |
| 模型列表看不到 DeepSeek | 路由开关没开 / Codex 没完全重启 / 端口冲突 | 检查路由页面开关状态 → pkill 重启 Codex → lsof 检查端口 |
| 请求返回 400 或 404 | DeepSeek V4 需要协议转换但没走代理 / 模型名错误 | 确认流量经过 CC Switch → 检查模型预设是否选对 |
| 发了消息没反应，也不报错 | 响应格式不兼容，Codex 静默丢弃 | 检查 CC Switch 日志 → 确认模型版本与预设匹配 |
| 请求直接打到 OpenAI | CC Switch 路由开关未开或 Codex 未重启 | 回到 CC Switch 路由页面确认绿灯 → pkill + 重新启动 |
| 图片类 Computer Use 不可用 | 第三方模型不支持图片输入功能 | 目前已知限制，等模型端支持 |

实测体验：三个模型的真实体感

我自己用了一段时间，把几个模型的体感记录下来，供参考。

DeepSeek V4 Flash：日常主力

速度跟 GPT-5 差不多，写一个中等复杂度的函数、改一个 bug、解释一段代码，响应速度都在可接受范围内。

价格极低，适合作为日常工作流的主力模型。

实测场景：在一个 Node.js 项目里改一个 Express 路由的 bug，从报错信息到定位问题到给出修复代码，总共大概 30 秒完成往返。体感和用 GPT-5 差距不大。

DeepSeek V4 Pro：重活才用

Pro 版本在复杂任务上表现更好------比如项目级重构、架构设计讨论、多文件联动的复杂修改。

但明显更慢，等待时间可能是 Flash 的 2-3 倍。

我的用法是：简单任务全走 Flash，遇到需要"想一会儿"的复杂任务才手动切到 Pro。

没必要一直挂着 Pro，又贵又慢。

本地 Qwen 35B：安全优先场景

跑在本地的 Qwen 35B，好处是不联网、数据不出本机。

适合处理包含敏感信息的代码------比如公司内部项目的配置文件、数据库连接串、业务逻辑里的商业逻辑。

如果你所在的公司对代码出境有合规要求，本地模型几乎是唯一合规的选择。

但推理能力差一截。

复杂的多步推理、跨文件依赖分析，效果明显不如 DeepSeek V4。

适合简单的代码生成和格式转换，不适合作为主力。

另外，跑本地模型对机器配置有要求。

35B 参数量的模型至少需要 24GB 显存（量化后），如果用 CPU 推理速度会很慢。

建议有 M 系列芯片的 Mac 或有独立显卡的机器再尝试。

模型选择决策框架

根据实测体验，我总结了一个简单的决策框架。

遇到一个任务时，按这个流程判断用哪个模型：

复制代码

任务进来
  │
  ├─ 涉及敏感数据 / 代码不能外传？
  │     ├─ 是 → 本地模型（Qwen 35B 等）
  │     └─ 否 ↓
  │
  ├─ 任务复杂度评估
  │     ├─ 简单任务（单文件修改、bug修复、代码解释）
  │     │     └─ DeepSeek V4 Flash
  │     │
  │     ├─ 中等任务（多文件联动、功能开发）
  │     │     ├─ 预算敏感 → Flash（多轮迭代）
  │     │     └─ 一次性要高质量 → Pro
  │     │
  │     └─ 复杂任务（架构重构、设计决策、大型迁移）
  │           ├─ 预算允许 → 直接 GPT-5 / Claude
  │           └─ 预算有限 → Pro + 多轮迭代
  │
  └─ 我的日常推荐组合：
        Flash 做日常 70% 的活
        Pro 做需要深度思考的 20%
        GPT-5 留给最难的 10%

核心思路是分层使用，不要一刀切。

Flash 够用就别上 Pro，Pro 搞不定就别死磕------该用闭源旗舰模型的时候别心疼钱，你的时间比 API 费贵得多。

CC Switch 的几个高级用法

配通了之后，CC Switch 还有几个值得了解的特性。

多工具隔离配置

如果你同时用 Codex 和 Claude Code，CC Switch 可以为它们设置不同的代理规则。

比如让 Codex 走 DeepSeek，Claude Code 走通义千问，互不干扰。

在 CC Switch 的设置里，每个工具的配置是独立的。

你不用改来改去，各自绑定各自的 Provider 就行。

多提供商同时在线

你可以在 CC Switch 里同时添加 DeepSeek 和通义千问的 Provider，然后在不同场景间切换。

比如 DeepSeek 做主力、通义千问做备用------哪家限流了就切另一家，提高可用性。

配置存在本地

CC Switch 的所有配置都存在你本机上，不会上传到任何服务器。

API Key 也是本地存储，不用担心泄露。这也是我推荐它而不是用在线转发服务的原因之一。

最后几个实操建议

1. 今晚就试。配置本身不超过 15 分钟。打开终端，跟着上面的一步一步做，从安装到跑通，一气呵成。犹豫越久越不想动手。
1. 先用 Flash 跑通，再考虑 Pro。不要一上来就追求最好的模型------先把整个链路跑通，确认代理、协议转换、API 调用都没问题，再切换到更强的模型。问题排查的范围越小越好。
1. 保留 GPT-5 的配置。不是用了国产模型就不用 OpenAI 了。有些场景------特别是需要 Computer Use（图片理解 + 屏幕操作）的场景------第三方模型目前不支持。保留一个 OpenAI 的 Provider 作为 fallback，关键时刻不会抓瞎。
1. 关注 CC Switch 的更新。协议转换这个领域迭代很快，OpenAI 的 Responses API 还在变化，国产模型的接口也在演进。CC Switch 如果有新版本，建议及时更新，避免因为协议变更导致的兼容性问题。
更新 CC Switch（macOS）

brew upgrade --cask cc-switch

补充：Responses API vs Chat Completions API 差异到底意味着什么

给想深入了解底层原理的开发者补充一段。

Chat Completions API 是 OpenAI 在 2023 年之前的主力协议，请求格式长这样：

复制代码

{
  "model": "gpt-4",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello"}
  ]
}

响应是一个 choices 数组，每个 choice 有 message 和 finish_reason。

流式输出通过 SSE 事件 data: {...} 返回，每条数据里是增量内容（delta）。

Responses API 是 OpenAI 2025 年推出的新协议，请求格式不同：

复制代码

{
  "model": "gpt-5",
  "input": "Hello",
  "instructions": "You are a helpful assistant.",
  "tools": [...]
}

响应结构完全重设计，不再是 choices + messages 那套，而是 output 数组，每个元素有 type（message、tool_call 等）。

流式输出的 SSE 事件类型也不一样------Chat Completions 用的是统一的 data: 前缀，Responses API 用了新的事件名（如 response.output_item.added、response.output_item.delta 等）。

对普通用户意味着什么？

意味着你不能简单地把 Codex 的请求 URL 从 api.openai.com 改成 api.deepseek.com 就指望能跑通。

请求体的字段名不一样，响应体的结构不一样，流式传输的事件类型不一样。

这就像 HTTP 和 WebSocket 都是网络协议，但你不能把 HTTP 请求发到 WebSocket 端口上。

这就是为什么需要 CC Switch 做中间转换------它要理解两套协议的差异，做字段映射、事件类型转换、错误码翻译，才能让 Codex 和 DeepSeek 正常对话。

总结一下：

Codex 用 Responses API，国产模型用 Chat Completions API，两者不互通------这是架构层面的原因，不是你的配置问题。
CC Switch 作为本地代理做协议转换，是目前最省心的解决方案。
配置的关键在于：选对模型预设、打开路由开关、彻底重启 Codex、验证流量经过代理。
日常用 DeepSeek V4 Flash，复杂任务切 Pro，敏感数据用本地模型，最难的活留给 GPT-5------分层使用，性价比最高。

动手试试吧。跑通的那一刻，你会发现整个流程其实没有想象中复杂------难的不是配置，是知道问题出在哪。

这就是 CC Switch 的价值：它把"协议不通"这个架构问题，降维成了一个"装个工具、填个 Key、开个开关"的操作问题。

把技术债务消化在代理层，让上层应用不用关心底层协议的差异。

这种解耦思路，不只是 Codex 的事------Claude Code、Cursor、Windsurf，只要是走 OpenAI Responses API 的工具，碰到国产模型都会有同样的协议问题，CC Switch 的代理方案说到底是一个通用解法。

既然看到这里了，如果觉得不错，随手点个赞、在看、转发三连吧，如果可以给我个星标⭐，将不胜感激～谢谢你看我的文章，我们，下次再见。

#Codex #CCSwitch #DeepSeek #开源模型 #AI编程

作者：大象 - 推动 AI 共学，让普通人轻松上手 AI

Codex 接入开源模型完整配置指南

你配半天连不上的原因，不在你

架构断层怎么补：中间层代理

开始配置：你需要准备什么

配置 CC Switch：这里面坑最多

第一步：选择模型预设

第二步：填入 API Key

第三步：开启 Needs Local Routing

第四步：在路由页面确认开关状态

重启 Codex，让它发现代理

验证：三层检查确保配置生效

第一层：模型列表检查

第二层：发送测试消息

第三层：路由计数验证

常见问题诊断清单

实测体验：三个模型的真实体感

DeepSeek V4 Flash：日常主力

DeepSeek V4 Pro：重活才用

本地 Qwen 35B：安全优先场景

模型选择决策框架

CC Switch 的几个高级用法

多工具隔离配置

多提供商同时在线

配置存在本地

最后几个实操建议

更新 CC Switch（macOS）

补充：Responses API vs Chat Completions API 差异到底意味着什么

总结一下：