1. 为什么要在 Codex 上接国产大模型Codex 这个工具刚火起来的时候大部分人第一反应是去搞一个官方 API Key然后老老实实按官方文档配。但实际用下来你会发现两个很现实的问题一是官方接口的调用成本对高频使用者来说并不便宜尤其是拿它跑批量重构、长上下文分析这类任务时token 消耗速度远超预期二是网络链路的稳定性在某些时段会明显波动导致请求超时、响应中断体验断断续续。国产大模型这两年的进步有目共睹DeepSeek、通义千问、Kimi、智谱 GLM 这些模型在代码理解、长文本处理上的表现已经相当能打而且价格普遍比官方接口低一个数量级。更关键的是它们大多提供了OpenAI 兼容接口这意味着只要 Codex 支持自定义 base_url 和 API Key理论上就能无缝切换。我最初的想法很简单把 Codex 的后端从官方接口换成国产模型成本降下来速度提上去。但真正动手之后才发现这里面有一堆细节坑——配置文件格式、字段命名、认证方式、模型名称映射任何一个环节出错都会导致 401、404 或者配置被忽略的报错。这篇文章就是把我踩过的坑和最终跑通的方案完整记录下来适合已经装好 Codex、想接国产模型但被配置卡住的人。提示本文讨论的是 Codex CLI 及桌面版的配置方式核心思路对所有支持 OpenAI 兼容协议的模型服务商通用。2. Codex 的配置文件到底长什么样2.1 config.toml 的位置与结构Codex 的配置核心是一个叫config.toml的文件Windows 下默认路径是C:\Users\你的用户名\.codex\config.tomlmacOS 和 Linux 下是~/.codex/config.toml。这个文件用的是 TOML 格式和 JSON、YAML 一样是结构化配置语言但语法更接近 INI读起来比较直观。很多人第一次打开这个文件会懵因为官方文档给的示例和实际生成的默认配置不完全一致。一个典型的 config.toml 结构大概是这样model gpt-4o model_provider openai [model_providers.openai] name OpenAI base_url https://api.openai.com/v1 env_key OPENAI_API_KEY wire_api chat这里有几个关键字段需要理解model指定默认使用的模型名称这个名称必须和服务商支持的模型 ID 完全一致写错了会直接报模型不支持。model_provider指定使用哪个 provider 配置块对应下面[model_providers.xxx]里的 xxx。base_urlAPI 的根地址注意结尾要不要带/v1取决于服务商这个后面会详细说。env_key环境变量的名字Codex 会从这个环境变量里读取 API Key而不是直接把 Key 写在配置文件里。wire_api协议类型chat对应/v1/chat/completionsresponses对应/v1/responses这个字段选错是很多报错的根源。2.2 为什么 Key 要放在环境变量里把 API Key 直接写进 config.toml 看起来省事但有两个问题一是配置文件容易被误传到 Git 仓库或者分享给别人造成 Key 泄露二是 Codex 的某些版本会忽略配置文件里的明文 Key 字段只认环境变量。所以正确做法是在系统里设置环境变量。Windows 下可以用 PowerShell[System.Environment]::SetEnvironmentVariable(DEEPSEEK_API_KEY, sk-你的key, User)macOS 和 Linux 下在~/.bashrc或~/.zshrc里加一行export DEEPSEEK_API_KEYsk-你的key设置完之后要重启终端或者手动 source 一下配置文件否则当前会话读不到新变量。这一步看起来简单但我见过太多人设置完没重启终端然后一直报 401白白折腾半小时。2.3 那些配置被忽略的警告是怎么回事热词里频繁出现codex is ignoring 1 unrecognized configuration setting和mcp_servers.node_repl.type is ignored这类提示本质上是 Codex 在解析 config.toml 时遇到了它不认识的字段。TOML 解析器本身是宽容的不认识的字段不会导致崩溃但 Codex 会打印警告告诉你这个字段被跳过了。这种情况通常有三个原因一是你用的配置字段是旧版本遗留的新版本已经改名或废弃二是字段层级放错了比如把本该在[model_providers.xxx]下的字段写到了顶层三是拼写错误TOML 对大小写和拼写很敏感。处理办法很直接对照当前版本的官方配置文档把不认识的字段删掉或者改对。如果这个字段确实是你需要的功能那就去查对应版本的迁移说明。不要觉得警告无所谓有时候一个被忽略的字段恰恰就是导致功能不生效的原因。3. 国产模型服务商的接口差异与选型3.1 OpenAI 兼容不等于完全一致几乎所有国产模型都宣称兼容 OpenAI 接口但兼容的程度参差不齐。有的只兼容/v1/chat/completions有的连/v1/models都不支持有的支持stream流式输出有的流式返回格式和官方有细微差别还有的模型名称必须用它们自己的 ID不能直接用gpt-4o这种名字。我在选型时主要看三个维度接口兼容度、模型能力、价格。下面是我实际测试过的几家对比服务商兼容接口推荐模型价格档位备注DeepSeekchat/completionsdeepseek-chat、deepseek-coder低代码能力强长上下文表现好通义千问chat/completionsqwen-max、qwen-coder中生态完善文档清晰智谱 GLMchat/completionsglm-4、glm-4-flash低到中flash 版本性价比极高Kimichat/completionsmoonshot-v1-8k/32k/128k中长文本处理是强项选哪个取决于你的使用场景。如果是日常写代码、改 bugDeepSeek 和 qwen-coder 都很合适如果是分析超长文档Kimi 的 128k 上下文更稳如果追求极致性价比GLM-4-Flash 几乎可以忽略成本。3.2 base_url 的坑到底带不带 /v1这是最容易出错的地方。OpenAI 官方的 base_url 是https://api.openai.com/v1Codex 会在这个地址后面拼接/chat/completions。但国产服务商的地址规则不统一DeepSeek 的 base_url 是https://api.deepseek.com注意它不带/v1但实际请求路径是/chat/completions所以 Codex 里要写成https://api.deepseek.com/v1才能正确拼接。通义千问的兼容地址是https://dashscope.aliyuncs.com/compatible-mode/v1这个必须带/v1。智谱的地址是https://open.bigmodel.cn/api/paas/v4注意是v4不是v1。判断方法很简单看服务商文档里给的完整请求示例把/chat/completions之前的部分作为 base_url。如果文档给的示例是https://api.deepseek.com/chat/completions那 base_url 就是https://api.deepseek.com如果是https://xxx.com/v1/chat/completions那 base_url 就是https://xxx.com/v1。3.3 wire_api 选 chat 还是 responsesCodex 支持两种协议chat和responses。chat对应标准的/v1/chat/completions这是绝大多数国产模型支持的responses是 OpenAI 较新的接口格式国产模型基本都不支持。热词里出现的cc switch local proxy failed while handling codex endpoint /responses就是因为 wire_api 配成了responses但后端服务商根本没有这个端点请求直接失败。解决办法就是把wire_api改成chat。[model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat这个字段看起来不起眼但它决定了 Codex 往哪个路径发请求配错了后面全白搭。4. 完整配置实战从零跑通 DeepSeek4.1 环境准备与安装确认在动手改配置之前先确认 Codex 本身装好了。Windows 下可以用 npm 安装npm install -g openai/codex装完之后运行codex --version能打印出版本号就说明安装成功。如果提示命令找不到检查一下 npm 的全局 bin 目录有没有加到 PATH 里。然后确认 config.toml 存在。如果~/.codex/目录下没有这个文件手动创建一个空的就行Codex 启动时会读取它。4.2 写入 provider 配置块打开 config.toml写入以下内容model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat这里model填的是 DeepSeek 的模型 IDdeepseek-chat不是gpt-4o。如果你填了gpt-4o请求发到 DeepSeek 那边会因为模型不存在而报错。4.3 设置环境变量并验证按前面说的方法设置好DEEPSEEK_API_KEY环境变量然后重启终端。验证环境变量是否生效echo $DEEPSEEK_API_KEYWindows PowerShell 下用echo $env:DEEPSEEK_API_KEY能打印出你的 Key 就说明设置成功了。如果打印为空说明环境变量没生效检查一下是不是设置到了错误的用户级别或者终端没重启。4.4 启动测试与常见报错对照配置完成后运行codex随便问一个问题测试。如果一切正常你会看到模型正常返回内容。如果报错对照下表排查报错信息原因解决办法401 UnauthorizedAPI Key 错误或未读取到检查环境变量名是否和 env_key 一致404 Not Foundbase_url 路径错误确认 base_url 是否包含正确的版本路径model not supported模型 ID 写错换成服务商文档里的准确模型 IDconnection timeout网络不通检查网络连接和服务商状态unrecognized setting配置字段无效删除或修正该字段热词里那个unexpected status 401 unauthorized: incorrect api key provided: sk-svcac****就是典型的 Key 问题。注意看它打印出来的 Key 前缀如果前缀和你设置的不一样说明 Codex 读到了另一个环境变量或者缓存了旧 Key。5. 多模型切换与进阶配置5.1 配置多个 provider 随时切换实际使用中我经常需要在不同模型之间切换——写代码用 DeepSeek分析长文档用 Kimi快速问答用 GLM-Flash。Codex 支持配置多个 provider通过修改model_provider字段来切换model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat [model_providers.kimi] name Kimi base_url https://api.moonshot.cn/v1 env_key MOONSHOT_API_KEY wire_api chat [model_providers.glm] name GLM base_url https://open.bigmodel.cn/api/paas/v4 env_key GLM_API_KEY wire_api chat切换时只需要改model和model_provider两行。如果嫌手动改麻烦可以写个小脚本或者用环境变量覆盖。5.2 用 profile 管理不同场景Codex 支持 profile 机制可以预设几套配置启动时用--profile参数指定[profiles.code] model deepseek-chat model_provider deepseek [profiles.doc] model moonshot-v1-128k model_provider kimi启动时用codex --profile code就会加载对应的配置。这个功能在需要频繁切换场景时特别省事。5.3 关于 cc switch 和本地代理热词里出现了cc switch local proxy failed和ccswitch配置codex这涉及到一个叫 cc switch 的工具它的作用是帮你在不同配置之间快速切换。但这类工具本质上是在 Codex 和模型服务商之间加了一层本地代理代理层如果配置不当就会出现 endpoint 不匹配、协议转换失败等问题。我的建议是如果你只是接一两个国产模型直接用 Codex 原生的 provider 配置就够了不需要引入额外的代理层。多一层代理就多一个故障点排查问题时会复杂很多。只有在需要做复杂的请求改写、多服务商负载均衡时才考虑上代理。6. 踩坑实录那些让我折腾半天的报错6.1 配置改了但完全不生效有一次我改完 config.toml重启 Codex发现行为完全没变还是走的老配置。排查了半天才发现Codex 在某些系统上会缓存配置需要删掉~/.codex/目录下的缓存文件才会重新读取。更隐蔽的一种情况是系统里存在多个 config.toml——比如你之前用某个工具生成过一份放在别的路径Codex 优先读了那一份。排查方法启动 Codex 时加详细日志参数看它实际加载的是哪个路径的配置文件。确认路径后只保留一份配置其余删掉。6.2 环境变量名大小写踩坑Windows 的环境变量不区分大小写但 Codex 读取时是区分大小写的。我有一次设置的是deepseek_api_key但 config.toml 里写的是DEEPSEEK_API_KEY结果一直报 401。改成完全一致后立刻就好了。这个坑的隐蔽之处在于Windows 的echo $env:xxx不区分大小写也能打印出来让你误以为设置对了。所以设置环境变量时养成和配置文件里env_key完全一致的习惯。6.3 流式输出中断与超时设置国产模型在流式输出时偶尔会出现响应中途断开的情况尤其是长回答。这通常是网络波动或者服务端的超时限制导致的。Codex 本身有一些超时相关的配置可以在 config.toml 里调整[model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat request_timeout_ms 120000把超时时间调大一些能减少长回答被截断的概率。但如果是服务商侧的限制调这个也没用只能换模型或者缩短单次请求的内容。6.4 模型名称映射的坑有些服务商的模型 ID 和展示名称不一致。比如文档里写的是通义千问-Max但实际 API 调用时要用qwen-max。如果你在 config.toml 里填了中文名称请求会直接失败。解决办法永远以服务商 API 文档里的模型 ID或model 参数为准不要用产品页上的展示名称。拿不准的话可以先调一下服务商的/v1/models接口看看返回的模型列表里有哪些 ID。7. 成本与性能的实测对比7.1 实际 token 消耗与费用我拿同一个代码重构任务约 8000 行 Python 代码的分析与改写在几个模型上跑了一遍记录了大致的 token 消耗和费用模型输入 token输出 token估算费用完成时间官方接口约 12 万约 3 万较高约 4 分钟DeepSeek约 12 万约 3 万低约 3 分钟GLM-4-Flash约 12 万约 3 万极低约 2 分钟Kimi 128k约 12 万约 3 万中约 5 分钟费用差距是数量级的这也是我坚持用国产模型的核心原因。当然不同模型在代码质量上确实有差异DeepSeek 和 qwen-coder 在代码任务上表现最接近官方GLM-Flash 速度快但复杂逻辑处理稍弱。7.2 响应速度的影响因素响应速度不只取决于模型本身还和几个因素有关一是服务商当前的负载高峰期会明显变慢二是你的网络到服务商机房的链路质量三是请求的上下文长度上下文越长首 token 延迟越高。实测下来DeepSeek 和 GLM 的响应速度最稳定Kimi 在处理超长上下文时首 token 延迟会明显增加但一旦开始输出速度还是可以的。7.3 什么场景适合用哪个模型根据我的使用经验给几个场景的推荐日常写代码、改 bugDeepSeek 或 qwen-coder代码理解准确价格低。快速问答、简单任务GLM-4-Flash速度极快成本几乎可以忽略。长文档分析、大文件重构Kimi 128k 或 DeepSeek上下文窗口够大。需要高质量推理的复杂任务qwen-max 或 DeepSeek逻辑能力更强。8. 一些容易被忽略的细节8.1 config.toml 的编码问题TOML 文件必须是 UTF-8 编码如果你在 Windows 下用记事本编辑可能会被存成带 BOM 的 UTF-8导致 Codex 解析失败。建议用 VS Code 或者 Notepad 编辑保存时确认编码是 UTF-8 无 BOM。8.2 注释和空行的处理TOML 支持#开头的注释但要注意注释不能写在字符串内部。另外配置块之间的空行不影响解析但为了可读性建议每个 provider 块之间留一个空行。8.3 版本升级后的配置迁移Codex 更新比较频繁有时候新版本会改配置字段名或者废弃某些字段。升级后如果发现配置不生效第一件事就是去看更新日志里的配置变更说明。热词里那些is ignored的警告很多就是版本升级后旧字段没清理导致的。8.4 关于 API Key 的安全最后强调一点API Key 等同于你的账户凭证泄露了别人就能用你的额度。不要把 Key 写进任何会公开的文件里包括 config.toml、代码仓库、聊天记录。用环境变量是最基本的防护如果条件允许还可以给 Key 设置调用额度上限和 IP 白名单。我在实际使用中养成的习惯是每个服务商单独建一个 Key只用于 Codex这样即使某个 Key 泄露影响范围也可控。定期检查各服务商的用量统计发现异常消耗及时更换 Key。这套流程跑下来既享受了国产模型的低成本又不用担心安全问题。