Crazyrouter

Codex CLI 配置 OpenAI API Key：安装、登录、验证与排错

更新于 2026-10-30 · crazyrouter.cyou

简答：配置 Codex CLI 的 OpenAI API Key，核心是先安装并确认 <code>codex</code> 可用，再把环境变量中的密钥通过标准输入交给 <code>codex login --with-api-key</code>，最后用 <code>codex login status</code> 验证。API Key 登录按 OpenAI API 标准计费，不等同于 ChatGPT 订阅额度；如果只是本地交互使用，也可以直接运行 <code>codex login</code> 走 ChatGPT 登录。

定义：Codex CLI 的 API Key 配置，是把 OpenAI Platform 的密钥安全地交给 Codex CLI 保存并用于本地编程代理调用，而不是把密钥直接写进项目代码。

先看速查卡：安装、登录、验证三步完成

以下流程针对 OpenAI 官方 API Key。命令中的变量名和路径可以直接参考，但不要把示例中的占位内容当成真实密钥使用。OpenAI 官方文档明确支持通过标准输入执行 codex login --with-api-key，并可用 codex login status 查看当前认证方式。官方认证文档 developers.openai.com

步骤macOS/LinuxWindows PowerShell成功判定
安装npm install -g @openai/codexnpm install -g @openai/codexcodex --version 能输出版本
登录printenv OPENAI_API_KEY | codex login --with-api-key$env:OPENAI_API_KEY | codex login --with-api-key命令正常退出，没有认证错误
验证codex login status显示当前认证方式并以成功状态退出

如果你还没有安装 Codex CLI，也可以先运行 codex，再选择 ChatGPT 登录；但本文重点是 API Key 登录路径。

第一步：安装 Codex CLI 并检查版本

官方仓库列出了 npm 和 Homebrew 等安装方式。npm 安装适用于已经配置 Node.js 的环境：Codex CLI 官方仓库 github.com

  1. macOS、Linux 或 Windows PowerShell 中执行：

    npm install -g @openai/codex

  2. 安装完成后检查命令是否进入 PATH：

    codex --version

  3. 如果提示找不到命令，先确认 npm 的全局 bin 目录已加入 PATH，再重新打开终端执行检查。

macOS 用户也可以按官方仓库说明使用 Homebrew：brew install --cask codex。官方仓库同时提供安装脚本，但通过远程脚本管道执行前，应先打开官方页面核对域名、查看脚本来源，并优先选择你能审查的安装方式。

第二步：按系统注入 API Key 并完成登录

先在 OpenAI Platform 创建 API Key，并将其保存到密码管理器或 CI/CD Secret 中。不要把真实密钥写入 Git 仓库、截图、公开日志、客户端代码或命令历史。OpenAI API 文档要求使用 Bearer 凭证，并建议从环境变量或密钥管理服务读取，不要暴露在浏览器或客户端代码中。OpenAI API 认证说明 developers.openai.com

macOS/Linux：当前终端会话配置

如果密钥已经由密码管理器或 Secret 注入环境变量，可以执行：

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

如果当前会话还没有环境变量，可先临时设置，再登录：

export OPENAI_API_KEY="替换为你的真实APIKey"
printenv OPENAI_API_KEY | codex login --with-api-key
unset OPENAI_API_KEY

不要在共享终端中直接把真实密钥写进命令行。对于脚本和 CI，建议使用平台的 Secret 变量，并通过标准输入传给 Codex。

Windows PowerShell：当前会话配置

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

$env:OPENAI_API_KEY = "替换为你的真实APIKey"
$env:OPENAI_API_KEY | codex login --with-api-key
Remove-Item Env:OPENAI_API_KEY

如果密钥来自 CI/CD Secret，直接让运行器注入 OPENAI_API_KEY，不要把密钥写进脚本文件。

CMD：不建议把真实密钥直接写进命令

CMD 可以使用环境变量后再通过管道登录，但命令历史、构建日志和回显行为更容易造成泄露。若必须使用 CMD，应由 CI/CD 平台注入变量，并检查日志是否会打印变量值；完成后及时清理会话变量。

第三步：检查认证状态、切换账号与清理凭据

登录后执行：

codex login status

官方命令参考说明，该命令会打印当前认证方式；存在凭据时以成功状态退出，因此也适合放进自动化检查。Codex CLI 命令参考 developers.openai.com

如果状态仍显示旧账号或旧的认证方式，先清除已保存凭据：

codex logout

然后重新执行 API Key 登录。官方认证文档说明，Codex CLI 会缓存登录信息，保存位置可能是 ~/.codex/auth.json 或操作系统凭据存储；因此排查时不要只检查环境变量，还要确认本地是否存在旧登录状态。认证缓存与退出登录说明 developers.openai.com

ChatGPT 登录和 API Key 登录有什么区别

对比项ChatGPT 登录API Key 登录
登录方式codex login 后完成浏览器流程通过标准输入执行 codex login --with-api-key
计费来源遵循对应 ChatGPT 工作区或计划规则按 OpenAI API 标准费率计入 API Platform 账户
自动化使用更适合交互式本地使用官方明确建议用于程序化 Codex CLI 工作流，例如 CI/CD
功能范围可使用依赖 ChatGPT 工作区的能力部分依赖 ChatGPT 工作区或云服务的功能可能受限或不可用
清理方式codex logout 清除已保存凭据

