Codex 怎么配置 OpenAI API Key 和 Base URL

更新于 2026-10-31 · aigocode.cyou

简答：可以。只接官方 OpenAI API 时，Codex CLI 可通过 <code>codex login --with-api-key</code> 使用 API Key；要连接 OpenAI 兼容接口，则需要在用户级 <code>~/.codex/config.toml</code> 中配置模型、provider、Base URL 和认证环境变量。本文以 Codex CLI 配置为主，并补充桌面端与 IDE 扩展的 API Key 入口。

定义：Codex 的 API Key 配置负责身份认证，Base URL 负责指定请求地址，模型 ID 和 Responses 协议则决定目标接口能否真正处理请求。

先做二选一：官方 OpenAI API，还是兼容接口

先不要同时修改 API Key、Base URL、模型和协议。第一步是确定你要使用哪种连接方式：只调用官方 OpenAI API，优先走 Codex 自带的 API Key 登录；需要连接企业网关或其他 OpenAI 兼容接口时，再配置自定义 provider。

截至 2026-10-31，官方认证文档明确列出了 ChatGPT 桌面端、Codex CLI 和 IDE 扩展的 API Key 入口：桌面端选择“其他方式登录”，CLI 通过标准输入执行登录，IDE 扩展选择“使用 API Key”。部分依赖 ChatGPT 工作区或云服务的功能可能受限，不能把 API Key 登录等同于 ChatGPT 账户登录。可查看 Codex Authentication 官方文档。

官方 API：用 API Key 登录 Codex

如果目标是官方 OpenAI API，通常不需要自己填写兼容网关的 Base URL。先在 OpenAI Platform 创建 API Key，再通过标准输入交给 Codex CLI：

printenv OPENAI_API_KEY | codex login --with-api-key

登录后检查认证状态：

codex login status

如果终端里还没有环境变量，可以在当前 macOS 或 Linux 会话中临时设置：

export OPENAI_API_KEY="你的_API_Key"

Windows PowerShell 可以设置当前会话变量：

$env:OPENAI_API_KEY="你的_API_Key"

Windows CMD 可以使用：

set OPENAI_API_KEY=你的_API_Key

OpenAI API 快速开始文档给出了 macOS/Linux 的 export 和 Windows 的 setx 示例。若使用 setx，它会把变量写入用户环境变量，已经打开的终端不会自动更新，因此需要重新打开终端；从安全角度看，临时会话变量或 Secret 管理通常更适合短期测试。参考 OpenAI API Developer quickstart。

API Key 登录的计费与 ChatGPT 订阅权益不是同一套规则。官方认证文档说明，API Key 使用量通过 OpenAI Platform 账户按标准 API 费率计费，并且部分依赖 ChatGPT 工作区或云服务的功能不可用或受限。需要确认当前费率时，应以官方 认证说明及其 API pricing 页面 为准。

兼容接口：在用户级 config.toml 配置 Base URL

如果目标是兼容网关，不要把真实密钥写进 TOML。推荐让 env_key 指向环境变量，再由 Codex 读取密钥。用户级配置文件位于：

~/.codex/config.toml

Windows 用户级路径为：

%USERPROFILE%\.codex\config.toml

官方配置参考说明，项目级 .codex/config.toml 只有在项目受信任时才会加载，而且项目级配置不能覆盖 model_provider 和 model_providers 等 provider 配置。因此，Base URL、provider 和认证字段应优先放在用户级配置中，不要把它们放进项目仓库里的配置文件。详见 Codex Configuration Reference。

下面是一个需要自行替换占位符的最小示例：

model = "your-model-id"

model_provider = "my_gateway"

[model_providers.my_gateway]

name = "My OpenAI Compatible Gateway"

base_url = "https://gateway.example.com/v1"

env_key = "OPENAI_API_KEY"

wire_api = "responses"

