Codex 配置 OpenAI 兼容 API：先验证再启动

更新于 2026-11-07 · anyrouter.cfd

简答：Codex 配置 OpenAI 兼容 API，核心是写入用户级 config.toml，指定自定义 model_provider、Responses API 地址和 env_key，再用 curl 验证接口。先确认四项：配置路径、Provider ID、最终 /responses 地址、真实模型 ID；使用第三方 API Key 时，不要先执行 codex login 进入 OpenAI 登录流程。

定义：OpenAI 兼容 API 是采用类似 OpenAI 请求格式的接口，但能否被 Codex 使用，仍取决于服务端是否提供兼容的 Responses API、认证方式和模型目录。

先看最小配置：四项确认后再启动 Codex

本文核验日期为 2026-11-07。Codex 的自定义 Provider 配置通常写在 $CODEX_HOME/config.toml；没有设置 CODEX_HOME 时，常见用户级路径是 macOS/Linux 的 ~/.codex/config.toml，Windows 通常对应用户目录下的 .codex\config.toml。OpenAI Codex 所引用的 Provider 定义源码显示，自定义 Provider 可配置 base_url、env_key 和 wire_api 等字段；源码版本会变化，使用前应结合本机 CLI 版本复核。Codex Provider 配置源码

通用最小模板如下。示例中的域名、变量名和模型 ID 都是占位符，不能直接当作任何服务商的真实配置：

model = "YOUR_MODEL_ID"
model_provider = "my-gateway"

[model_providers.my-gateway]
name = "My OpenAI Compatible API"
base_url = "https://example.com/v1"
env_key = "MY_API_KEY"
wire_api = "responses"

其中 env_key 填的是环境变量名称，不是密钥本身；wire_api 是否支持以及具体字段行为，应以本机 Codex 版本对应的官方配置说明为准。所引用的当前源码只接受 responses 作为该字段值，并明确提示 chat 配置不再支持，但主分支不是固定版本，因此不要把它视为所有历史版本的行为。源码中的 Wire API 与 Provider 字段

第一步：安装 Codex、检查版本并备份原配置

如果尚未安装或需要更新 Codex CLI，可以使用 npm 安装，然后检查当前版本：

• npm install -g @openai/codex@latest
• codex --version

OpenAI 的 Codex 示例采用了上述安装与版本检查方式。由于 CLI 字段和默认行为可能随版本变化，本文不指定未经核实的最低版本。OpenAI Codex 安装与版本检查示例

macOS 或 Linux 先备份已有配置：

• mkdir -p ~/.codex
• if [ -f ~/.codex/config.toml ]; then cp ~/.codex/config.toml ~/.codex/config.toml.bak; fi

Windows PowerShell 先确认 Codex 配置目录并备份：

• $codexHome = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $env:USERPROFILE ".codex" }
• New-Item -ItemType Directory -Force -Path $codexHome | Out-Null
• $config = Join-Path $codexHome "config.toml"
• if (Test-Path $config) { Copy-Item $config "$config.bak" -Force }

认证提醒：如果使用的是第三方兼容 API Key，不要先执行 codex login 进入 OpenAI 登录流程。应先通过自定义 Provider 的 env_key 提供密钥，并确认 model_provider 已指向自定义 Provider。若启动时仍出现登录提示，先检查是否仍在使用默认 Provider，或当前配置是否把 requires_openai_auth 设为了需要登录的模式。

第二步：设置 API Key，并创建 config.toml

macOS/Linux 临时设置：在当前终端执行以下命令，关闭终端后变量通常会失效：

• export MY_API_KEY="替换为你的真实Key"
• export CODEX_HOME="$HOME/.codex"

macOS/Linux 持久设置：根据使用的 Shell 追加到配置文件，再重新加载：

• printf '\nexport MY_API_KEY="替换为你的真实Key"\n' >> ~/.zshrc
• source ~/.zshrc

如果使用 Bash，把 ~/.zshrc 换成 ~/.bashrc。不要把真实密钥提交到 Git、写进公开截图、粘贴到问题反馈或打印到日志中。

Windows PowerShell 临时设置：

• $env:MY_API_KEY = "替换为你的真实Key"
• $env:CODEX_HOME = Join-Path $env:USERPROFILE ".codex"

Windows 持久设置：下面的命令会把变量写入当前用户环境，新的终端窗口才会读取到：

• [Environment]::SetEnvironmentVariable("MY_API_KEY", "替换为你的真实Key", "User")
• [Environment]::SetEnvironmentVariable("CODEX_HOME", (Join-Path $env:USERPROFILE ".codex"), "User")

设置持久变量后，请关闭并重新打开 PowerShell，再执行：