因此，个人本地交互使用可以根据账号体系选择 ChatGPT 登录；需要在脚本、私有 CI Runner 或自动化任务中运行时，API Key 通常更容易纳入 Secret 管理。不要把 API Key 登录理解为共享 ChatGPT 订阅额度，两者的计费和权限边界不同。

最小验证与错误分流

完成登录后，先用下面的顺序判断问题位于哪一层：

  1. 命令层：执行 codex --version。若失败，先处理安装或 PATH 问题。
  2. 认证层：执行 codex login status。若没有有效凭据，重新运行登录命令。
  3. 账户层：如果认证状态正常但请求被拒绝，检查 API Key 是否被撤销、项目权限是否正确，以及 API 账户是否具备可用额度。
  4. 模型层：如果提示模型不存在或不可用，不要直接照抄其他教程中的模型名，应以当前账户可用模型和 Codex 当前文档为准。
  5. 网络层：如果出现超时、连接失败或流式中断，先确认代理、DNS、防火墙和企业网络策略，再判断是否为服务端返回错误。
现象优先检查不要先做的事
command not found安装是否完成、npm 全局目录是否在 PATH不要重复创建 API Key
登录命令失败环境变量是否为空、管道是否输出了密钥、Codex 版本是否过旧不要把密钥直接贴到公开日志
401 或认证失败密钥是否正确、是否已撤销、是否登录到了预期账户不要无限重试
403 或权限不足项目、组织、工作区和模型权限不要把 403 当成网络问题
404 或模型不存在模型名称、接口兼容范围和当前账户可用模型不要认为所有模型都能用于 Codex
429 或额度限制账户额度、速率限制和服务端返回的重试信息不要在余额不足时自动重试

第三方 OpenAI-compatible 网关的配置边界

如果你准备把 Codex CLI 指向兼容 OpenAI API 的网关，必须把它和官方 OpenAI API 分开判断。本文核验到的官方 Codex API Key 登录命令，只能证明 Codex 支持通过 API Key 完成本地认证；不能据此证明任意网关都兼容 Codex 所需的请求路径、Responses API、流式传输、工具调用、模型名称或权限行为。

在尝试兼容网关前，先向提供方确认以下四项：是否支持 Codex 当前版本需要的 API 表面、是否提供明确的 Base URL、是否支持目标模型名称、是否说明 API Key 应通过哪种认证头传递。若对方只给出通用 SDK 示例，而没有 Codex CLI 的适配说明，应将结果视为未核实。

不要把 OpenAI CLI 的 OPENAI_BASE_URL 配置经验直接套到 Codex CLI。OpenAI 官方 CLI 文档明确介绍了自身可通过 OPENAI_BASE_URL 指向其他兼容端点，但这不等于 Codex CLI 一定读取同名变量或支持相同配置方式。OpenAI CLI 官方文档 developers.openai.com

如果必须测试兼容网关，先使用非生产密钥和最小权限，记录实际 Codex 版本、Base URL、模型名和返回状态码；确认最小调用成功后，再考虑项目使用。不要在没有官方或提供方文档证明时写入固定的 config.toml 字段。

密钥安全清单：配置成功后还要做什么

OpenAI API 官方文档强调 API Key 属于秘密凭证，应从环境变量或密钥管理服务读取；Codex 官方认证文档也提醒，不要在不受信任或公开环境中暴露 Codex 执行能力。

常见问题

Codex CLI 可以直接读取 OPENAI_API_KEY 吗？

官方 Codex CLI 的 API Key 登录流程是通过标准输入执行 <code>printenv OPENAI_API_KEY | codex login --with-api-key</code>。不要仅凭其他 OpenAI 工具读取环境变量的方式推断 Codex CLI 会自动采用相同逻辑。

Codex CLI 的 API Key 登录会消耗 ChatGPT 订阅额度吗？

不会按 ChatGPT 订阅内的额度处理。官方文档说明，API Key 登录按 OpenAI API 标准费率计入 OpenAI Platform 账户；ChatGPT 登录和 API Key 登录的计费边界不同。

为什么已经设置 OPENAI_API_KEY，Codex 仍然显示旧账号？

Codex 可能正在使用已经保存的登录凭据。先执行 <code>codex login status</code> 确认认证方式，再运行 <code>codex logout</code> 清除已保存凭据，最后重新执行 API Key 登录。

API Key 登录适合放进 CI/CD 吗？

官方认证文档明确将 API Key 认证用于程序化 Codex CLI 工作流，例如 CI/CD。实际部署时应使用 CI/CD Secret 或密钥管理服务，并避免在日志中打印环境变量和 Codex 调试输出。

Codex CLI 能否直接连接任意 OpenAI-compatible 网关？

不能仅凭兼容 OpenAI API 这一描述确认。需要逐项核实 Codex 当前版本所需的请求接口、Base URL、模型映射、流式传输、工具调用和认证方式；没有明确文档支持的配置应视为未核实。

相关阅读

参考资料

  1. OpenAI Codex 官方认证文档
  2. OpenAI Codex CLI 官方命令参考
  3. OpenAI Codex 官方 GitHub 仓库与安装说明
  4. OpenAI API 官方认证与 API 概览
  5. OpenAI CLI 官方文档
  6. github.com