这些字段的含义是：model 是服务端实际接受的模型 ID；model_provider 必须与 provider 表名一致；base_url 是请求根地址；env_key 指定从哪个环境变量读取 API Key；wire_api 表示 provider 使用 Responses 协议。官方网关示例使用了 base_url 和 wire_api = "responses"，配置参考还明确说明当前 wire_api 支持的值为 responses，但具体字段仍应以当前 Codex 版本文档为准。可对照 Connect to a gateway 和 Configuration Reference。

注意 TOML 层级：model 和 model_provider 应放在第一个表头之前；如果误放到 [model_providers.my_gateway] 之后，它们就会被解析为 provider 内的字段，Codex 可能不会按预期读取。

Base URL、模型和协议怎么核对

“OpenAI 兼容”不等于所有接口都能直接被 Codex 使用。配置前至少核对下面五项：

官方 API 的 Responses 请求路径包含 /v1/responses，认证使用 Bearer 凭据；但兼容接口是否需要 /v1、是否支持 Responses，以及模型 ID 如何命名，都不能仅凭经验推断。API 认证和 Responses 入口可参考 OpenAI API Reference Overview。

配置修改后，完全退出并重新启动 Codex CLI、桌面端或 IDE 扩展。官方网关文档还提醒，终端中设置的环境变量不一定会被桌面应用继承；如果桌面端仍提示没有 Key，应在桌面应用能够读取的环境中设置变量，或使用其 API Key 登录入口。

CLI、桌面端和 IDE 扩展分别怎么处理

Codex CLI

CLI 直接使用 codex login --with-api-key 完成 API Key 登录。认证状态用 codex login status 检查；如果要清理已保存的登录状态，可执行 codex logout，然后重新登录。这里的状态命令只能证明认证方式，不代表自定义 Base URL、模型和 Responses 协议已经可用，接口调用仍需单独验证。

桌面端

退出登录后选择“其他方式登录”，输入 API Key 并继续。若连接自定义网关，仍需按当前 Codex 配置文档设置 provider；Windows 应用的 provider 设置放在 %USERPROFILE%\.codex\config.toml，修改后重启应用。官方网关页面对 Windows 应用的路径和重启要求有明确说明。

IDE 扩展

退出登录后选择“使用 API Key”，输入密钥并确认。官方认证文档明确列出了 IDE 扩展的这一入口。CLI 和 IDE 扩展会复用本地缓存的登录信息；官方文档说明，登录详情会被缓存，CLI 与扩展共享缓存，退出其中一处后，另一处下次启动也可能需要重新登录。本文不把这种登录缓存共享扩大解释为所有配置项都共享，provider 配置仍应以当前配置参考和实际启动环境为准。

认证成功但请求失败：按错误码分流

1. 401：先检查 API Key 是否完整、环境变量名称是否正确，以及 Codex 是否还在使用旧的登录缓存。CLI 可运行 codex login status；必要时执行 codex logout 后重新登录。自定义 provider 则重点检查 env_key 和启动 Codex 的进程环境。
2. 403：先核对账户、项目、模型或网关权限。403 只能说明请求被拒绝，不能单独证明 Base URL 写错；应保留脱敏后的错误正文和请求 ID，再向对应服务方核验权限。
3. 404：分别检查最终 Base URL 是否多了或少了 /v1，以及模型 ID 是否为精确值。一次只修改一个变量，避免把路径错误和模型错误混在一起。
4. 400 或协议错误：确认目标接口是否支持 Responses API。当前配置参考将 wire_api 的支持值限定为 responses；如果服务只提供 Chat Completions，而没有明确的 Responses 兼容说明，应标记为“未核实”，不要直接判断可用。
5. 429：查看目标服务的速率限制、并发限制和账户额度。降低请求频率只能用于验证是否存在限流，不能据此推断所有服务的具体限制。
6. 超时或连接失败：检查域名解析、TLS、代理和 Base URL；不要为了绕过连接问题关闭 TLS 校验。若是企业网络或自定义证书环境，按照管理员提供的网络和证书要求排查。
7. 配置不生效：确认编辑的是用户级 config.toml，没有被项目级限制、管理策略或其他启动参数覆盖，并彻底重启 Codex。尤其不要把 provider 字段放在项目级配置中后，仍期待它覆盖用户级 provider。

