你明明已经在项目中添加了.codex/config.toml，也写好了model_provider、base_url和模型名，但 Codex 启动后仍然连接原来的服务，甚至继续报 401、404 或model not found。
这种情况不一定是 API Key 或中转线路出了问题。一个很容易忽略的原因是：Provider 配置被写进了项目级配置文件，而 Codex 会忽略项目级配置中的model_provider和model_providers。
本文用最短路径解释 Codex 的配置层级，并给出一套不泄露 API Key 的排查方法。
一、最常见的错误：把 Provider 放进项目目录
很多人会在仓库里创建：
你的项目/.codex/config.toml然后写入类似内容：
model = "控制台显示的模型 ID" model_provider = "my_provider" [model_providers.my_provider] name = "My Provider" base_url = "https://example.com/v1" env_key = "OPENAI_API_KEY" wire_api = "responses"文件语法可能完全正确，但 Provider 仍然不生效。
根据 OpenAI 官方 Codex Configuration Reference，用户级配置位于：
~/.codex/config.toml项目也可以拥有.codex/config.toml，但项目级配置不能覆盖机器本地的 Provider 和认证等设置。官方文档明确列出的项目级忽略项包括：
model_providermodel_providersopenai_base_urlchatgpt_base_urlprofile/profiles- 通知和遥测相关配置
所以，自定义 API Provider 应写在用户级~/.codex/config.toml，不要只放在某个项目下面。
二、正确的配置结构
下面是一个不包含真实地址、真实模型名和真实密钥的模板：
model = "控制台当前显示的模型 ID" model_provider = "my_provider" [model_providers.my_provider] name = "My Provider" base_url = "https://你的服务地址/v1" env_key = "OPENAI_API_KEY" wire_api = "responses"API Key 不要直接写进 TOML。建议在启动 Codex 的同一个终端中设置环境变量：
macOS / Linux：
exportOPENAI_API_KEY='你的_API_KEY'codexPowerShell：
$env:OPENAI_API_KEY='你的_API_KEY'codex如果从 IDE、启动器或另一个终端打开 Codex，需要确认那个进程是否继承了同一份环境变量。
三、5 分钟定位配置为何没有生效
1. 先确认文件位置
正确位置是当前用户主目录下的：
~/.codex/config.toml不要把~理解成当前项目目录。也不要只修改仓库中的.codex/config.toml来切换 Provider。
2. 检查 TOML 层级
下面两个字段是顶层字段：
model = "..." model_provider = "my_provider"Provider 的详细配置才放在对应表中：
[model_providers.my_provider]如果把顶层字段误放到前一个 TOML 表下面，文件可能仍能被解析，但含义已经不同。
3. Provider 名称必须完全对应
这两处名称必须一致：
model_provider = "my_provider" [model_providers.my_provider]大小写、下划线和拼写都要一致。
4. 模型名以当前控制台为准
不要直接复制几个月前教程里的模型名。第三方 Provider 展示的模型 ID 可能变化；模型名不匹配时，经常表现为 404 或model not found，而不是“配置文件不存在”。
5. 确认接口真的支持 Responses API
Codex 的 Agent 工作负载和普通聊天不同。一个只兼容旧式 Chat Completions 的接口，不一定能完整支持 Codex 的流式事件和工具调用。
配置中使用：
wire_api = "responses"同时需要服务端真正兼容 Responses API，而不是只修改路径名称。
6. 完全退出后重新启动
修改用户级配置和环境变量后，退出当前 Codex 进程，再从已经设置好环境变量的终端重新启动。不要用仍在后台运行的旧进程判断新配置是否有效。
四、如何区分配置问题与线路问题
可以用下面的判断顺序：
| 现象 | 优先检查 |
|---|---|
| 仍连接旧 Provider | 配置文件位置、model_provider是否写在项目级文件 |
| 401 / 403 | 环境变量、Key 权限、启动进程是否继承变量 |
| 404 / model not found | base_url、模型 ID、Provider 映射 |
| 普通问答正常，Codex 长任务失败 | Responses API、SSE 流、代理超时 |
| 偶发 429 | 并发、速率、Token 配额与自动重试 |
| 固定时间断流 | CDN、反向代理或网关空闲超时 |
不要一次同时改 Key、模型名、Provider 和网络。一次只改一个变量，才能知道真正的原因。
五、一个更安全的配置方法
如果你不想手写 TOML，可以使用这个免费 Codex 配置生成器：
https://t6016884321-maker.github.io/vidai-config-generator/
它不会要求输入真实 API Key，所有输出都使用占位符；配置只在浏览器本地生成，复制前可以完整检查。页面同时提供 401、model not found和配置未生效的排错入口。
如果需要用真实仓库验证 Codex 长任务，可在 VidAI（胃袋AI）先做小额试跑，再决定是否长期使用：
https://api.david-ai.net/register?aff=5SM2BCS7ML2H&utm_source=csdn&utm_medium=organic&utm_campaign=codex_config_location_202610
建议使用同一个仓库依次完成：只读分析、跨文件修改、运行测试，并记录重连次数、总耗时、实际扣费和是否成功。不要用一次短问答代替稳定性测试。
六、最终检查清单
- Provider 写在
~/.codex/config.toml，而不是只写在项目目录； model_provider与[model_providers.<id>]的 ID 完全一致；- 模型 ID 来自当前控制台；
- API Key 通过环境变量提供，没有写进文章、截图或仓库；
base_url路径与服务端要求一致；- 服务端支持 Responses API 和持续 SSE；
- 修改后彻底退出并从同一终端重新启动 Codex；
- 先用小任务验证，再跑真实仓库长任务。
总结
Codex 自定义 API “配置不生效”时，不要第一时间更换 Key 或重装客户端。先检查 Provider 是否被错误地写进项目级.codex/config.toml。项目配置适合存放项目相关的行为设置，但机器本地的 Provider 和认证配置应放在用户级~/.codex/config.toml。
把配置层级、模型 ID、环境变量和 Responses API 逐项拆开验证，通常比反复复制别人的完整配置更快，也更安全。
参考资料：OpenAI 官方 Codex Configuration Reference：
https://learn.chatgpt.com/docs/config-file/config-reference
-公式原理详解与性能测评 Matlab代码免费获取)
