Codex 连接第三方大模型接口时，模型名不是随便填一个名称就能用。Codex 会把配置中的 model 字符串原样放进请求体的 model 字段，第三方服务根据这个字段查找对应模型。如果配置里写了 gpt-4，但服务端只认识 deepseek-chat，请求就会直接失败。很多人习惯照搬 OpenAI 官方示例，却在第三方接口上收到模型不存在或参数错误，核心原因就在这里。
一、模型名为什么不能照搬 OpenAI 官方名称
OpenAI 的模型名如 gpt-4o、o3 只在 OpenAI 自己的接口里有效。第三方服务虽然兼容 OpenAI 的接口格式，但模型列表是各自维护的，不会因为你写了 gpt-4 就自动路由到某个对应模型。所谓兼容 OpenAI 协议，通常只是请求路径和参数结构相似，并不代表模型标识也沿用 OpenAI 的命名。
以 DeepSeek 为例，它的对话模型名是 deepseek-chat，推理模型名是 deepseek-reasoner。如果在 Codex 里填 gpt-4o，DeepSeek 服务端找不到这个模型，就会返回 404。类似地，通义千问的 OpenAI 兼容接口使用 qwen-plus、qwen-max，而不是中文名称或 OpenAI 风格名称。模型名应当是服务商 API 文档中给出的英文标识，界面上的产品名通常不能直接使用。
模型名不仅影响请求是否成功，还可能影响上下文长度、输出价格和工具调用能力。比如同一个服务商的不同模型名可能对应不同上下文窗口，填错后即使返回正常，也可能因为上下文太小而截断代码。填写前最好到服务商的控制台或模型列表页面确认可用的模型标识。
二、Codex CLI 的配置结构和正确填法
Codex CLI 的配置通常保存在用户目录下的 config.toml 文件中，Linux 和 macOS 路径是 ~/.codex/config.toml，Windows 路径是 %USERPROFILE%\.codex\config.toml。在这个文件里，model 指定要使用的模型名，model_provider 指定从哪个提供商配置读取连接信息。第三方 API 需要在 model_providers 表中增加一项，包含 name、base_url、env_key 和 wire_api。
下面是一个对接 DeepSeek 的典型配置。注意 base_url 是否包含 /v1 要以服务商文档为准，DeepSeek 的 OpenAI 兼容地址需要带上 /v1。env_key 表示从哪个环境变量读取 API Key，这里使用 DEEPSEEK_API_KEY。如果环境变量名不同，需要按实际情况调整。
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"
保存配置后，Codex 会把 model 的值原样拼接到请求体里，并请求 base_url 下面的 chat/completions 路径。如果 base_url 写成了 https://api.deepseek.com，实际请求路径就可能缺少 /v1，导致 404。因此 base_url 的结尾斜杠和版本路径要完全按文档填写，不能多也不能少。
还应注意 wire_api 的选择。大多数第三方服务目前只支持 OpenAI 的 chat 接口，所以这里填 chat 最稳妥。少数新服务可能支持 responses 接口，但第三方兼容性参差不齐，如果填了 responses 后调用失败，可以优先改回 chat 再测试。
三、常见第三方服务的模型名与 base_url 对照
不同服务商的模型名和接口地址可以从各自文档获取，下面是部分常用组合，适用于 OpenAI 兼容协议。填写时应以服务商最新文档为准，但模型名格式通常比较稳定。
| 服务商 | 模型名示例 | base_url | 说明 |
|---|---|---|---|
| DeepSeek | deepseek-chat | https://api.deepseek.com/v1 | 推理模型用 deepseek-reasoner |
| Moonshot | moonshot-v1-8k | https://api.moonshot.cn/v1 | 也支持 kimi-k2-0711-preview |
| 通义千问 | qwen-plus | https://dashscope.aliyuncs.com/compatible-mode/v1 | 还有 qwen-max、qwen-turbo |
| OpenRouter | openai/gpt-4o-mini | https://openrouter.ai/api/v1 | 模型名必须带前缀 |
| Groq | llama-3.3-70b-versatile | https://api.groq.com/openai/v1 | 注意路径包含 openai |
OpenRouter 这类聚合服务的模型名带有前缀，比如 openai/gpt-4o-mini 或 anthropic/claude-3.5-sonnet。如果只填 gpt-4o-mini，OpenRouter 无法判断应该路由到哪家上游，会直接报错。类似的聚合网关还有不少，填写前一定要看清楚模型全名。
如果使用的是企业或自建网关，模型名可能是网关后台配置的自定义名称，而不是上游真实名称。此时不能直接照搬公开 API 文档，需要查看网关管理页面，或者咨询网关管理员。很多团队内部的网关会把 gpt-4o 映射成 internal-gpt-4o，这类信息只能从自己的系统里获取。
四、用 curl 快速验证模型名是否有效
在写入 Codex 配置前，直接用 curl 调用一次 chat/completions 可以快速确认模型名和 base_url 是否正确。验证通过后再配置进 Codex，能减少后续排查成本，也能把问题范围缩小到模型名、地址或 Key 三者之一。
curl https://api.deepseek.com/v1/chat/completions \
-H "Authorization: Bearer $DEEPSEEK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"deepseek-chat","messages":[{"role":"user","content":"ping"}]}'
返回结果里如果包含 choices 数组，说明模型名有效，请求已经正常到达服务端。如果返回 404 且错误信息包含 model_not_found，说明模型名不对或 base_url 路径不对。如果返回 401，说明 API Key 没传或无效。通过错误类型可以快速区分问题来源。
Windows 终端里执行 curl 时，JSON 字符串的引号和换行符可能需要调整，建议把上面的命令写成一行，或者把 JSON 保存成文件后用 -d @body.json 方式提交。模型名要保证没有首尾空格，也不要把复制文档时带入的特殊空格写进去。
五、模型名填错的常见报错与排查顺序
模型名填错后，Codex 通常会输出类似 404 Not Found、model_not_found、invalid model 或 Model does not exist 的信息。这些报错都指向同一个问题：服务端没有找到名为该字符串的模型。此时不需要反复重试，先检查配置反而更快。
排查时可以按这个顺序来：先确认模型名大小写是否完全一致，然后检查配置中 model 与 model_provider 是否对应，再确认 base_url 是否包含正确的版本路径，最后用 curl 验证。若这些都正确但仍然报错，可能是账户权限不足或模型不在白名单内。
如果使用了第三方中转，模型名可能被要求加上前缀或后缀，比如把 gpt-4o 写成 openai/gpt-4o。需要以中转站文档为准，不要凭经验填写。配置修改后建议重启 Codex CLI 相关进程，避免旧的环境变量缓存影响后续请求。