Codex 怎么配置 OpenAI 兼容 API Base URL？

更新于 2026-11-01 · standardcompute.cyou

简答：Codex 配置 OpenAI 兼容 API Base URL，通常有两种方式：仅修改内置 OpenAI provider 时使用 openai_base_url；需要单独指定模型、密钥环境变量或请求头时，在用户级 ~/.codex/config.toml 中定义自定义 model_providers。当前 Codex 配置参考将自定义 provider 的 wire_api 定义为 responses，因此只兼容 Chat Completions 的接口不能直接视为可用，必须先向服务商核实。

定义：OpenAI 兼容 API Base URL 是 Codex 发送模型请求时使用的接口根地址，具体是否包含 /v1、是否支持 Responses API、模型 ID 和认证头，都必须以接口提供方当前文档或控制台显示为准。

先看结论：两种 Base URL 配置方式怎么选

本文是第三方 AI API 接入指南，不是 Codex 或任何接口服务商的官网。Codex 当前官方配置文档把“修改内置 OpenAI provider”和“新增自定义 provider”分成两条路径，建议先按下表选择，不要同时堆叠多个配置。

官方文档明确说明，若只是把内置 OpenAI provider 指向代理、路由或数据驻留项目，可以直接设置 openai_base_url；如果需要独立的 provider，则使用 model_providers.<id> 并通过 model_provider 选择它。详情可查看Codex 高级配置文档和Codex 配置字段参考。

最短三步：先把 Codex 接口参数核对完整

1. 从接口提供方复制参数。至少确认 Base URL、Responses API 是否支持、API Key 环境变量名称、可用模型 ID，以及是否需要额外请求头。不要把服务商首页地址、控制台地址或带具体资源路径的完整 URL 直接当成 Base URL。
2. 把配置写入用户级文件。Codex 默认使用 CODEX_HOME 指向的目录保存状态；未设置时默认为 ~/.codex，常见配置文件是 ~/.codex/config.toml。provider 路由和认证相关配置应放在用户级文件，而不是项目级 .codex/config.toml。
3. 先做最小请求，再启动 Codex。用不泄露密钥的方式测试模型列表或服务商提供的健康检查端点；如果服务商没有公开模型列表端点，就直接用其文档中的最小 Responses 请求。只有状态码、响应体和模型字段都符合预期后，才运行 Codex 任务。

当前文档还说明，项目级配置只有在项目受信任时才加载，并且不能覆盖会改变凭据、provider 或 Base URL 的关键字段。因此，出现“配置写了但 Codex 没采用”时，第一步应检查文件层级，而不是马上更换模型。

方案一：只修改内置 OpenAI provider

如果你的目标只是把 Codex 的内置 OpenAI provider 指向一个 OpenAI 兼容路由，可以在用户级 config.toml 中使用以下结构。这里的地址是示例值，发送请求前必须替换并核实，不代表任何具体服务商的真实端点。

openai_base_url = "https://api.example.com/v1"

这种方式的优点是配置短，不需要新增 provider。官方文档特别提醒，不要通过 [model_providers.openai] 创建同名自定义 provider，因为 openai 是内置保留 ID，不能这样覆盖。

需要注意，/v1 不是所有服务商都相同。判断方法不是“看别人配置怎么写”，而是核对服务商文档列出的 API 根地址，再检查最终请求路径。例如文档若明确写出模型列表路径为 /v1/models，Base URL 通常应能与该路径拼接；如果服务商提供的是完整的 Responses 路径或网关专用路径，应以其文档为准，不能自行重复添加 /v1。

这种方式适合先验证“Codex 能否通过内置 provider 访问接口”。如果还需要单独设置 API Key 环境变量、请求头、重试策略或多个 provider，改用下一种方式更清晰。

方案二：使用自定义 model provider

