Codex CLI 登录：ChatGPT 账号和 API Key 两种方式

这篇适合谁、读完能做到什么

这篇适合想在终端里使用 Codex 的开发者。读完你应该能分清 ChatGPT 账号登录和 API Key 登录各自适合什么场景，会用 codex login 完成登录，知道怎么查看和退出登录，知道登录信息存放在哪里，也知道在远程机器上登录不成功时可以换哪种办法。^[1]^[2]

如果你是开发者，想在终端或代码编辑器里使用 Codex，官方快速开始页给出的两个入口是 Codex CLI 和 Codex IDE 扩展。^[1]

本文只讲登录和认证。这里不讲安装步骤，所以下面默认你已经装好了 Codex CLI。

Codex 在使用 OpenAI 模型时，有两种登录方式：用 ChatGPT 账号登录，获得订阅形式的访问；用 API Key 登录，按用量计费。^[2] 桌面应用、CLI 和 IDE 扩展在本地工作时两种方式都支持，但 Codex cloud 只能用 ChatGPT 账号登录。^[2]

两种方式的计费不一样。用 API Key 登录时，Codex 按标准 API 价格计费，不再消耗 ChatGPT 套餐里包含的额度；API Key 的用量由 OpenAI Platform 账户计费。^[2]

API Key 能用的功能范围也更窄。依赖 ChatGPT 工作区权限或云端服务的功能，在 API Key 登录下可能受限，甚至不可用。^[2] 所以在依赖某个功能之前，先确认它在你的登录方式下能用。

文档对 API Key 的定位是：适合 CI/CD 之类的程序化 Codex CLI 工作流，并且称 API Key 仍是自动化场景的推荐默认方式。文档同时提醒，不要把 Codex 的执行放在不受信任或公开的环境里。^[2]

先从 OpenAI 控制台拿到 API Key。^[2] 然后用管道把环境变量里的 Key 通过标准输入交给 codex login：

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

运行 codex logout，清除当前保存的登录信息。^[2] 退出后，下次启动 CLI 或扩展时需要重新登录。^[2]

Codex 会缓存登录信息，缓存有两个位置：一个是明文文件 ~/.codex/auth.json，另一个是操作系统的凭据存储。^[2] CLI 和 IDE 扩展共用同一份缓存，所以在其中一个里登出，另一个下次启动时也要重新登录。^[2]

配置项 cli_auth_credentials_store 决定凭据存放的位置，可选值是 file、keyring、auto 和 ephemeral。^[2]

# file | keyring | auto | ephemeral
cli_auth_credentials_store = "keyring"

四个取值的含义如下：

注意 auth.json 里有访问令牌，要像密码一样保管：不要提交到代码仓库，不要贴进工单，也不要粘贴到聊天里。^[2]

如果 CLI 跑在远程机器或无头（headless）环境里，浏览器登录可能走不通。这时文档推荐设备码认证（beta）。^[2]

设备码登录要先开启：个人账号在 ChatGPT 的安全设置里打开，工作区账号则由工作区管理员在工作区权限里打开。^[2] 开启后运行 codex login --device-auth。^[2]

如果设备码登录在你的环境里不可用，文档给出两个备选办法：

在有浏览器的机器上运行 codex login，然后把 ~/.codex/auth.json 复制到无头机器上的同一路径。如果凭据存在操作系统的凭据存储里，这个办法可能不适用。^[2]
用 SSH 转发 Codex 的本地回调端口。默认回调地址是 localhost:1455，在本地机器上运行 ssh -L 1455:localhost:1455 user@remote，然后在这个 SSH 会话里运行 codex login，并在本地打开它打印出的地址。^[2]

其中 user@remote 换成你自己的用户名和主机地址。