• echo $env:CODEX_HOME
• if ($env:MY_API_KEY) { "MY_API_KEY is set" } else { "MY_API_KEY is missing" }

然后创建或编辑配置文件。PowerShell 示例：

$config = Join-Path $env:CODEX_HOME "config.toml"
@'
model = "YOUR_MODEL_ID"
model_provider = "my-gateway"

[model_providers.my-gateway]
name = "My OpenAI Compatible API"
base_url = "https://example.com/v1"
env_key = "MY_API_KEY"
wire_api = "responses"
'@ | Set-Content -Path $config -Encoding utf8

macOS/Linux 可以用编辑器打开同一文件：

• mkdir -p "${CODEX_HOME:-$HOME/.codex}"
• ${EDITOR:-nano} "${CODEX_HOME:-$HOME/.codex}/config.toml"

base_url 是否需要 /v1 不能一概而论。它只是常见格式，不是所有 OpenAI 兼容网关的通用规则；应以服务商文档、模型列表接口和最终请求路径为准。不要把已经包含 /responses 的完整接口地址再填入 base_url，否则可能产生重复路径。

第三步：分别用 Unix Shell 和 PowerShell 验证 Responses API

不要直接启动 Codex 猜错在哪里。先把变量、模型和接口分开验证。下面的命令假设 base_url 为 https://example.com/v1，请替换为服务商明确提供的 API 根路径。

macOS/Linux：

export BASE_URL="https://example.com/v1"
export MY_MODEL_ID="替换为 /models 返回的真实ID"
curl --fail-with-body --silent --show-error "$BASE_URL/models" \
  -H "Authorization: Bearer $MY_API_KEY"

确认模型 ID 后，再测试 Responses：

curl --fail-with-body --silent --show-error "$BASE_URL/responses" \
  -H "Authorization: Bearer $MY_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"$MY_MODEL_ID\",\"input\":\"Reply with one short sentence.\"}"

Windows PowerShell：

$env:BASE_URL = "https://example.com/v1"
$env:MY_MODEL_ID = "替换为 /models 返回的真实ID"
$headers = @{ Authorization = "Bearer $env:MY_API_KEY" }
Invoke-RestMethod -Uri "$env:BASE_URL/models" -Headers $headers -Method Get

测试 Responses：

$body = @{ model = $env:MY_MODEL_ID; input = "Reply with one short sentence." } | ConvertTo-Json -Compress
$headers["Content-Type"] = "application/json"
Invoke-RestMethod -Uri "$env:BASE_URL/responses" -Headers $headers -Method Post -Body $body

成功时至少检查三点：HTTP 请求没有返回 4xx/5xx；响应 JSON 能被正常解析；响应中出现服务端返回的响应对象或可读取的输出内容。不同兼容服务的响应字段可能不同，不能只凭某一个字段判断全部服务都成功。若启用流式返回，还应确认事件流能够持续读取并正常结束；如果连接在结束事件前断开，先关闭流式或改用非流式最小请求判断基础连通性。

如果服务端返回非 2xx，保留状态码和错误体中的通用信息，但不要把 API Key 写入日志。若出现 TLS、DNS、连接超时或代理错误，说明请求可能尚未到达应用层，应先检查域名解析、证书、网络出口和防火墙，再继续排查模型或权限。

验证通过后启动 Codex：交互模式与一次性执行

只有 /models 和 /responses 都按照服务商实际接口验证通过后，再启动 Codex：

• 交互模式：codex
• 一次性执行：codex exec "用一句话说明当前仓库用途"

如果 Codex 仍然请求错误地址，优先检查配置是否被覆盖：

• model_provider 是否与 Provider 表名完全一致；
• CODEX_HOME 是否指向你实际编辑的目录；
• 是否在命令行使用了 -c 参数覆盖文件配置；
• 是否重新打开了 PowerShell 或 Shell，使持久环境变量生效；
• 模型 ID 是否来自当前服务商的实际返回，而不是旧教程或记忆。

如果启动时出现 OpenAI 登录提示，先不要重复登录。检查是否仍使用默认 openai Provider，以及自定义 Provider 是否设置了正确的 env_key。当前官方源码说明，requires_openai_auth = false 时会跳过登录界面并从 env_key 指向的环境变量读取密钥；但该字段是否适用于你安装的具体 CLI 版本，应以本机版本对应的配置参考核实。OpenAI Codex Provider 参数示例

以 AnyRouter 为例：文档地址不等于已实测可用

本站不是 AnyRouter 官方站点。下面只把它作为一个需要现场复核的配置示例，不能据此推断价格、额度、模型长期可用性或服务稳定性。

如果你要测试该示例，应先在独立 Provider 中使用文档声明的根路径，并通过模型接口复制当前返回的真实 ID：

