Codex 配置 API Key：从登录到自定义接口

更新于 2026-10-23 · ccsub.cyou

简答：Codex 配置 API Key，最简单的是通过 CLI 执行 <code>printenv OPENAI_API_KEY | codex login --with-api-key</code>；如果接入自定义接口，则在用户级 <code>~/.codex/config.toml</code> 中填写 <code>model</code>、<code>model_provider</code>、<code>base_url</code>、<code>env_key</code> 和 <code>wire_api = "responses"</code>。桌面端和 IDE 扩展可在登录界面选择 API Key，但不应默认它们读取同一份自定义 provider 配置。

定义：Codex API Key 配置，是把 API 凭据安全地交给 Codex，并让客户端使用正确的模型、Base URL、认证方式和 Responses API 协议完成调用。

30 秒速查卡：先判断你属于哪种配置

如果你只是调用官方 API，先设置 OPENAI_API_KEY，再通过标准输入登录 Codex CLI；如果你接入自定义网关，则不要把 Key 直接写进配置文件，而是配置环境变量名。自定义 provider 至少要核对五个字段：model、model_provider、base_url、env_key 和 wire_api。

# 官方 API Key 登录：macOS、Linux、WSL
printenv OPENAI_API_KEY | codex login --with-api-key

# 自定义 provider 的五个核心字段
model = "YOUR_MODEL_ID"
model_provider = "custom"

[model_providers.custom]
name = "Custom Provider"
base_url = "https://YOUR_API_BASE_URL"
env_key = "MY_PROVIDER_API_KEY"
wire_api = "responses"

官方认证文档明确说明，Codex CLI 可使用 codex login 完成 ChatGPT 登录，也可使用 API Key 登录；桌面端和 IDE 扩展同样提供 API Key 登录入口。详见Codex Authentication 官方文档。

第一步：安装或确认 Codex CLI

已经安装 Codex 的读者可以先确认版本：

codex --version

macOS 和 Linux 可使用官方安装命令：

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Windows、npm 和 Homebrew 的安装入口也列在官方 CLI 页面中。由于安装方式可能随版本变化，Windows 用户应打开Codex CLI 官方指南，选择页面中的 Windows 安装选项，而不要照搬其他版本的旧命令。安装后重新打开终端，再运行 codex --version。

官方 CLI 快速开始流程是：进入项目目录，运行 codex，然后选择可用的登录方式。交互会话中，/status用于查看当前会话配置，/model用于查看或切换模型。具体命令可在Codex CLI 官方页面核对。

第二步：使用 OpenAI API Key 登录 CLI

API Key 登录与 ChatGPT 浏览器登录不是同一种凭据。官方文档说明，API Key 用量按 OpenAI Platform API 账户计费，不使用 ChatGPT 订阅中的相同额度；部分依赖 ChatGPT 工作区或云服务的功能也可能不可用。

macOS、Linux 和 WSL 建议只在当前终端会话中读取 Key，不把真实值写入命令历史：

read -s OPENAI_API_KEY
export OPENAI_API_KEY
printf '\n'

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

read -s会隐藏输入内容，export只对当前 Shell 会话生效。关闭终端后，如果仍需使用，应通过安全的密钥管理工具、CI Secret 或重新注入环境变量。

Windows PowerShell 不要直接使用普通的 Read-Host 输入真实 Key，因为普通输入会回显。可以使用安全字符串读取，再传给 Codex：