自定义 provider 适合第三方网关、组织内部路由或需要多个接口配置的场景。官方示例使用 model、model_provider、base_url 和 env_key 组合。下面保留字段结构，但模型名、域名和环境变量名都是示例值，发送请求前必须核实。

model = "MODEL_ID_FROM_PROVIDER"
model_provider = "my_gateway"

[model_providers.my_gateway]
name = "My OpenAI-compatible gateway"
base_url = "https://api.example.com/v1"
env_key = "MY_GATEWAY_API_KEY"
wire_api = "responses"

配置后，在当前终端会话中设置对应环境变量。Linux 或 macOS 可以使用类似下面的写法；命令只读取环境变量，不要把真实密钥直接写进 shell 历史或文章、截图和仓库。

export MY_GATEWAY_API_KEY='REPLACE_WITH_YOUR_KEY'

PowerShell 可使用：

$env:MY_GATEWAY_API_KEY = "REPLACE_WITH_YOUR_KEY"

如果你使用了自定义环境变量，env_key 必须与当前进程实际存在的变量名完全一致。官方字段参考将 env_key 定义为“为 provider 提供 API Key 的环境变量”；它不是 API Key 本身，也不会自动替你创建变量。

当前配置参考把自定义 provider 的 wire_api 可选值列为 responses，且省略时默认也是 responses。因此，不应继续照搬旧的 wire_api = "chat" 作为通用方案。若你的接口只提供 Chat Completions，应先核实是否存在 Responses 兼容能力；在没有一手文档或成功最小请求前，本文不把它判定为 Codex 可用。

模型名、API Key 和 Base URL 如何逐项核验

模型列表接口的返回通常包含模型 id，该字段才是后续 API 请求应引用的模型标识。可参考模型列表 API 参考中的返回结构。对于兼容网关，模型列表可能被关闭、裁剪或改写，因此“没有列出模型”不一定等于模型不存在；此时应以服务商控制台和响应体为准。

用最小请求验证 Base URL，而不是直接运行复杂任务

如果服务商公开了模型列表端点，可以先使用下面的安全模板。这是示例命令，发送前核实 Base URL 和环境变量名；不要把真实 Key 替换进文章或提交到仓库。

curl "$BASE_URL/models" \
-H "Authorization: Bearer $API_KEY"

其中 BASE_URL 应该是服务商文档定义的 API 根地址，API_KEY 由当前终端环境提供。不要在诊断命令中使用 echo $API_KEY、set 或会打印全部环境变量的操作。

成功判定建议同时满足四项：

1. HTTP 状态码属于服务商文档定义的成功范围，通常先看是否为 2xx，但不能只凭状态码下结论。
2. 响应体是预期的 JSON 或接口文档定义的响应格式，而不是代理层的 HTML 错误页。
3. 返回数据中存在可用的模型标识，或最小 Responses 请求返回了可解析的响应对象。
4. 将同一个模型 ID 写入 Codex 后，最小任务能在客户端显示实际文本，而不是只显示连接成功。

如果服务商没有 /models，不要为了凑验证步骤而假设该端点存在。改用服务商文档中的最小 Responses 请求，并记录最终 URL、请求方法、状态码、响应体摘要和响应头中的 request ID；排错时只保留脱敏后的信息。

401、403、404、429 和超时：按证据排查

建议固定使用“凭据→最终 URL/路径→模型→权限或区域→最小请求→错误响应”的顺序。每次只改一个变量，并保存脱敏后的状态码、响应体和 request ID。这样才能区分是 Codex 配置问题、网关路由问题，还是服务商本身的兼容性限制。

常见问题 FAQ

Codex 的 Base URL 应该填到 /v1 还是域名根目录？

没有适用于所有服务商的固定答案。应以服务商文档给出的 API 根地址和完整请求路径为准，再用最小请求验证。若文档明确把模型列表写成 /v1/models，通常需要让 Base URL 与该路径正确拼接；如果文档已经给出完整的网关路径，就不要重复添加 /v1。

什么时候用 openai_base_url，什么时候用自定义 provider？

