Codex CLI 配置自定义 API：Base URL、Provider 与鉴权步骤
简答：Codex CLI 配置自定义 API，通常修改用户级 config.toml：简单场景设置 openai_base_url，复杂场景定义 model_providers。API Key 放环境变量，Provider 需确认支持 Responses API。
定义：Codex CLI 自定义 API，是通过 config.toml 指定模型、Provider、Base URL、接口协议和鉴权变量，让 Codex 将请求发送到兼容 Responses API 的自定义网关。
先看结论：选择哪种配置方式
本站是第三方 AI API 接入指南站，不代表任何 Codex 或接口服务的官方身份。配置前先确认自定义接口是否支持 OpenAI Responses API；Codex CLI 的推理请求通过 Responses API 执行，自定义端点需要实现相应接口和流式事件，不能仅凭“支持 OpenAI 兼容”就判断一定可用。可先阅读 OpenAI 对 Codex agent loop 与 Responses API 的说明。
| 场景 | 推荐写法 | 适用条件 |
|---|---|---|
| 只想把内置 OpenAI Provider 指向自定义网关 | openai_base_url | 网关使用内置 Provider 的认证方式和请求格式 |
| 需要自定义 Provider、模型或请求头 | model_providers.<id> | 需要指定 wire_api、env_key 或自定义 Header |
| 接口只兼容 Chat Completions | 暂不直接套用本文配置 | Codex 需要先确认该接口是否提供 Responses API 兼容层 |
最小判断标准是：服务方能提供明确的 Base URL、模型标识、认证方式，并确认请求路径和响应流符合 Responses API。没有这些资料时，本文中的地址和模型只能使用占位符，不能直接替换成未经核实的服务信息。
第一步：安装或确认 Codex CLI
如果尚未安装 Codex CLI，可按照官方示例使用 npm 安装；已经安装的用户先确认当前版本，避免把新配置字段写入过旧版本。官方示例使用的命令是：
npm install -g @openai/codex@latestcodex --version
安装方式和版本行为可能随官方发布变化，执行前应以 OpenAI Codex CLI 官方示例为准。本文不固定某个版本号，也不把某个模型名称当作所有账户都可用的默认值。
第二步：确认配置文件位置并先备份
Codex 默认把用户配置放在 CODEX_HOME 下；未设置该变量时，macOS 和 Linux 通常使用 ~/.codex/config.toml。Windows 应使用 %USERPROFILE%\.codex\config.toml，WSL 按 Linux 路径处理，除非你显式设置了其他 CODEX_HOME。这些路径和作用域以 Codex 网关配置文档及 Codex 配置参考为准。
修改前先创建目录并备份已有配置，不要整体覆盖文件。macOS、Linux 或 WSL 可执行：
mkdir -p ~/.codextest -f ~/.codex/config.toml && cp ~/.codex/config.toml ~/.codex/config.toml.bak
Windows PowerShell 可执行：
New-Item -ItemType Directory -Force "$HOME\.codex" | Out-Nullif (Test-Path "$HOME\.codex\config.toml") { Copy-Item "$HOME\.codex\config.toml" "$HOME\.codex\config.toml.bak" -Force }
如果已有配置，建议用编辑器合并字段，不要删除原有的模型、沙箱、审批或其他个人设置。
第三步：简单方案——只设置 openai_base_url
如果自定义网关只是替换请求地址，且仍使用内置 OpenAI Provider 的认证方式，可以在用户级 config.toml 增加：
openai_base_url = "https://api.example.com/v1"
这里的域名只是占位符，实际地址必须由接口提供方确认。官方高级配置文档明确说明，openai_base_url用于修改内置 openai Provider 的 Base URL，不需要再创建一个名为 openai 的自定义 Provider。详见 Codex 高级配置文档。
该方案适合先做最小验证，但它不能表达每个网关都不同的模型目录、请求头或认证逻辑。如果接口要求自定义 Header，直接只改 Base URL 可能不够，应改用下一种方案。
第四步：完整方案——定义自定义 Provider
需要自定义模型、认证变量或接口协议时，在用户级 config.toml 中配置 Provider。下面是可替换的模板，模型、域名和环境变量名均为占位符：
model = "<MODEL_ID>"model_provider = "custom-gateway"[model_providers.custom-gateway]name = "Custom Gateway"base_url = "https://api.example.com/v1"wire_api = "responses"env_key = "CUSTOM_GATEWAY_API_KEY"
字段含义如下：
| 字段 | 作用 | 注意事项 |
|---|---|---|
model | 本次调用使用的模型标识 | 必须使用网关提供且当前 Codex 能识别的模型名 |
model_provider | 选择下方定义的 Provider ID | 必须与 model_providers.<id> 中的 ID 完全一致 |
base_url | 请求发送到的 API 基础地址 | 不要擅自重复拼接 /v1 或其他路径 |
wire_api | 指定接口协议 | 本文场景使用 responses |
env_key | 指定从哪个环境变量读取密钥 | 密钥值不写进 TOML 或代码仓库 |
官方网关示例也要求把 model、model_provider 等顶层字段放在第一个 TOML 表之前；如果把它们放进某个表之后，解析结果可能不符合预期。可参考 官方网关 Provider 示例。
第五步：设置 API Key，但不要写入 config.toml
env_key只保存环境变量名称，真正的密钥由启动 Codex 的进程提供。macOS、Linux 或 WSL 当前终端可使用：
export CUSTOM_GATEWAY_API_KEY="<YOUR_API_KEY>"test -n "$CUSTOM_GATEWAY_API_KEY" && echo "set" || echo "empty"
上面的自检只显示是否为空，不输出密钥片段。若要长期使用，应把变量写入受控的 Shell 配置或使用系统密钥管理工具；不要把真实密钥提交到 Git、项目目录或截图中。
如果网关不是 Bearer 认证，而是要求类似 X-API-Key 的请求头，可将 env_key替换为：
env_http_headers = { "X-API-Key" = "CUSTOM_GATEWAY_API_KEY" }
Header 名称必须以接口方文档为准。官方文档明确区分了 env_key 与 env_http_headers 两种方式，并提醒桌面应用不一定继承终端中设置的环境变量。
第六步：启动、验证与定位常见问题
保存配置后重新启动 Codex。若使用桌面应用或编辑器扩展，修改配置或环境变量后应重启对应应用，使新进程重新读取配置。
- 确认配置文件被读取：检查文件路径是否属于当前
CODEX_HOME，并确认 TOML 括号、引号和字段层级正确。 - 确认 Provider：在 Codex 会话中使用状态查看功能，确认当前模型和 Provider 与配置一致；不要只根据配置文件内容判断已经生效。
- 确认认证：只检查环境变量是否为空，不打印密钥；如果返回 401 或 403，先核对变量名、请求头方式和密钥权限。
- 确认地址：如果返回 404，检查 Base URL 是否已经包含版本路径，避免客户端自动拼接后出现重复路径。
- 确认模型：如果提示模型不存在，核对网关提供的模型名、Codex 当前版本以及是否需要模型目录配置。
- 确认协议：如果请求能建立但流式响应中断，优先确认网关是否完整支持 Responses API 的请求体和事件格式，而不是只支持 Chat Completions。
Codex 使用 Responses API 的请求流程和流式事件说明，可查阅 OpenAI Codex agent loop 原理说明。排查时不建议直接分享包含请求体、Header 或密钥的调试日志。
项目级配置为什么没有生效
Provider、认证和 Base URL 属于机器或用户相关设置，不应放在项目仓库的 .codex/config.toml 中作为团队共享配置。官方配置参考明确列出，项目级配置不能覆盖包括 openai_base_url、model_provider、model_providers 和认证相关设置在内的若干键；这些设置应放在用户级配置中。项目级文件还需要在受信任项目中才会加载。
因此，推荐的分工是：用户级 ~/.codex/config.toml 保存 Provider、Base URL 和认证映射；项目级 .codex/config.toml只保存适合随项目共享、且不涉及本机凭据和请求路由的配置。具体限制以 配置参考为准。
临时测试与永久配置的区别
需要临时试验时，可以使用 -c 或 --config覆盖单次运行的配置，而不立即改动永久文件。例如可以临时指定模型或 Provider：
codex -c 'model_provider="custom-gateway"' -c 'model="<MODEL_ID>"'
复杂的 Provider 表通常更适合写入用户级 config.toml，并通过备份、编辑、重启和状态检查确认结果。临时参数适合验证单个字段，永久配置适合重复使用；两者不要混在一起排查，否则容易误判到底是哪一层配置生效。
配置前的自查清单
- 是否已经执行
codex --version确认版本。 - 是否确认当前使用的
CODEX_HOME和配置文件路径。 - 是否先备份了原有
config.toml。 - 是否使用了占位符替换后的真实 Base URL，而不是示例域名。
- 是否确认接口支持 Responses API，而不只是 Chat Completions。
- 是否把真实 API Key 放在环境变量或密钥管理工具中。
model_provider是否与 Provider ID 完全一致。wire_api是否写为接口方确认的协议。- 是否避免在项目级配置中放置 Provider、Base URL 或认证字段。
- 是否通过状态信息和一次最小请求验证，而不是只看文件是否保存成功。
结语：先用最小配置确认，再扩展 Provider
Codex CLI 配置自定义 API 的稳妥顺序是：确认版本和配置路径，备份文件，先尝试 openai_base_url，需要自定义认证或请求协议时再定义 Provider，最后用状态信息和最小请求验证。对于具体接口的 Base URL、模型 ID、密钥格式和可用功能，本文不替读者猜测，必须以接口提供方的公开文档为准。
常见问题
Codex CLI 配置自定义 API 必须使用 model_providers 吗？
不一定。如果只是把内置 OpenAI Provider 指向另一个兼容地址，可以先使用 openai_base_url；只有需要自定义 Provider、模型、请求头或认证方式时，才使用 model_providers。
Codex CLI 能直接连接只支持 Chat Completions 的接口吗？
不能直接假设可以。Codex CLI 的推理流程使用 Responses API；如果接口只提供 Chat Completions，除非服务方提供兼容层或明确支持 Codex 所需请求与流式事件，否则不应套用本文配置。
API Key 应该写在 config.toml 里吗？
不建议。config.toml 中只写 env_key 指向环境变量名称，真实密钥通过启动 Codex 的进程注入。这样可以减少密钥进入配置文件、代码仓库和分享截图的风险。
为什么我修改了项目里的 .codex/config.toml 却没有生效？
Provider、Base URL 和认证相关字段属于受限配置，项目级配置不能覆盖其中一些键；应将它们放在用户级 config.toml，并确认项目处于受信任状态。
Base URL 后面应该写 /v1 吗？
不能一概而论。应按照接口方提供的完整基础地址配置，并确认 Codex 或网关是否会继续拼接请求路径。若出现 404，优先检查是否重复添加了版本路径或接口路径。
桌面应用读取不到终端里设置的 API Key 怎么办？
桌面应用可能不会继承当前终端的环境变量。重启应用前，确认变量已通过该应用进程可读取的方式提供；同时只检查变量是否为空，不要打印密钥内容。
参考资料
- Advanced Configuration | ChatGPT Learn（learn.chatgpt.com）
- Unrolling the Codex agent loop | OpenAI
- Using Goals in Codex | OpenAI Developers