1. 为什么要把 Codex 接到国产大模型上
Codex 这个工具刚火起来那阵子，我身边不少朋友第一反应就是去官网下载、装桌面版、登录账号，然后发现要么卡在验证环节，要么用起来成本不低。我自己也是折腾了好几轮，从最初的codex安装、codex登录，到后来遇到unexpected status 401 unauthorized: incorrect api key provided这种报错，再到研究config.toml到底该怎么写，踩的坑基本能凑成一本小册子。
核心痛点其实就一个：Codex 本身是一个客户端形态的编程助手，它的能力上限取决于背后接的是哪个模型。官方默认走的那套服务，对国内用户来说存在网络链路和计费两方面的门槛。而这两年国产大模型进步非常快，DeepSeek、通义千问、Kimi、智谱 GLM 这些在代码补全、函数生成、重构建议上的表现已经相当能打，关键是它们普遍提供了OpenAI 兼容接口，这就给"换后端"提供了技术前提。
所谓"对接国产廉价大模型"，本质上是把 Codex 的请求地址从官方端点改成一个兼容 OpenAI 协议的自建或第三方端点，再把 API Key 换成对应厂商的 Key。听起来简单，但实际操作里config.toml的字段名、模型标识、路由前缀、认证头格式，每一项写错都会直接抛 401 或者静默失败。我见过太多人卡在codex is ignoring 1 unrecognized configuration setting这种提示上，明明配置写了却完全不生效，原因往往就是字段名拼错或者用了已废弃的写法。
这篇内容适合三类人：一是刚接触 Codex、想先把环境跑通的新手；二是已经在用官方服务、想换成更便宜后端的进阶用户；三是被各种 401、配置不生效问题折磨过、想彻底搞懂配置逻辑的折腾党。我会把config.toml的结构、OpenAI 兼容接口的对接原理、常见报错的排查路径全部拆开讲，尽量做到你照着抄就能用。
2. Codex 的配置体系与国产模型对接原理
2.1 Codex 到底读的是哪份配置
很多人第一次找配置文件就懵了，因为 Codex 在不同系统下的路径不一样，而且桌面版和 CLI 版读的位置也可能有差异。Windows 下最常见的是用户目录下的.codex文件夹，也就是类似C:\Users\你的用户名\.codex\config.toml这个位置。热词里出现的c:\users\丁子洋.codex\config.toml就是典型的 Windows 路径写法，注意中间那个点是用户名和.codex之间的分隔，不是路径错误。
这里有个特别容易踩的坑：文件名必须是config.toml，扩展名不能是.txt或者.toml.txt。Windows 默认隐藏已知扩展名，你用记事本另存为的时候很容易变成config.toml.txt，然后 Codex 根本读不到，你还以为是配置内容写错了。我的建议是先在文件夹选项里把"隐藏已知文件类型的扩展名"关掉，确认文件名干净。
配置文件的加载优先级也值得说一句。Codex 一般会按"当前项目目录 → 用户主目录 → 全局默认"的顺序去找配置，项目级的配置会覆盖用户级的。如果你在项目里放了一份config.toml，又在家目录放了一份，结果发现改家目录那份没反应，八成是被项目级的那份盖住了。排查的时候先确认你到底在改哪一份。
2.2 OpenAI 兼容接口是怎么回事
国产大模型厂商为了降低迁移成本，基本都实现了 OpenAI 的接口协议。什么意思呢？就是原本发给https://api.openai.com/v1/chat/completions的请求，你只要把域名换成厂商的地址，请求体的 JSON 结构、认证头的格式都不用动，就能拿到格式一致的响应。
这个兼容层通常包含几个关键部分：
- Base URL：厂商提供的接口根地址，一般以
/v1结尾，比如https://api.某厂商.com/v1。注意有些厂商给的是不带/v1的，你需要自己补上，补错了就会 404。 - API Key：厂商控制台生成的密钥，通常是一串
sk-开头的字符串。热词里那个sk-svcac****就是典型的 Key 格式。 - Model 名称：厂商定义的模型标识，比如
deepseek-chat、qwen-plus、glm-4这类。这个必须和厂商文档里写的完全一致，写错了会返回模型不存在的错误。 - 认证方式：标准做法是请求头里带
Authorization: Bearer <你的Key>。有些厂商还支持额外的 header，但基础兼容模式下这一条就够了。
Codex 作为客户端，它内部其实也是按这套协议发请求的。所以对接国产模型，本质上就是告诉 Codex："别去官方地址了，去我指定的这个地址，用我给的这把钥匙。"
2.3 为什么会出现 unrecognized configuration setting
热词里反复出现codex is ignoring 1 unrecognized configuration setting. check for typos or deprecated settings，这个提示的意思是：Codex 读到了你的配置文件，但里面有一个字段它不认识，于是选择忽略。
造成这个问题的原因主要有三类：
第一类是字段名拼写错误。TOML 对大小写和拼写是敏感的，api_key和apikey是两个完全不同的东西，base_url和baseURL也不一样。我见过有人把model写成models，结果配置直接失效。
第二类是用了已废弃的字段。Codex 迭代比较快，早期版本支持的某些配置项在新版本里被移除了。比如热词里提到的mcp_servers.node_repl.type is ignored，就是某个 MCP 相关字段在新版本里不再被识别。这种情况要么删掉这个字段，要么去查当前版本的文档看它被换成了什么。
第三类是层级放错了位置。TOML 是有层级结构的，某个字段必须放在特定的 section 下面才生效。如果你把本该放在[model_providers.xxx]下面的字段写到了顶层，Codex 就会认为这是个未知配置。
排查这类问题的思路很简单：从下往上删，删到不报错为止，再一个个加回来。这样能快速定位到底是哪个字段惹的祸。
3. config.toml 核心字段逐项拆解与实操配置
3.1 一份可直接参考的最小配置
先给一份我实测能跑通的最小配置骨架，你可以把它当成模板，把里面的占位符换成自己的信息：
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指定你要用的模型标识，model_provider指向下面定义的 provider 名称。[model_providers.deepseek]这个 section 里，base_url是接口地址，env_key是存放 API Key 的环境变量名，wire_api指定走的是 chat 还是 responses 协议。
注意env_key这个设计，它不让你把 Key 明文写在配置文件里，而是让你把 Key 放到环境变量里，配置只引用变量名。这样做的好处是配置文件可以安全地分享或者提交到仓库，不会泄露密钥。设置环境变量的方式在 Windows 和 macOS/Linux 下不一样，后面会单独讲。
3.2 base_url 的写法陷阱
base_url是最容易写错的地方，我把它单独拎出来说。常见的错误有这么几种：
- 漏了
/v1：很多厂商的接口根是https://api.xxx.com，但实际请求路径是/v1/chat/completions。如果你只写到域名，Codex 拼出来的地址就会缺一段，直接 404。 - 多写了
/chat/completions：有些人以为要写完整路径，结果 Codex 自己还会再拼一次，变成/v1/chat/completions/chat/completions，同样报错。base_url 只需要写到/v1这一层。 - 结尾多了斜杠：
https://api.xxx.com/v1/和https://api.xxx.com/v1在某些实现下行为不一致，稳妥起见不要带结尾斜杠。 - 用了 http 而不是 https：除非你本地自建了服务，否则一律用 https，http 会被拒绝或者存在安全风险。
我一般建议的做法是：拿到厂商文档给的地址后，先自己用 curl 测一下，确认base_url + /chat/completions能通，再往配置里填。这样能把网络问题和配置问题分开排查。
3.3 模型标识必须和厂商文档对齐
model字段填的是厂商定义的模型名，不是你想当然的名字。比如 DeepSeek 的对话模型叫deepseek-chat，你写成deepseek或者DeepSeek-Chat都可能失败，因为服务端是精确匹配的。
热词里出现过{"detail":"the 'gpt-5.6-sol' model is not supported when using codex with a..."}这种报错，本质就是模型名不被支持。这种情况要么是模型名写错了，要么是这个模型压根不支持当前接口协议。
我的经验是：配置前先去厂商的模型列表页确认准确的模型标识，复制粘贴，不要手打。手打特别容易把连字符打成下划线，或者把大小写搞错。
3.4 API Key 的存放与环境变量设置
前面说了 Key 要放环境变量，具体怎么设：
Windows 下有两种方式。临时的话在 PowerShell 里执行$env:DEEPSEEK_API_KEY="sk-你的key"，但关掉窗口就没了。永久的话用系统设置里的"环境变量"面板，新建一个用户变量，变量名填DEEPSEEK_API_KEY，值填你的 Key，然后重启终端让配置生效。
macOS 和 Linux 下，把export DEEPSEEK_API_KEY="sk-你的key"加到~/.bashrc或者~/.zshrc里，然后source一下。
这里有个高频坑：设完环境变量后必须重启 Codex 或者重启终端。因为进程启动时才会读取环境变量，你在 Codex 已经运行的状态下改环境变量，它是感知不到的。很多人改完发现还是 401，就是因为没重启。
还有一个坑是变量名不一致。配置里写的是env_key = "DEEPSEEK_API_KEY"，你环境变量却设成了DEEPSEEK_KEY，那 Codex 去找DEEPSEEK_API_KEY找不到，自然认证失败。这两个名字必须一字不差。
3.5 wire_api 选 chat 还是 responses
热词里出现过cc switch local proxy failed while handling codex endpoint /responses，这说明 Codex 在某些模式下会走/responses这个端点，而不是传统的/chat/completions。
/responses是较新的一套接口协议，功能更强但兼容性要求也更高。国产厂商的兼容层大多实现的是/chat/completions，对/responses的支持参差不齐。所以如果你对接国产模型，优先把wire_api设成chat，走传统协议，成功率最高。
如果你确实需要 responses 协议的特性，那就要确认厂商是否支持，不支持的话就会像热词里那样报 proxy failed。这种情况下退回 chat 协议是最省事的解法。
4. 完整对接流程与实测记录
4.1 从零开始的对接步骤
我把整个流程按顺序列一遍，你照着走基本不会漏：
- 确认 Codex 已正确安装并能启动。先不管模型，确保
codex命令能跑起来，或者桌面版能打开。如果这一步就卡住，先解决安装问题。 - 去国产模型厂商控制台注册并生成 API Key。以 DeepSeek 为例，登录后在 API Keys 页面创建一个，复制保存好，这个 Key 只显示一次。
- 设置环境变量。按前面说的方法把 Key 写进环境变量，重启终端。
- 创建或编辑
config.toml。放到用户目录的.codex文件夹下，内容参考前面的最小配置模板。 - 启动 Codex 并测试。随便问一个代码问题，看是否能正常返回。
- 根据报错调整配置。如果报 401 就查 Key 和环境变量，如果报模型不存在就查模型名，如果报 unrecognized 就查字段拼写。
4.2 一次真实的排查记录
我第一次配的时候，遇到的是unexpected status 401 unauthorized: incorrect api key provided: sk-svcac****。这个报错其实信息量很大：它明确告诉你 Key 被识别到了（因为显示了前缀sk-svcac），但服务端认为这个 Key 不对。
我当时的排查路径是这样的：
先确认 Key 本身有没有问题。我把同一个 Key 拿去用 curl 直接请求厂商接口，结果能通，说明 Key 是有效的。那就排除了 Key 失效的可能。
接着怀疑是不是环境变量没生效。我在终端里echo了一下那个变量，发现是空的。原因是我在 PowerShell 里设的临时变量，但 Codex 是从另一个终端启动的，两个终端的环境变量不共享。改成永久环境变量并重启后，问题解决。
这个案例的教训是：401 不一定是 Key 错，也可能是 Key 根本没被读到。区分方法是看报错里有没有显示 Key 的前缀，显示了说明读到了但不对，没显示说明压根没读到。
4.3 配置生效的验证方法
怎么确认你的配置真的被 Codex 读进去了？我的做法是故意写一个错误的模型名，比如model = "this-model-does-not-exist"，然后启动 Codex 发一个请求。如果它报"模型不存在"，说明配置被读到了，只是模型名不对；如果它还是走官方模型正常回复，说明你的配置压根没生效，得回去查文件路径和文件名。
这个"故意写错"的技巧特别好用，能快速区分"配置没生效"和"配置生效但内容错"这两种情况，避免在错误的方向上浪费时间。
5. 常见报错速查与避坑经验
5.1 报错对照表
| 报错信息 | 大概率原因 | 解决方向 |
|---|---|---|
401 unauthorized: incorrect api key | Key 错误或未被读取 | 检查环境变量名是否一致、是否重启终端 |
unrecognized configuration setting | 字段名拼错或已废弃 | 逐字段核对，删除废弃字段 |
model is not supported | 模型标识错误 | 去厂商文档复制准确模型名 |
local proxy failed ... /responses | 协议不兼容 | 把 wire_api 改成 chat |
auth token is unavailable | 认证信息缺失 | 确认 Key 已设置且格式正确 |
| 配置改了没反应 | 文件路径或文件名错误 | 确认是config.toml且在正确目录 |
| 请求超时 | 网络链路问题 | 检查 base_url 是否可达 |
5.2 几个我踩过的坑
坑一：配置文件编码问题。TOML 文件建议用 UTF-8 无 BOM 编码保存。有些编辑器默认存成带 BOM 的 UTF-8，Codex 解析时可能在第一个字段就出错。如果你发现配置怎么都不生效，可以试试换个编辑器另存为无 BOM 格式。
坑二：多个配置文件打架。前面提过项目级配置会覆盖用户级，但很多人不知道还有环境变量形式的配置。如果你之前设过某些 Codex 相关的环境变量，它们可能优先级更高，导致你改配置文件没用。排查时把所有相关环境变量都清一遍。
坑三：Key 里有隐藏字符。从网页复制 Key 的时候，有时候会带上首尾空格或者换行符。这种 Key 肉眼看不出来，但服务端校验会失败。建议复制后先粘到纯文本编辑器里看一眼，确认干净再往环境变量里放。
坑四：厂商接口有速率限制。廉价模型往往有 QPS 或者并发限制，请求太频繁会被限流。如果你发现偶尔成功偶尔失败，可能是触发了限流，适当降低请求频率或者升级套餐。
坑五：模型上下文长度不够。国产廉价模型的上下文窗口可能比官方小，喂太长的代码文件会被截断或者报错。这种情况要么换上下文更长的模型，要么把代码拆成小块再问。
5.3 关于成本和稳定性的取舍
对接国产廉价模型最大的吸引力就是成本。同样量的代码问答，国产模型的价格可能只有官方的几分之一甚至更低。但便宜也有便宜的代价：响应速度可能慢一些，复杂推理任务上的表现可能不如顶级模型，接口稳定性也可能有波动。
我的建议是分场景使用：日常的代码补全、简单函数生成、注释翻译这类任务，用国产廉价模型完全够用；遇到复杂的架构设计、疑难 bug 排查，再切回更强的模型。Codex 支持配置多个 provider，你可以根据任务类型灵活切换，没必要一刀切。
6. 多模型切换与进阶玩法
6.1 配置多个 provider 随时切换
Codex 的配置支持定义多个 provider，你可以在config.toml里同时写好 DeepSeek、通义、GLM 好几套，然后通过改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.qwen] name = "Qwen" base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1" env_key = "QWEN_API_KEY" wire_api = "chat"切换的时候只改model_provider = "qwen"和对应的model就行。注意每个 provider 的env_key要对应各自的环境变量，别搞混了。
6.2 用本地代理做统一入口
热词里出现了cc switch local proxy failed，说明有人尝试用本地代理来统一管理多个后端。这个思路是：在本地起一个代理服务，Codex 统一指向这个本地地址，由代理根据规则转发到不同的厂商。
这种方案的好处是配置集中、切换灵活，坏处是多了一层，出问题时排查链路变长。如果你只是个人用，直接配多个 provider 就够了，没必要上代理。代理更适合团队场景，需要统一管理和审计的时候。
6.3 关于模型能力的实测感受
我自己拿几个国产模型跑过同一批代码任务，说点主观感受。DeepSeek 在代码理解和生成上确实扎实，尤其是 Python 和 JavaScript，基本能跟上思路。通义千问在中文注释和技术文档翻译上更顺。GLM 在结构化输出、JSON 生成这类任务上比较稳。
但要说清楚，这些都是我个人的使用体感，不同任务、不同提示词下结果可能差别很大。最靠谱的办法是自己拿真实任务去测，别光看别人的评测。配置好之后，用你平时最常问的那类问题跑几轮，哪个顺手用哪个。
7. 一些收尾的实操建议
配置这件事，最怕的就是想当然。我见过太多人对着网上的教程抄，抄完不生效就开始怀疑人生，其实问题往往就出在一个字符上。我的习惯是每改一个字段就重启验证一次，虽然麻烦，但能保证每次改动都是有效的，出问题也能立刻定位到是哪一步引入的。
另外，config.toml建议做版本管理。你可以把它放到一个私有仓库里，每次改动都提交一下，这样哪天配置被改乱了，直接回滚就行。当然，前提是 Key 走环境变量，配置文件里不能有明文密钥。
最后分享一个小技巧：如果你不确定某个字段的正确写法，可以去看 Codex 的官方文档或者它自带的示例配置。很多客户端在安装目录下会放一份默认配置，那份文件里的字段名一定是对的，照着改最保险。实在找不到，就把配置精简到最小可用集，先跑通再加功能，别一上来就堆一大堆字段，那样出问题根本不知道是哪个引起的。