只需要把内置 OpenAI provider 指向另一个路由时，优先使用 openai_base_url。需要单独设置环境变量、请求头、多个接口或明确切换 provider 时，使用 model_provider 与 model_providers.<id>。两种方式不要为了“保险”同时配置。

为什么项目里的 .codex/config.toml 改了却没有生效？

当前官方规则明确限制项目级配置覆盖 provider 和认证相关字段，openai_base_url、model_provider、model_providers 都在被忽略的字段范围内。请将这些内容移动到用户级 ~/.codex/config.toml，并检查项目是否处于受信任状态。

OpenAI 兼容 API 只支持 Chat Completions，Codex 能不能直接用？

不能仅凭“OpenAI 兼容”判断可以。当前 Codex 配置参考中自定义 provider 的 wire_api 可选值为 responses，所以应先向服务商核实 Responses API、请求格式、流式事件和模型能力是否完整兼容。没有一手资料或最小请求证据时，应标记为未核实。

可以把 API Key 直接写进 config.toml 吗？

不建议。官方字段参考提供了 env_key，用于让 Codex 从环境变量读取 API Key；配置文件只保存变量名，不保存真实密钥。密钥还应避免出现在 Git 仓库、截图、日志和诊断输出中。

模型 ID 应该填什么？

填写接口提供方当前认可的模型 ID，而不是产品展示名、网页标题或个人猜测。优先从服务商模型列表、控制台或接口返回的 id 字段复制；如果接口没有模型列表，就以其文档和实际最小请求结果为准。

配置完成后的自查清单

• 已确认当前 Codex 版本对应的配置文档，并使用用户级 config.toml。
• 已区分 openai_base_url 与自定义 model_providers，没有使用保留 provider ID。
• 已从服务商一手资料确认 Base URL、是否包含 /v1、Responses API 和模型 ID。
• 已使用环境变量提供 API Key，没有把真实密钥写入配置、仓库或命令输出。
• 已通过最小请求检查状态码、响应体、模型字段或 Responses 响应对象。
• 出现错误时，已查看响应体、响应头或日志，而不是只根据 401、403、404、429 的数字猜原因。

截至 2026-11-01，本文只采用当前可核验的 Codex 配置文档字段；具体服务商的端点、模型、价格、限速、区域和权限仍需以其当前文档或控制台为准，本文不替任何具体服务商确认这些动态参数。

常见问题

Codex 的 Base URL 应该填到 /v1 还是域名根目录？

没有统一固定值，必须以服务商文档给出的 API 根地址和完整请求路径为准，再用最小请求验证，避免重复添加或遗漏 /v1。

什么时候用 openai_base_url，什么时候用自定义 provider？

只改内置 OpenAI provider 的地址时用 openai_base_url；需要自定义环境变量、请求头、多个路由或独立 provider 时，用 model_provider 与 model_providers。

为什么项目里的 .codex/config.toml 没有生效？

当前规则不允许项目级配置覆盖 openai_base_url、model_provider 和 model_providers 等关键字段，应把它们写入用户级 config.toml。

只支持 Chat Completions 的接口能直接接 Codex 吗？

不能直接推断可用。当前配置参考将自定义 provider 的 wire_api 定义为 responses，因此应先核实服务商是否提供 Responses API 兼容能力。

API Key 可以直接写入 config.toml 吗？

不建议。使用 env_key 指定环境变量名，让 Codex读取环境变量中的密钥，并避免密钥出现在仓库、截图和日志中。

相关阅读

• Codex 接中转接口的 Responses 核验与 401/404 排查
• API Key 安全管理和用量监控
• Cursor 配置 OpenAI API Key 与 Base URL 的排错方法
• OpenAI API Token 计算与计费概念

参考资料

1. Codex Configuration Reference：配置文件、provider 字段与 wire_api（learn.chatgpt.com）
2. developers.openai.com
3. platform.openai.com