Codex CLI API Key 配置与登录验证指南
简答：Codex CLI 可以通过 OpenAI API Key 登录：先在 OpenAI API Platform 创建自己的密钥，再用环境变量或标准输入传给 <code>codex login --with-api-key</code>，最后运行 <code>codex login status</code> 验证。不要把密钥写进代码、命令参数或提交到仓库。
定义：Codex CLI API Key 是用于让终端版 Codex 访问 OpenAI API 的项目密钥，和通过 ChatGPT 账户登录属于两条不同的认证路径。
先照做：创建 API Key 并完成 Codex 登录
本文是独立的 AI API 接入指南，不是 Codex 或 OpenAI 的官方页面。下面只介绍公开资料能够核实的 OpenAI API Key 配置方式；如果你使用的是兼容接口或其他网关，变量名、登录方式和计费规则应以对应服务的文档为准。
- 登录 OpenAI API Platform，进入所属项目的 API Keys 页面，创建一个新的 secret key。
- 创建成功后立即保存密钥。官方说明显示，完整 secret key 只会在创建时展示，之后无法再次查看；遗失时应重新创建，而不是寻找所谓“找回原密钥”的方法。参考 OpenAI API Key 管理说明。
- 确认 Codex CLI 已安装，并在项目目录中运行
codex。官方入门资料列出的安装方式包括npm install -g @openai/codex，也可参考仓库中的安装说明。 - 不要把密钥直接拼在命令行参数中。当前官方仓库的命令实现说明，
codex login --with-api-key会从标准输入读取 API Key，因此推荐使用管道或交互式输入。 - 登录后运行
codex login status查看当前认证状态。需要退出时运行codex logout。
官方仓库中的命令定义明确列出了 --with-api-key，并给出了从 OPENAI_API_KEY 管道读取的示例：Codex CLI 登录命令源码。如果你的本地版本不识别这些参数，先检查 CLI 版本和安装来源，再对照 OpenAI Codex 官方仓库更新。
macOS/Linux：用环境变量和标准输入配置
OpenAI 的密钥安全建议是使用环境变量 OPENAI_API_KEY，而不是把密钥写入源码。临时配置适合当前终端会话，关闭终端后变量通常不会继续存在。
推荐的交互式写法如下，输入时不会把密钥直接写进命令历史：
read -r -s OPENAI_API_KEY
export OPENAI_API_KEY
printf '\n'
if [ -z "$OPENAI_API_KEY" ]; then
echo "OPENAI_API_KEY 为空" >&2
exit 1
fi
printf '%s' "$OPENAI_API_KEY" | codex login --with-api-key
codex login status如果密钥已经安全地存在环境变量中，可以使用：
if [ -z "${OPENAI_API_KEY:-}" ]; then
echo "请先设置 OPENAI_API_KEY" >&2
exit 1
fi
printf '%s' "$OPENAI_API_KEY" | codex login --with-api-key
codex login status这里使用 printf 把变量内容通过标准输入传递给登录命令，不需要把密钥放进 URL，也不建议把完整密钥直接写在命令行参数中。OpenAI 的安全建议还包括为不同成员、项目或用途使用独立密钥，并定期轮换，具体可参考 API Key 安全最佳实践。
需要长期使用时怎么保存
- 个人开发环境：使用操作系统或开发工具的环境变量管理，不要把真实密钥写入 Git 仓库。
- 共享项目：为项目或成员创建独立密钥，避免多人共用同一个 secret key。
- CI/CD：把密钥放在 CI 平台的 Secrets 中，在任务运行时注入
OPENAI_API_KEY，不要写进 YAML、日志或构建产物。
Windows PowerShell：设置变量并登录 Codex CLI
PowerShell 中可以先为当前会话设置环境变量，再通过管道交给 Codex。以下示例不会把密钥作为 --api-key 参数传入：
$OPENAI_API_KEY = Read-Host "OpenAI API Key" -AsSecureString
$ptr = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($OPENAI_API_KEY)
try {
$plainKey = [Runtime.InteropServices.Marshal]::PtrToStringBSTR($ptr)
$env:OPENAI_API_KEY = $plainKey
}
finally {
if ($ptr -ne [IntPtr]::Zero) {
[Runtime.InteropServices.Marshal]::ZeroFreeBSTR($ptr)
}
}
if ([string]::IsNullOrWhiteSpace($env:OPENAI_API_KEY)) {
throw "OPENAI_API_KEY 为空"
}
$env:OPENAI_API_KEY | codex login --with-api-key
codex login status如果你要让后续新开的终端继续使用变量，可以使用系统提供的环境变量设置方式；但长期保存前应先确认设备是个人电脑还是共享环境。OpenAI 的安全页面建议避免在客户端应用中暴露密钥、不要提交到公开仓库，并在怀疑泄露时立即删除或轮换，详见 OpenAI 账户与 API Key 安全说明。
PowerShell 的管道行为可能受本地版本和命令解析影响。如果登录后状态不符合预期，先单独检查 $env:OPENAI_API_KEY 是否为空，再重新执行登录命令；不要为了排查把完整密钥打印到屏幕。
ChatGPT 登录和 API Key 登录有什么区别
| 项目 | ChatGPT 登录 | API Key 登录 |
|---|---|---|
| 认证入口 | 在 Codex CLI 中选择 ChatGPT 登录并完成浏览器授权 | 在 API Platform 创建密钥，再通过环境变量或标准输入登录 |
| 适合场景 | 希望使用符合账户条件的 ChatGPT 计划权益，且不想手动复制密钥 | 本地脚本、自动化任务、CI/CD 或需要按 API 项目管理访问的场景 |
| 密钥处理 | 登录流程可在本地保存认证凭据，通常不需要手动复制 API Key | 需要自行保护、轮换、撤销 API Key |
| 额度与计费 | 受 ChatGPT 账户、工作区和当前产品规则影响 | 受 API 项目、模型权限、限速与 API 账户设置影响 |
| 自动化 | 不适合作为无人值守脚本的唯一认证方案 | 更适合通过 CI/CD Secrets 注入，但要控制权限和生命周期 |
官方资料将这两种方式分别说明：Codex CLI 可以选择 Sign in with ChatGPT，也可以使用 API Key；ChatGPT 计划页面则把 CLI 作为账户登录入口之一。因为两条路径的账户体系和使用限制不同，不要把 ChatGPT 订阅权益直接当成 API 项目余额或 API Key 权限。可对照 Codex CLI 与 ChatGPT 登录说明 和 使用 ChatGPT 计划访问 Codex。
登录失败时按这张表排查
| 现象 | 先检查什么 | 下一步动作 |
|---|---|---|
命令提示找不到 codex | CLI 是否安装成功，当前终端的 PATH 是否包含安装目录 | 重新打开终端，并对照 Codex CLI 官方入门说明检查安装方式 |
--with-api-key 不被识别 | 本地 Codex CLI 版本是否过旧，是否调用了另一个同名程序 | 运行版本检查并从官方仓库更新，避免混用旧版二进制 |
| 登录后仍提示未认证 | 标准输入是否真的传入，环境变量是否为空，是否在另一个终端检查状态 | 重新运行 printf '%s' "$OPENAI_API_KEY" | codex login --with-api-key，然后执行 codex login status |
| 出现 401 或 invalid API key | 密钥是否复制完整、是否已被删除、是否属于当前项目 | 在 API Key 页面确认密钥状态；必要时创建新密钥并轮换旧密钥 |
| 出现权限、额度或限速提示 | 项目的模型访问、API Key 权限、用量和限额 | 检查项目设置与 Usage 页面；官方项目文档说明可按项目管理 API Key、模型访问和限速 |
| CI/CD 中登录失败 | Secret 是否注入到正确任务、变量名是否为 OPENAI_API_KEY、日志是否暴露了变量 | 在任务中只检查变量是否非空，不打印变量值，并使用独立的 CI 密钥 |
| 自定义兼容接口无法连接 | 当前配置是否仍然使用 OpenAI 官方 CLI 的认证路径 | 本文只核实 OpenAI API Key 登录；自定义 Base URL、模型名和网关参数应查看对应兼容接口文档 |
其中，“命令存在但行为不同”不应直接归因于某个服务故障。先确认实际执行的 Codex CLI 版本、登录命令来源和当前认证状态；公开资料能够确认的是官方仓库当前包含 codex login status、codex logout 以及从标准输入读取 API Key 的选项。
退出、撤销与轮换 API Key
- 在 Codex CLI 中运行
codex logout，清理本地登录状态。 - 如果只是更换本地使用的密钥，先在 API Platform 创建新密钥，再更新环境变量或 CI/CD Secret。
- 用新密钥完成一次登录和最小化验证后，再到 API Keys 页面删除旧密钥。
- 如果密钥曾出现在日志、截图、聊天记录、公开仓库或 URL 中，不要只删除本地文件，应立即在 API Key 页面撤销，并检查 Usage 是否出现异常调用。
官方说明指出，删除后的 API Key 不能继续使用；安全最佳实践建议建立轮换流程，并为不同成员或用途使用独立密钥。API Platform 的项目文档还说明，项目可以管理 API Key 权限、模型访问、用量和支出限制，因此生产环境应尽量使用范围更小、生命周期更短的密钥。
不要购买、传播或使用来源不明的 API Key。本文无法核验任何第三方密钥的归属、有效期、权限或安全性；如需使用兼容接口，请自行核对其服务条款、数据处理说明、Base URL 和密钥管理方式。
安全自查清单
- 没有明文提交：搜索仓库、Shell 历史、CI 日志和公开 issue，确认没有完整密钥。
- 没有放进 URL：API Key 不应出现在查询参数、浏览器地址栏或分享链接中。
- 没有写入前端：浏览器、移动端和公开客户端不应直接携带长期 API Key，应由后端或受控任务调用。
- 权限可控：根据项目需要选择合适的 API Key 权限，不默认给所有自动化任务最高权限。
- 能够撤销：记录密钥用途和负责人，确认泄露时可以快速定位并删除。
- 用量可观察：为项目设置预算提醒或硬限制，并定期查看使用情况。
如果你只需要让 Codex CLI 在本地工作，最小可行路径是：创建自己的 API Key，临时设置 OPENAI_API_KEY，通过标准输入执行 codex login --with-api-key，再用 codex login status 验证。不要为了“方便”把密钥硬编码到脚本或共享给其他人。
常见问题
Codex CLI API Key 从哪里创建？
在 OpenAI API Platform 的项目 API Keys 页面创建。官方说明显示，完整 secret key 只在创建时展示，遗失后通常需要创建新密钥，不能依赖之后再次查看。
Codex CLI 可以直接使用 OPENAI_API_KEY 吗？
可以把 OPENAI_API_KEY 作为环境变量保存，再通过标准输入执行 <code>printf '%s' "$OPENAI_API_KEY" | codex login --with-api-key</code>。登录后建议运行 <code>codex login status</code> 验证。
为什么 ChatGPT 能登录，API Key 却不能用？
ChatGPT 登录和 API Key 登录是不同认证路径。API Key 还受到项目归属、密钥状态、权限、模型访问、用量和限额影响，应在 API Platform 项目设置中逐项核对。
Windows PowerShell 如何设置 Codex 的 API Key？
可用 <code>Read-Host -AsSecureString</code> 读取后写入当前会话的 <code>$env:OPENAI_API_KEY</code>，再通过管道执行 <code>codex login --with-api-key</code>。不要把完整密钥打印出来或写进脚本仓库。
API Key 泄露后只运行 codex logout 是否足够？
不够。<code>codex logout</code> 用于清理本地登录状态；如果密钥已经暴露，应在 API Key 页面删除或撤销旧密钥，创建替代密钥，并检查项目用量和日志。
第三方兼容接口能直接套用这套 Codex 配置吗？
不能默认认为可以。本文核实的是 OpenAI API Key 与官方 Codex CLI 的登录路径；兼容接口可能要求不同的 Base URL、模型名、认证头或账户规则，应以对应服务的公开文档为准。