$secure = Read-Host "OPENAI_API_KEY" -AsSecureString
$ptr = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($secure)
try {
  $env:OPENAI_API_KEY = [Runtime.InteropServices.Marshal]::PtrToStringBSTR($ptr)
} finally {
  [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($ptr)
}

$env:OPENAI_API_KEY | codex login --with-api-key
codex login status

$env:只对当前 PowerShell 会话生效。需要长期配置时，可在 Windows 的“系统属性→环境变量”中设置用户变量；使用 setx时不要把真实 Key 直接写进可被记录的命令历史。

登录后用下面的命令查看当前认证方式：

codex login status

如果需要清除已保存的 CLI 登录凭据，可执行：

codex logout

官方文档还说明，Codex CLI 和 IDE 扩展会共享缓存的登录凭据；凭据可能保存在 ~/.codex/auth.json或操作系统凭据存储中，应像密码一样保护，不能提交到 Git。

第三步：配置自定义 OpenAI 兼容接口

自定义 provider 与 codex login status是两条不同的认证路径。使用 env_key时，Codex 会从指定环境变量读取 provider Key，不一定会改变 codex login status显示的旧 ChatGPT 或 API Key 登录状态。因此，验证自定义接口时应优先检查环境变量、配置文件和实际请求，而不是只看登录状态。

官方配置参考规定，用户级配置文件位于 ~/.codex/config.toml；provider 相关字段应放在用户级配置中，项目级 .codex/config.toml不能覆盖 model_provider 和 model_providers等机器级字段。可复制以下模板：

model = "YOUR_MODEL_ID"
model_provider = "custom"

[model_providers.custom]
name = "Custom Provider"
base_url = "https://YOUR_API_BASE_URL"
env_key = "MY_PROVIDER_API_KEY"
wire_api = "responses"

其中：

• model：服务商实际提供的模型 ID，不要凭名称猜测。
• model_provider：必须与配置段中的 custom完全一致。
• base_url：服务商给出的 API 基础地址。
• env_key：环境变量名，不是 Key 本身。
• wire_api：官方配置参考当前只接受 responses，省略时默认也是该值。

官方配置参考把 experimental_bearer_token标记为不推荐，优先使用 env_key；命令式 token 获取则使用 auth配置，不能同时与 env_key或直接 bearer token 混用。字段定义见Codex Configuration Reference 官方文档。

各系统路径与环境变量写法

官方文档给出的用户级配置路径是 ~/.codex/config.toml。在 macOS、Linux 和 WSL 中，它对应当前 Linux 用户的 Home 目录：

mkdir -p ~/.codex
nano ~/.codex/config.toml

Windows 原生 PowerShell 中，用户目录通常展开为：

$env:USERPROFILE\.codex\config.toml

可用 PowerShell 创建目录并打开文件：

New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex" | Out-Null
notepad "$env:USERPROFILE\.codex\config.toml"

这里的 ~是官方文档中的用户级路径写法，Windows 使用 %USERPROFILE%对应的用户目录。若你设置了 CODEX_HOME或使用了配置 profile，实际文件位置可能由该设置决定；可先检查当前环境：

# PowerShell
$env:CODEX_HOME

# Bash、zsh 或 WSL
printf '%s\n' "$CODEX_HOME"

WSL 与 Windows 原生终端使用不同的用户环境：在 WSL 中运行 Codex 时，~/.codex是 WSL 用户目录；在 Windows PowerShell 中运行时，使用 Windows 用户目录。两者不会因为文件名相同而自动共享配置。

自定义 provider 的环境变量示例：

# Bash、zsh、WSL
read -s MY_PROVIDER_API_KEY
export MY_PROVIDER_API_KEY
printf '\n'

# PowerShell
$secure = Read-Host "MY_PROVIDER_API_KEY" -AsSecureString
$ptr = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($secure)
try {
  $env:MY_PROVIDER_API_KEY = [Runtime.InteropServices.Marshal]::PtrToStringBSTR($ptr)
} finally {
  [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($ptr)
}

长期使用可通过 Windows 用户环境变量界面保存变量；保存后要重新打开终端。验证时只判断变量是否存在：

# Bash、zsh、WSL
test -n "$MY_PROVIDER_API_KEY" && echo set || echo missing

# PowerShell
if ($env:MY_PROVIDER_API_KEY) { "set" } else { "missing" }

CLI、桌面端和 IDE 扩展怎么选

官方认证页面明确列出桌面端、CLI 和 IDE 扩展的 API Key 登录入口；如果你的目标是第三方兼容接口，本文建议先用 CLI 完成最小验证，再决定是否在桌面端或 IDE 中继续使用。入口和界面可能随版本调整，可参考官方认证说明。

Base URL、模型名与 Responses API 排错

自定义接口最容易出错的不是 Key 本身，而是 Base URL、模型 ID 和协议不匹配。Codex 的自定义 provider 配置要求 wire_api为 responses；一个只声明支持旧式 Chat Completions 的接口，不能据此推断已经兼容 Codex。

OpenAI API 官方错误文档也建议针对 401 检查正确的 API Key 和组织信息，针对 429 遵循 Retry-After并使用带抖动的指数退避。自定义 provider 的具体限制仍以接口服务商的兼容性文档为准，可参考OpenAI API 错误码官方文档。

配置完成后的最小验证清单

1. 运行 codex --version，确认当前使用的 CLI 版本。
2. 确认 ~/.codex/config.toml或 Windows 用户目录下的配置文件确实存在。
3. 检查 model_provider与 [model_providers.对应ID]完全一致。
4. 只检查环境变量是否存在，不打印 Key 内容。
5. 确认 base_url是否已经包含服务商要求的路径，避免重复添加 /v1。
6. 确认模型 ID来自服务商的实际模型列表。
7. 用短提示词启动 codex，例如“只用一句话说明当前目录是什么项目”。
8. 进入会话后运行 /status，确认当前模型和会话配置。
9. 如果自定义 provider 失败，保存 HTTP 状态码、错误体、模型名和请求 ID，但不要保存完整 Key。

如果 CLI 的官方 API Key 登录成功，但自定义 provider 仍失败，说明两条认证链路不能互相证明可用：官方登录只验证官方 API 凭据，自定义 provider 还必须单独验证 Base URL、模型和 Responses API 兼容性。

Key 安全与凭据清理

API Key、auth.json和包含 token 的日志都应按密码处理。不要把真实 Key 写入 Git、README、截图、工单、聊天记录或项目配置；项目中最多提交不含秘密的 config.example.toml。

• 将 .env和本地凭据文件加入 .gitignore。
• 验证时只输出变量是否存在，不使用 echo $KEY或 PowerShell 直接打印 Key。
• 发现泄露后，立即到对应控制台撤销并重新创建，不能只删除本地文件。
• 如果使用 auth.json保存登录态，不要提交或转发该文件。
• 自定义 provider 优先使用 env_key，不要把真实 token 写入 experimental_bearer_token。

截至2026年10月23日，官方认证文档仍将 API Key 登录、CLI 登录缓存和自定义 provider 配置分开说明；不同 Codex 版本可能调整界面或默认存储方式，实际使用时应以当前官方文档为准。

常见问题

Codex 配置 API Key 后为什么还提示登录？

先运行 <code>codex login status</code>确认当前登录态。如果你使用的是官方 API Key 登录，应重新执行 <code>printenv OPENAI_API_KEY | codex login --with-api-key</code>；如果你使用的是自定义 provider，则检查 <code>env_key</code>与环境变量是否一致。自定义 provider 不一定会改变登录状态命令显示的旧凭据。

Codex 的 API Key 应该写进 config.toml 吗？

不建议。config.toml 中应写 <code>env_key = "环境变量名"</code>，真实 Key 放在环境变量或 Secret 管理工具中。官方配置参考将 <code>experimental_bearer_token</code>标为不推荐，优先使用 <code>env_key</code>。

Windows 配置 Codex API Key 后，重开终端就失效怎么办？

PowerShell 中的 <code>$env:变量名</code>只对当前会话生效。临时测试时重新设置变量；长期使用可在 Windows 用户环境变量中配置，保存后重新打开终端，再用变量是否为空来验证，不要打印 Key。

Codex 返回 404，是不是 Base URL 一定写错了？

不一定。404 也可能来自模型 ID 错误、provider ID 不一致或路径重复。先核对服务商给出的完整 Base URL，再确认是否重复添加 <code>/v1</code>，随后逐字检查 <code>model</code>、<code>model_provider</code>和配置段名称。

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

不能直接推断。官方自定义 provider 配置的 <code>wire_api</code>当前只支持 <code>responses</code>，因此服务商需要明确说明支持 Codex 所需的 Responses API 行为。仅写着“OpenAI 兼容”或“支持 Chat Completions”不足以证明兼容。

Codex CLI、桌面端和 IDE 扩展会共用 config.toml 吗？

不能一概而论。CLI 明确使用用户级 <code>~/.codex/config.toml</code>；桌面端和 IDE 扩展提供各自的登录界面。官方说明 CLI 与 IDE 扩展共享登录缓存，但这不等于所有自定义 provider 配置都自动共享，应按当前版本分别核对。

相关阅读

• 查看 AI API 接入与模型调用指南

参考资料

1. Codex Authentication 官方文档
2. Codex Configuration Reference 官方文档
3. OpenAI API 错误码官方文档
4. OpenAI API Reference 官方总览