Codex 接入自定义 API：配置前先看清这 3 个坑

先说结论

• Codex 版本决定 wire_api 类型，0.80.0 以下用 chat，以上用 responses，选错直接报错。

• API Key 必须通过环境变量传递，不能直接写在配置文件中，否则有安全风险。

• base_url 本地服务用 http，用 https 会导致 SSL 错误，除非配置 allow_insecure。

从踩坑角度讲 Codex 自定义 API 配置，重点不是步骤而是容易忽略的版本和协议匹配问题。

最近不少人在折腾 Codex 接入自定义 API，想用本地模型或者国产大模型替代 OpenAI。配置本身不复杂，但如果你直接按网上教程抄，大概率会遇到几个坑。我梳理了一下，最关键的其实不是怎么写配置文件，而是版本和协议匹配。

先说结论：Codex 0.80.0 是个分水岭。低于这个版本，它只支持 Chat Completions API（wire_api = “chat”）；高于这个版本，它只支持 Responses API（wire_api = “responses”）。如果你 API 服务只支持 chat 格式，却装了新版 Codex，就会看到 “wire_api = chat is no longer supported” 这样的报错。反过来也一样。所以第一步不是写配置，而是确认你的 API 服务支持哪种协议，然后选择对应版本的 Codex。

为什么这事值得聊？因为很多人想省成本，用本地部署的模型或者国产 API 服务，这些服务绝大多数只支持 Chat Completions 格式。而 Codex 新版默认只支持 Responses，这就导致要么降级 Codex，要么改造 API 服务。降级简单，但会失去新版的功能更新；改造 API 服务则可能涉及代码修改，不是所有人都愿意干。

方案拆解：假设你决定用 0.80.0 版本，配置过程其实很直接。首先安装指定版本：npm install -g @openai/codex@0.80.0。然后创建配置文件 ~/.codex/config.toml，核心内容如下：

model = "your-model-name"
model_provider = "custom"

[model_providers.custom]
base_url = "http://localhost:8080/v1"
wire_api = "chat"
env_key = "CUSTOM_API_KEY"

注意：env_key 填的是环境变量名，不是 API Key 本身。API Key 要通过 export CUSTOM_API_KEY="sk-xxx" 设置，并写入 ~/.zshrc 使其永久生效。

这里有一个容易忽略的点：base_url 如果是本地服务，一定要用 http，不要用 https。本地自签名证书会导致 SSL 错误，除非你在配置里加 allow_insecure = true，但仅限开发环境。

适用边界：这种配置方式适合个人开发者或小团队，因为环境变量管理简单，但缺乏审计和权限控制。如果在大团队里，多个项目共用同一台机器，API Key 混在一起，容易泄露。更现实的做法是使用项目级配置（在项目根目录下放 .codex/config.toml），每个项目独立设置环境变量，并确保 .codex/ 目录被 .gitignore 忽略。

另外，多 Provider 管理虽然灵活，但切换成本不低。如果你经常在本地模型和云端模型之间切换，建议在配置文件中定义多个 Provider，然后通过 codex -m model-name --provider provider-name 临时指定。但注意，--model-provider 这个参数名是错的，正确的是 --provider。

最后留一个讨论点：如果你的 API 服务只支持 chat 协议，你会选择降级 Codex 到 0.80.0，还是改造 API 服务去支持 responses？两种方案都有代价，降级省事但可能错过新功能，改造则增加维护成本。你更倾向哪一种？

最后留一个讨论点

你更倾向用低版本 Codex 兼容 chat 协议，还是升级 API 服务支持 responses 协议？为什么？