排错日志只保留脱敏后的请求地址、状态码、错误类型和请求 ID。不要粘贴 API Key、auth.json 或完整 Authorization 请求头。

API Key 和 auth.json 的安全边界

OpenAI API 文档建议把 API Key 放在环境变量或密钥管理服务中，不要写入浏览器、客户端代码、公开仓库、文章、截图或普通日志。官方 API Reference 也明确要求将 API Key 视为秘密凭据。

Codex 的登录缓存可能使用操作系统凭据存储，也可能使用文件存储。配置参考说明，文件存储模式会使用 CODEX_HOME/auth.json；认证文档同时说明，CLI、桌面端和 IDE 扩展的登录信息会被缓存并复用。因此，auth.json 应按密码文件保护，不能提交 Git 或发送给他人。不要直接在 config.toml 中写真实 bearer token；对于自定义 provider，优先使用 env_key，如需自定义请求头则使用官方配置参考中定义的 env_http_headers。

如果怀疑密钥已经泄露，应立即在对应平台撤销并重新生成，再检查仓库历史、终端记录和日志。本文不评价任何具体兼容服务的价格、隐私、限速或稳定性；使用前应自行核对服务方当前文档、合同和数据处理规则。

常见问题

Codex 一定要配置 Base URL 吗？

不一定。只使用官方 OpenAI API 时，先通过 Codex 的 API Key 登录流程即可；只有连接兼容网关、企业网关或其他自定义 provider 时，才需要配置 Base URL。

Codex 的 API Key 应该放在哪里？

CLI 可通过标准输入执行 <code>codex login --with-api-key</code>；兼容 provider 推荐使用 <code>env_key</code> 读取环境变量。不要把真实密钥写入公开仓库、代码、截图、TOML 或普通日志。

Base URL 要不要加 /v1？

没有统一答案。官方 Responses 地址包含 <code>/v1/responses</code>，兼容接口是否需要 <code>/v1</code> 必须以目标服务给出的完整请求地址为准。

为什么设置了 OPENAI_API_KEY 仍然提示未登录？

环境变量存在不等于 Codex 已完成登录。CLI 需要执行 <code>printenv OPENAI_API_KEY | codex login --with-api-key</code>，再运行 <code>codex login status</code>；如果已有旧登录状态，可先执行 <code>codex logout</code>。

Codex 报 404，是模型错还是 Base URL 错？

两者都有可能。先核对最终 Base URL 的协议、路径和 <code>/v1</code>，再核对模型 ID 是否为接口实际接受的精确值。一次只修改一个变量，并保留脱敏后的错误响应。

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

不能直接下结论。当前 Codex provider 配置使用 Responses 协议；如果目标服务没有明确说明支持 Responses，兼容性应标记为未核实，不要仅凭“OpenAI 兼容”判断可用。

项目级 .codex/config.toml 能配置 Base URL 吗？

不建议这样做。官方配置参考说明，项目级配置只有在项目受信任时加载，而且不能覆盖 <code>model_provider</code> 和 <code>model_providers</code> 等字段。provider、Base URL 和认证配置应放在用户级 <code>config.toml</code>。

相关阅读

• 继续了解 OpenAI 兼容 API 的 Base URL、模型 ID 与错误排查
• 查看 Dify 接入兼容 API 时的配置与验证方法
• 如果还要配置 IDE 工具，可参考 API Key 接入步骤
• 浏览更多 AI API 接入与错误排查文章

参考资料

1. Authentication｜ChatGPT Learn（learn.chatgpt.com）
2. Connect to a gateway｜ChatGPT Learn（learn.chatgpt.com）
3. Configuration Reference｜ChatGPT Learn（learn.chatgpt.com）
4. Developer quickstart｜OpenAI API
5. API Overview｜OpenAI API Reference