model = "从当前 /models 返回值复制"
model_provider = "anyrouter-example"

[model_providers.anyrouter-example]
name = "AnyRouter example"
base_url = "https://anyrouter.cfd/api/v1"
env_key = "ANYROUTER_API_KEY"
wire_api = "responses"

然后分别验证 GET https://anyrouter.cfd/api/v1/models 和 POST https://anyrouter.cfd/api/v1/responses。本页没有对这些地址进行独立请求，因此“文档存在端点”和“你的账户当前可以调用”必须分开判断。AnyRouter Agents 文档

常见报错：按配置、鉴权、路径和协议分流

修改失败时，先恢复 config.toml.bak，确认 Codex 能恢复启动，再一次只改一个变量：先确认配置路径，再确认 Provider 名称，再确认 Base URL，最后确认模型和协议。这样可以避免把 401、404、模型错误和配置覆盖混在一起。

env_key 与 auth.json：当前可核验范围怎么选

对于自定义 Provider，本文优先使用 env_key，原因是所引用的 Codex Provider 定义明确把它描述为保存 API Key 的环境变量名称，并将直接配置 experimental_bearer_token 标为出于安全原因不鼓励的方式。OpenAI 的 API Key 指南也建议通过环境变量或密钥管理服务加载密钥，避免把密钥放进源代码、日志或客户端代码。OpenAI API Key 安全指南

至于把第三方兼容 API Key 直接写进 auth.json，本次核验到的官方资料没有确认它对所有 Codex CLI 版本、自定义 Provider 和认证后端都通用。因此本文不提供把第三方 Key 写入 auth.json 的确定性步骤，也不把它当成与 env_key 等价的方案。若你的具体 CLI 版本或服务商文档明确说明支持，应按对应版本文档核对文件路径、字段和存储权限。

实际使用中可按场景选择：临时本机测试使用当前终端环境变量；长期本机使用系统用户环境变量或密码管理器；自动化任务使用 CI/CD Secret。无论采用哪种方式，都应保留原配置备份，避免密钥进入 Git 仓库和公开日志。

常见问题

Codex 配置 OpenAI 兼容 API 时，Base URL 要不要加 /v1？

不能一概而论。/v1 只是常见路径格式，是否需要取决于服务商文档和实际接口。Base URL 通常填写 API 根路径，再由 Codex 请求其下的 /responses；不要把已经包含 /responses 的完整地址再次填入 base_url。

Windows 下如何创建 Codex 的 config.toml？

先在 PowerShell 设置 CODEX_HOME，再用 Set-Content 写入文件，或用记事本编辑 Join-Path $env:CODEX_HOME "config.toml"。写入后重新打开 PowerShell，并用 curl 或 Invoke-RestMethod 验证变量、/models 和 /responses。

env_key 和 auth.json 哪个更适合自定义 Provider？

当前核验到的官方 Provider 定义明确支持 env_key，并不鼓励把 Bearer Token 直接写入配置。对于第三方 Key 是否能通过 auth.json 在所有 Codex CLI 版本中复用，资料未确认，因此优先使用 env_key；auth.json 只能按具体版本文档核实。

为什么设置了 OPENAI_API_KEY，Codex 还是没有调用兼容 API？

Codex 的自定义 Provider 不一定读取 OPENAI_API_KEY。检查 config.toml 的 env_key 是否指向实际设置的变量，并确认 model_provider 与 Provider 表名完全一致；如果仍使用默认 Provider，兼容 API 的 Base URL 不会生效。

Codex 使用兼容 API 时为什么不要先执行 codex login？

codex login 可能把流程带入 OpenAI 的登录或凭据路径。使用第三方兼容 API Key 时，应先配置自定义 Provider 和 env_key；如果启动仍要求登录，再检查是否误用了默认 Provider或启用了 requires_openai_auth。

AnyRouter 的模型 ID 能直接照抄旧教程吗？

不建议。本次只核实到其公开文档中的端点说明，未独立验证你的账户、模型目录、额度或价格。应先请求当前模型接口，复制实际返回的模型 ID，再测试 Responses 请求。

相关阅读

• 遇到 401 时按 Key、权限和请求头排查
• 请求成功但流式输出中断时的排查方法
• 选择 OpenAI 兼容 API Router 前的核验清单
• 继续查看 Codex 的 Base URL、Key 与 Responses API 核对

参考资料

1. OpenAI Codex：Model Provider 配置源码
2. OpenAI Developers：Codex 安装与版本检查示例
3. OpenAI Developers：Codex Responses Provider 参数示例
4. OpenAI API：API Key 与密钥安全指南
5. AnyRouter Agents 文档：OpenAI 兼容接口说明