Codex 是 OpenAI 的编程代理产品，常见形态包括命令行工具 Codex CLI、IDE 扩展和云端任务。很多团队想把它接到自己的 API 入口上，用统一 Key、统一账单，或者使用网关提供的模型。需要先说明：Codex 并没有一套独立的「Codex API」，Codex CLI 调用的是 OpenAI 的 Responses 接口，所谓自定义 API，本质是把请求的 Base URL、Key 和模型名换成兼容端点。
本文以 2026 年 10 月的常见版本为例，讲清三件事：Codex CLI 怎么装、config.toml 怎么写、接上自定义网关后怎么验证和排错。
说明：OpenAI、Codex 是其权利人的商标，本文仅作技术接入说明。Codex 的协议要求、网关支持的接口与模型名可能随版本调整，请以官方文档和站内模型价格为准。
一、先分清 Codex 的三种形态
| 形态 | 入口 | 能否用自定义 Key |
|---|---|---|
| Codex CLI | 终端执行 codex |
可以，通过 config.toml |
| IDE 扩展 | 编辑器侧边栏 | 以当前版本为准，通常跟随账号体系 |
| 云端任务 | 网页端 | 通常使用 ChatGPT 账号 |
对多数开发者来说，自定义 API 的主战场是 Codex CLI。它负责读代码、改文件、跑命令，模型只负责推理。把模型端点换掉，工具链仍然在本地执行。
二、Codex 的 API Key 与 Base URL
Codex CLI 的自定义 provider 需要三个参数：Base URL、API Key、模型名。官方默认地址是 https://api.openai.com/v1；如果用中商起航 AI 网关，地址是 https://ai.zhongshangqihang.com/v1。
| 配置项 | 官方默认 | 中商起航网关 |
|---|---|---|
| Base URL | https://api.openai.com/v1 |
https://ai.zhongshangqihang.com/v1 |
| 鉴权 | OpenAI API Key | 网关控制台创建的 Key |
| 协议 | Responses API | 提供 /v1/responses 入口，模型支持以站内文档为准 |
| 模型名 | 官方模型 ID | 以站内价格页为准 |
这里有一个 2026 年的关键变化：Codex CLI 的自定义 provider 目前只接受 wire_api = "responses"，旧的 wire_api = "chat" 已被移除。也就是说，网关必须能转发 Responses 协议；如果只提供 Chat Completions，就需要中间层做协议转换，或者改用其他客户端。中商起航 AI 网关提供 /v1/responses 入口，具体哪些模型支持 Responses，以站内文档和价格页为准。
三、安装 Codex CLI
按你的系统选一种方式：
# npm
npm install -g @openai/codex
# macOS Homebrew
brew install --cask codex
# 安装后确认版本
codex --version
安装完成后，先不要急着改配置。用官方账号登录跑通一次，可以确认工具本身正常：
- 在终端执行
codex。 - 按提示选择登录方式。
- 新建一个测试目录，让它读取一个文件。
- 确认能正常返回后再切换自定义 provider。
四、编写 config.toml
Codex CLI 的用户级配置在 ~/.codex/config.toml。项目目录下的 .codex/config.toml 不会覆盖 provider 定义，容易让人误以为配置没生效。
# ~/.codex/config.toml
model = "your-model-id"
model_provider = "zsqh"
[model_providers.zsqh]
name = "ZSQH AI Gateway"
base_url = "https://ai.zhongshangqihang.com/v1"
env_key = "ZSQH_API_KEY"
wire_api = "responses"
字段含义：
model：要调用的模型 ID，必须和网关价格页上的标识完全一致。model_provider：指向下面定义的 provider 名称，两边要一致。base_url：OpenAI 兼容根地址，通常以/v1结尾。env_key：存放 Key 的环境变量名，不要把 Key 直接写进配置文件。wire_api：当前版本填responses。
然后在 shell 里导出 Key：
export ZSQH_API_KEY="sk-你的密钥"
Windows PowerShell 用 $env:ZSQH_API_KEY="sk-你的密钥"。如果希望永久生效，把变量写进 shell 配置文件或系统环境变量，不要提交到代码仓库。
五、验证第一条请求
交互模式直接执行 codex，在项目目录里提一个只读问题，例如“解释这个目录的入口文件”。如果只想做一次非交互验证，可以用 codex exec（当前版本若提供该子命令，先跑 codex exec --help 确认）：
cd /path/to/your-project
codex exec "用三点说明这个项目的目录结构，不要修改文件"
排查请求走向时，加调试日志：
codex --log-level debug
重点看请求 URL 是否指向你的 Base URL、路径是否为 /responses、模型名是否原样发出。很多“配置不生效”其实是终端没有重新加载环境变量，或者改错了配置文件位置。
六、模型怎么选
Codex 的任务偏代码理解、补丁生成和命令执行，选模型时优先看三项：上下文长度、工具调用稳定性、长任务中的指令遵循。不要只看单价。
| 场景 | 选型建议 | 注意 |
|---|---|---|
| 日常改代码 | 通用对话或代码模型 | 确认支持流式输出 |
| 大型仓库阅读 | 长上下文模型 | 上下文越长，单次成本越高 |
| 多步骤任务 | 工具调用稳定的模型 | 先用小任务验证 |
| 批量脚本 | 成本较低的模型 | 失败重试要限额 |
模型 ID 以站内价格页为准。把网页上的展示名直接填进 model 是最常见的错误之一；展示名和 API 标识往往不是一回事。
七、常见报错与处理
| 现象 | 常见原因 | 处理 |
|---|---|---|
401 Unauthorized |
Key 未导出或填错 | 重开终端，确认 env_key 指向的变量有值 |
404 Not Found |
Base URL 多了或少了 /v1，或网关不支持 /responses |
核对地址与接口范围 |
wire_api = "chat" 报错 |
使用了旧配置 | 改为 responses，或升级 Codex |
model not found |
模型 ID 与价格页不一致 | 复制价格页上的准确标识 |
| 请求中断 | 网络或流式超时 | 检查代理、超时和重试设置 |
429 |
触发限流或额度不足 | 查看网关用量页，降低并发 |
如果网关只支持 Chat Completions，而当前 Codex 版本又只认 Responses，最稳妥的做法是加一层协议转换（例如 LiteLLM 之类的网关），而不是到处找旧版本。旧版本迟早会失去维护。
八、安全与成本清单
- Key 只放环境变量或密钥管理服务，不进 Git。
- 给 Codex 单独发一把 Key，便于限额和吊销。
- 在网关侧设置预算和并发上限，避免 Agent 循环烧额度。
- 大型仓库先排除构建产物、依赖目录和密钥文件。
- 定期看用量报表，按项目拆分成本。
- 不要在提示词里粘贴生产密钥、客户数据或未脱敏日志。
常见问题
Codex API 和 ChatGPT 订阅是一回事吗？
不是。ChatGPT 订阅面向网页和客户端产品；Codex CLI 可以走账号登录，也可以配置 API Key 按量计费。两者计费口径不同，团队采购时要分开算。
Codex CLI 能用 Chat Completions 接口吗？
当前版本的自定义 provider 只支持 Responses 协议，wire_api = "chat" 已被移除。只有 Chat Completions 的端点需要协议转换层。
为什么改了 config.toml 没有生效？
先确认改的是 ~/.codex/config.toml，不是项目内的配置文件；再确认 model_provider 与 [model_providers.xxx] 名称一致；最后重开终端，让环境变量生效。
模型名应该填展示名还是 API 标识？
填 API 标识。展示名只用于界面显示，填错通常报 model not found。准确写法以站内模型价格为准。
团队可以共用一把 Key 吗？
不建议。按人、按项目或按环境分别发 Key，出问题能定位，离职或泄露时也能单独吊销。
下一步
Codex 的接入难点不在安装，而在协议匹配：先确认网关是否支持 Responses，再配 Base URL、Key 和模型三处。需要统一入口和用量管理，可以注册中商起航 AI 网关，模型与接口范围以模型价格页为准。
相关阅读：
