Codex 接入自定义 API，先想清楚这 3 个问题再动手

先说结论

• Codex 版本决定了 API 协议类型：0.80.0 以下用 Chat Completions，以上用 Responses API，混用会报错。

• API Key 必须通过环境变量传入，不能直接写在 TOML 配置文件中，这是安全红线。

• 本地服务用 http，base_url 末尾带 /v1，wire_api 要和 API 实际类型一致，否则配置不生效。

从配置的版本陷阱和协议匹配难点切入，帮你避开那些文档没写的坑。

先聊一个真实场景：本地模型接不上 Codex

你花了一下午部署了一个 Qwen 模型，端口是 8080，curl 测试正常。结果 Codex 启动后，模型列表里空空如也。

然后你开始怀疑：是不是配置写错了？环境变量没加载？版本不对？最后发现——Codex 版本太新，已经抛弃了你 API 支持的 Chat Completions 协议。

这不是个例。本地模型接入命令行工具，版本和协议的兼容问题往往是第一道坎。

版本选择不是小事：0.80 前后两套协议

Codex 在 0.80.0 版本是一个重要的分界线：

• 0.80.0 及以下：使用 Chat Completions API，wire_api 参数填写 "chat"。
• 0.81.0 及以上：使用 Responses API，wire_api 参数填写 "responses"。

目前大多数国产模型和本地部署服务（包括 vLLM、Ollama 等）都只兼容 Chat Completions。如果你用的是新版 Codex，要么降级到 0.80.0，要么找能提供 Responses API 的后端。

更现实的做法是：一开始就装 0.80.0 版本。

npm install -g @openai/codex@0.80.0

别急着追新。工具是拿来用的，不是拿来升级的。

配置文件的三个关键字段，写错一个就白费

Codex 的配置文件是 TOML 格式，位置在 ~/.codex/config.toml。核心字段只有三个，但也是最容易出错的三个：

base_url

API 服务地址，本地服务一定用 http 而不是 https。很多人在这一步被 SSL 错误卡住。

正确的写法：

base_url = "http://localhost:8080/v1"

wire_api

协议类型，必须和你的 API 服务匹配。如果后端只支持 Chat Completions，你写 "responses" 就是找死。

env_key

这里填的是环境变量名，不是 API Key 本身。很多人直接填 "sk-xxx"，结果 Codex 读不到。

正确的做法：

env_key = "MY_API_KEY"

然后在终端设置：

export MY_API_KEY="sk-xxxx"

常见错误：Key 放错位置、协议不匹配、base_url 多 s

错误 1：API Key 写死在配置文件里

# ❌ 错误
env_key = "sk-xxxx"

这样既不安全，也不灵活。改成环境变量引用。

错误 2：wire_api 与版本不匹配

如果你装了 0.82.0 却写 wire_api = "chat"，Codex 会直接报错：

wire_api = chat is no longer supported

这时候要么降级，要么换 API 后端。

错误 3：base_url 末尾带多余路径

正确的格式是 http://localhost:8080/v1，不要多写 /chat/completions。Codex 内部会拼接路径。

错误 4：环境变量没生效

配置了 env_key 但 Codex 还是报找不到 Key。先检查：

echo $MY_API_KEY

如果显示为空，说明环境变量没加载。Mac 上记得执行 source ~/.zshrc 或重启终端。

多 Provider 切换：一个终端用多家模型

Codex 的 Provider 机制允许你配置多个模型后端，用 model_provider 字段自由切换。

model = "qwen3.6-plus"
model_provider = "local_qwen"

[model_providers.local_qwen]
name = "Local Qwen"
base_url = "http://localhost:8080/v1"
wire_api = "chat"
env_key = "QWEN_API_KEY"

[model_providers.cloud_gpt]
name = "Cloud GPT"
base_url = "https://api.openai.com/v1"
wire_api = "responses"
env_key = "OPENAI_API_KEY"

然后在命令行用 --provider 参数指定：

codex "写一个快速排序" --provider cloud_gpt

适合一个人团队，灵活管理多模型。但要注意：如果多个 Provider 的 wire_api 不同，切换时可能会触发协议不兼容问题。

写在最后：如果让我从头配置，我会先做什么

1. 先确认 API 服务类型：用 curl 测一下，看它返回的是 Chat Completions 格式还是 Responses 格式。
2. 再选择 Codex 版本：根据 API 类型决定用 0.80.0 还是最新版。
3. 配置文件和环境变量分开：配置文件只写结构，Key 永远走环境变量。
4. 用 codex config show 验证：确保加载的配置是你想要的。

整个过程其实不复杂，但版本和协议的坑很容易让人怀疑人生。

最后留一个问题：如果你要在团队里推广 Codex + 自定义模型，你会优先选择降级到 0.80.0 版本兼容已有服务，还是升级 API 服务来适配新版 Codex？为什么？

最后留一个讨论点

如果你要在团队里推广 Codex + 自定义模型，你会优先选择降级到 0.80.0 版本兼容已有服务，还是升级 API 服务来适配新版 Codex？为什么？