Codex 怎么配置 API Key？按场景完成登录、验证与排错
简答：先在 OpenAI Platform 创建 API Key，再根据使用场景选择 Codex CLI、桌面端或 IDE 的 API Key 登录入口。CLI 可将 OPENAI_API_KEY 通过标准输入传给 codex login；桌面端选择“Sign in another way”，IDE 扩展选择“Use API Key”。最后用 codex login status 或客户端账号状态确认认证方式，并注意 API Key 使用按 OpenAI Platform 的 API 计费规则处理，不等同于 ChatGPT 方案额度。
定义：Codex API Key 是用于让 Codex CLI、桌面端或 IDE 扩展通过 OpenAI Platform API 完成身份认证的密钥。
先选对配置路径：三种场景一张表看懂
本文是第三方 AI API 接入指南，帮助你配置 Codex API Key，不代表任何官方站点。先按自己的使用方式选择路径：
| 你的场景 | 建议入口 | 最短操作 | 成功判定 |
|---|---|---|---|
| 只使用 Codex CLI | 终端 | 设置 OPENAI_API_KEY，执行 printenv OPENAI_API_KEY | codex login --with-api-key | 运行 codex login status 查看认证方式 |
| 使用 Codex 桌面端 | 未登录页面 | 选择 Sign in another way，输入 API Key | 回到账号菜单，确认 API Key 状态 |
| 使用 IDE 扩展 | 扩展登录页面 | 选择 Use API Key，输入密钥 | 账号菜单显示当前 API Key 状态 |
| 需要 ChatGPT 工作区或云端功能 | ChatGPT 登录 | 使用 codex login 完成浏览器登录 | 确认当前账号、工作区和功能权限 |
官方认证文档明确列出 ChatGPT 登录与 API Key 登录两种方式，并说明桌面端、Codex CLI 和 IDE 扩展都支持 API Key；Codex Cloud 则要求使用 ChatGPT 登录。可查看官方 Authentication 文档核对当前入口。
创建 API Key：先核对入口，再安全保存
- 打开 OpenAI Platform 的 API Key 管理入口，创建或获取用于 Codex 的 API Key。
- 创建后立即保存到密码管理器或其他受控凭据存储中，不要把完整密钥发到聊天、工单、截图或公开日志。
- 不要把密钥写进前端代码、公开仓库或提交到 Git；需要在脚本中使用时，优先通过环境变量或受控凭据注入。
- 如果密钥已经暴露，先在平台撤销或轮换，再在 Codex 中重新登录。
“项目 API Key”“创建密钥”等入口名称可能随控制台界面变化。如果当前页面找不到对应入口，应从 OpenAI Platform 当前控制台和官方开发者文档进入，不要根据旧截图猜测位置。官方插件文档也将“创建、保存和连接项目 API Key”作为开发者流程的一部分，可参考OpenAI Developers plugin 文档。
计费提醒：官方认证文档说明，使用 API Key 时，相关 Codex 使用按 OpenAI Platform 的标准 API 费率处理，并使用 API Key 认证时不消耗 ChatGPT 方案中包含的额度。具体价格、项目权限、余额和可用功能，应以当前平台计费页、项目页面和 Codex 文档为准。
Codex CLI 配置 API Key：推荐使用标准输入传递
macOS 或 Linux
先在当前终端设置环境变量：
export OPENAI_API_KEY="你的_API_Key"
再通过标准输入完成 Codex CLI 登录：
printenv OPENAI_API_KEY | codex login --with-api-key
官方 Authentication 文档给出了这条 Codex CLI 命令；官方 API Quickstart 也给出了 macOS/Linux 使用 export OPENAI_API_KEY 的示例，详见OpenAI API Quickstart。
Windows PowerShell
官方 API Quickstart 给出的 PowerShell 写法是：
setx OPENAI_API_KEY "你的_API_Key"
执行后打开新的 PowerShell 窗口，再检查变量是否可读：
echo $env:OPENAI_API_KEY
确认变量存在后，将它传给 Codex：
$env:OPENAI_API_KEY | codex login --with-api-key
setx 会把变量写入之后启动的环境，当前窗口未必立即刷新；如果新窗口仍为空，检查变量名、引号和密钥复制是否完整。
Windows CMD
如果你使用 CMD，可以在当前窗口写入临时变量：
set OPENAI_API_KEY=你的_API_Key
然后执行：
echo %OPENAI_API_KEY% | codex login --with-api-key
CMD 语法与 PowerShell 不同，不要把 $env: 或 PowerShell 命令直接粘贴到 CMD。若当前 Codex 版本对该命令报错，先运行 codex --help，以本机 CLI 帮助和当前 Authentication 文档为准。
验证 CLI 是否已经切换到 API Key
官方认证页面提供了：
codex login status
它用于查看当前认证方式。如果当前 CLI 提示命令不存在或输出与文档不同，运行 codex --help 核对本机版本支持的子命令，不要根据其他版本的输出格式判断成功。
桌面端与 IDE 扩展：入口可能随版本调整
Codex 桌面端
- 打开桌面端，在未登录页面开始登录。
- 选择
Sign in another way，不要误选 ChatGPT 浏览器登录。 - 输入 API Key，点击继续。
- 登录后打开账号或个人资料菜单，确认当前显示的是 API Key 状态。
官方文档明确给出的桌面端 API Key 入口是 Sign in another way。如果你当前版本看不到完全相同的按钮，优先查看未登录页面中的其他登录方式，并通过官方 Authentication 文档核对，而不是把密钥粘贴到普通聊天输入框。
IDE 扩展
- 打开安装了 Codex 扩展的 IDE。
- 在扩展的未登录页面选择
Use API Key。 - 输入 API Key 并确认。
- 回到扩展账号菜单，确认当前认证状态；必要时发起一个不含敏感代码的只读测试任务。
官方认证页面说明 IDE 扩展使用 Use API Key 入口。按钮名称、菜单位置和账号状态显示可能随客户端版本变化，因此应以当前扩展页面和官方文档为准。
API Key 认证支持本地 Codex 工作流，但官方同时说明，依赖 ChatGPT 工作区访问或云服务的部分功能可能受限或不可用；这不是“所有功能都不能用”，也不能把某个客户端的表现泛化到所有版本。需要云端或工作区能力时，应改用 ChatGPT 登录并核对当前功能支持。
ChatGPT 登录与 API Key 登录：不要混淆两套认证
| 项目 | ChatGPT 登录 | API Key 登录 |
|---|---|---|
| 登录方式 | 浏览器完成 ChatGPT 账号登录 | 从 OpenAI Platform 获取 API Key 后输入或通过 CLI 传入 |
| CLI 命令 | codex login | printenv OPENAI_API_KEY | codex login --with-api-key |
| 计费口径 | 遵循 ChatGPT 方案、账号和工作区规则 | 相关使用按 OpenAI Platform 的标准 API 费率处理 |
| 适用范围 | 需要 ChatGPT 账号、工作区或云端能力的场景 | 本地开发、脚本化 CLI 和部分自动化流程 |
| 能力边界 | 取决于账号、工作区、方案和权限 | 依赖 ChatGPT 工作区或云服务的部分功能可能受限 |
官方文档把两种登录方式定义为不同认证路径：ChatGPT 登录面向订阅访问，API Key 登录面向按使用量计费的访问；API Key 认证不启用依赖 ChatGPT 工作区的全部能力。详细边界请查看认证文档中的 Authentication 章节和Codex 与 ChatGPT 方案说明。
401、密钥无效、变量未生效：按顺序排查
- 确认实际使用的密钥：检查环境变量是否为空，但不要在终端、CI 日志或截图中回显完整密钥。只显示是否存在，或仅保留末尾少量字符用于人工核对。
- 确认认证状态：运行
codex login status。如果仍是旧的 ChatGPT 登录或旧 API Key，先运行codex logout，再重新执行 API Key 登录；如果当前版本不支持这些命令，以codex --help为准。 - 确认终端语法：macOS/Linux 使用
printenv OPENAI_API_KEY，PowerShell 使用$env:OPENAI_API_KEY，CMD 使用%OPENAI_API_KEY%。变量为空时，先解决环境变量问题，不要急着更换模型。 - 确认密钥是否已撤销或复制错误：检查是否混入空格、换行、引号或使用旧密钥。若密钥曾经暴露，直接撤销并创建新密钥通常比反复重试更稳妥。
- 确认项目和用量状态：有效的 API Key 不代表项目一定拥有所需权限，也不代表当前项目用量设置满足请求。到 OpenAI Platform 检查项目权限、计费和用量信息。
- 区分认证失败与功能限制：如果登录成功但某项功能不可用，先核对该功能是否依赖 ChatGPT 工作区或云服务；不要把所有失败都归因于 401 或网络。
官方文档还说明，桌面端、Codex CLI 和 IDE 扩展会缓存登录信息，CLI 与扩展共享缓存；凭据可能存放在 ~/.codex/auth.json 或操作系统凭据存储中。因此，切换密钥后仍显示旧状态时，退出登录并重新认证，同时检查本机凭据存储。
API Key 安全清单：配置成功后再做三项检查
- 不要提交：检查 Git 暂存区、提交记录、终端历史和 CI 日志中是否出现完整密钥。
- 不要前端暴露：浏览器端、公开网页和客户端分发包不适合直接放长期 API Key，应由受控后端或安全凭据机制调用。
- 及时轮换：怀疑泄露时先撤销旧密钥，再创建新密钥，并重新登录 Codex。
- 限制环境：官方建议不要在不可信或公开环境中暴露 Codex 执行过程；自动化任务应使用受控的私有运行环境。
- 留存证据：排查时记录客户端版本、系统、认证方式和脱敏错误信息，但不要记录完整密钥。
完成后，最小成功判定不是“按钮消失”，而是：当前客户端显示 API Key 认证状态，CLI 能通过 codex login status 查询认证方式，并且在不含敏感信息的目录中完成一次简单、只读的测试任务。
常见问题
Codex API Key 从哪里获取？
应从 OpenAI Platform 的 API Key 管理入口创建或获取。控制台的项目、密钥和权限界面可能调整，如果找不到入口，以当前平台页面和官方开发者文档为准，不要从第三方截图复制密钥。
配置了 OPENAI_API_KEY，Codex 还是要求登录怎么办？
先用当前系统的变量读取命令确认变量不为空，再运行 codex login status 查看认证方式。如果仍是旧缓存，可运行 codex logout 后重新执行 printenv OPENAI_API_KEY | codex login --with-api-key；若命令不可用，先运行 codex --help 核对当前版本。
Codex API Key 会消耗 ChatGPT 方案额度吗？
官方认证文档将两者分开说明：API Key 认证使用 OpenAI Platform 的标准 API 计费，不使用 ChatGPT 方案中包含的额度。具体价格、项目用量和限制以当前平台页面及官方文档为准。
PowerShell 执行 setx 后当前窗口读取不到怎么办？
setx 写入的是之后启动的环境变量。关闭当前 PowerShell，打开新窗口后运行 echo $env:OPENAI_API_KEY；如果仍为空，检查变量名、引号、密钥复制和当前用户环境设置。
桌面端或 IDE 找不到 Sign in another way、Use API Key 怎么办？
官方文档当前列出的入口分别是 Sign in another way 和 Use API Key，但客户端界面可能变化。先确认处于未登录页面，再查看其他登录方式；仍找不到时用当前 Authentication 文档和客户端帮助核对版本，不要把 API Key 粘贴到普通聊天框。
API Key 登录后，Codex 的所有功能都能使用吗？
不能直接这样推断。官方说明 API Key 支持本地 Codex 工作流，但依赖 ChatGPT 工作区访问或云服务的部分功能可能受限或不可用。需要这些能力时，应使用 ChatGPT 登录并逐项核对当前功能支持。
相关阅读
- 继续查看兼容 API 的 Base URL、认证与排错方法
- 如果你也使用 Cursor，可参考自己的 API Key 配置步骤
- Windows 用户可继续查看环境变量和密钥未生效排查
- 查看更多 AI API 接入与错误诊断文章
参考资料
- Authentication | ChatGPT Learn（learn.chatgpt.com）
- Developer quickstart | OpenAI API
- Using Codex with your ChatGPT plan
- OpenAI Developers plugin