ChatGPT 登录还是 API Key：Codex 两种认证的边界

2026-08-09

装完 Codex（OpenAI Codex）的命令行工具，第一道坎不是写提示词，是认证。官方文档在这里给了两条路：用 ChatGPT 账号登录，或者用 OpenAI 控制台的 API key。很多人随手选一条就往下走了，等到月底看账单、或者公司安全同事来问「这台机器上的东西归谁管」，才发现选的时候没想清楚。

这两条路的差别不在「哪个更好用」，而在三件事的归属：钱从哪个账户扣、这台机器上的会话受哪套治理规则约束、凭据落在磁盘的哪个位置。下面按第一次上手的顺序走一遍，每一步都说清为什么要这么做，以及做错了会在哪里表现出来。

第零步：先确认你要登的是哪一个 codex

这一步经常被跳过，然后在后面制造出最难查的问题：机器上装过好几遍 Codex CLI，你在一个终端里登录了，另一个终端调起来的却是另一份可执行文件，于是「明明登过了却还在提示登录」。

官方给的安装方式有四种：

# macOS / Linux 独立安装脚本
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Windows 独立安装脚本
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

# npm
npm install -g @openai/codex

# Homebrew
brew install --cask codex
brew upgrade --cask codex

四种渠道混装是很常见的事——先用脚本装过，后来又 npm install -g 了一遍。与其去翻 PATH，不如直接问它自己：

codex doctor

在 codex-cli 0.147.0（Windows 11）上，doctor 的 runtime 行会明确写出当前这个 codex 是从哪种渠道装的、可执行文件在哪；本机走的是 npm 全局安装，这一行显示的就是 npm 包内的可执行文件路径，install 行显示 consistent。先看这两行，再谈登录，否则你可能在给一份自己根本不会调用的安装做认证。

两种认证方式的官方口径

官方文档把两种方式列成两行，用词值得逐字读：

方式	官方说明
ChatGPT 登录	使用 ChatGPT workspace 凭据，在浏览器里完成认证。遵循 workspace 权限、RBAC 与企业留存设置
API Key	需要 OpenAI 控制台的 API key，按标准 API 费率通过 OpenAI Platform 账户计费

注意这两行讲的根本不是同一维度的事。ChatGPT 登录那一行讲的是治理——权限、角色、留存策略跟着你所在的 workspace 走；API Key 那一行讲的是计费——走 OpenAI Platform 账户，按 token 用量算钱。官方没有在 API Key 这一行里写治理口径，所以这篇也不替它补写；你要是在有合规要求的团队里，这恰恰是应该去问管理员而不是自己拍脑袋的地方。

对第一次上手的个人开发者，判断依据可以简化成一句话：你已经在为 ChatGPT 订阅付钱、并且希望用量走订阅额度，就选 ChatGPT 登录；你需要的是按用量结算、能进 OpenAI Platform 账单体系的调用，就选 API Key。

第一步：CLI 侧怎么登

ChatGPT 登录只有一条命令：

codex login

它会把你带到浏览器完成认证。做错了会怎样？最典型的是在没有图形界面的远程机器上直接敲这条命令，然后卡在「等浏览器」——这种场景要走下面第四节的设备码方式。

API key 走的是另一个参数。官方给的示例是把 key 从环境变量经管道喂进去：

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

这条命令的形态本身就是提示：key 是从标准输入进去的，而不是作为命令行参数直接写在命令里。命令行参数会原样留在 shell 历史和进程列表里，环境变量加管道这种写法躲开了这一层。你自己敲的时候，环境变量里放的应该是真 key，文章和文档里一律写占位符 <YOUR_API_KEY>。

需要提醒的是：我们核对到的官方示例只有 printenv 这一种写法，而 printenv 是 Unix 侧的命令，Windows 的 PowerShell 里没有这个内置命令。这里不替它发明一条等价写法——Windows 上要用 API key 认证，请以官方文档最新写法为准。做错了会怎样？照抄这条命令在 PowerShell 里跑，你拿到的是「命令未找到」一类的报错，而不是认证失败，别顺着认证的方向去排查。

另外，在 codex-cli 0.147.0（Windows 11）上执行 codex login --help，除了 --with-api-key 之外还能看到一个 --with-access-token，官方给的示例形式是 printenv CODEX_ACCESS_TOKEN | codex login --with-access-token。第一次上手一般用不到它，知道有这个入口就行。

第二步：怎么验收

登完别急着开工，先问一句状态：

codex login status

在 codex-cli 0.147.0（Windows 11）上，本机这条命令的输出是 Logged in using ChatGPT——它会把当前用的是哪种认证方式直接告诉你。这一步的价值在于消歧义：如果你先后试过两种方式，或者在几台机器之间来回切，人的记忆很不可靠，命令不会记错。

要退出，用：

codex logout

官方对它的说明是「Remove stored authentication credentials」，也就是把存下来的凭据清掉。想干净地从一种认证换到另一种，先 logout 再重新 login，比在两种状态之间叠加要省事。

第三步：凭据落在哪，以及为什么必须知道

凭据只会在两个地方之一：

~/.codex/auth.json，明文文件
操作系统的凭据存储（keyring / Windows 凭据管理器）

用哪个由这个配置键决定：

cli_auth_credentials_store = "keyring"  # 可选 file | keyring | auto，默认 auto

官方在这里给了一句原文，值得原样贴出来：「Treat ~/.codex/auth.json like a password: it contains access tokens. Don’t commit it, paste it into tickets, or share it in chat.」——把它当密码看待，它里面装着 access token，不要提交进仓库、不要贴进工单、不要发在聊天里。

在 codex-cli 0.147.0（Windows 11）上，本机 ~/.codex/auth.json 确实存在，是一个几 KB 的小文件。做错了会怎样，这里其实不用多解释：一个明文的、体积很小的、名字很好认的文件，被顺手 git add . 进去或者截图发出去，都不是罕见事故。默认值是 auto，如果你的机器上有多人共用、或者备份策略会把用户目录整个同步走，这个键是你唯一能动的开关。

第四步：没有浏览器的机器怎么登

远程服务器、容器、纯 SSH 的开发机——这类场景 codex login 那套浏览器跳转走不通。官方给的首选做法是设备码登录：

codex login --device-auth

它会给你一个链接和一次性验证码，你在任意一台有浏览器的设备上打开链接、输入码即可。注意这个能力官方标注为 beta 阶段，别把它当成板上钉钉的稳定路径写进团队的标准操作流程，升级版本后先复核一次。

官方另外给了两条备选：

从一台有浏览器的机器上复制已经缓存好的凭据过去；
用 SSH 隧道把 localhost 的回调端口 1455 转发过去，让浏览器回调能打到远程机器上。

第二条的价值在于它解释了第一条路为什么会卡住：浏览器认证要回调到本地的 1455 端口，远程机器上没人接这个回调，流程自然就悬在那儿。知道端口号，你才能判断是网络策略拦了、还是隧道没打通。

第五步：登录失败先看哪里

失败的时候不要盲目重试，官方给了明确的落点：登录失败的诊断信息写在配置的日志目录里的 codex-login.log。先去看这个文件，再决定下一步。

有一类失败特别常见，官方也单独点了名：公司网络上有 TLS 代理或者私有根 CA 的时候，认证握手会被中间设备切断。官方给的做法是在登录之前设置 CODEX_CA_CERTIFICATE 环境变量，把你们的根证书交给它。如果你在公司网里登不上、在手机热点上一登就过，基本可以先往这个方向查。

什么情况说明不是这个原因？如果你在个人网络上同样失败，那就跟 TLS 代理无关，别在证书上耗时间，回去看 codex-login.log。

团队想固定走某一条路：三个配置键

个人用随便切没问题，团队里就不一样了——你不希望有人在公司项目上悄悄挂了自己的 API key。相关的配置键有三个（详见官方《Configuration Reference》）：

键	作用
`forced_login_method`	取值 `chatgpt` 或 `api`，把认证方式固定住
`forced_chatgpt_workspace_id`	固定 ChatGPT 登录使用的 workspace（uuid）
`chatgpt_base_url`	与 ChatGPT 侧 base URL 相关；官方《Configuration Reference》在认证一节只列出了键名，没有给功能说明，具体语义以官方文档为准

# ~/.codex/config.toml
forced_login_method = "chatgpt"
cli_auth_credentials_store = "keyring"

以上为按官方文档键位组合的示例，未逐项实测，以官方文档为准。

钱的边界：两种认证的计费不是一回事

这是选型时真正的分水岭，也是最容易想当然的地方。

ChatGPT 登录走订阅档位。官方定价页上，个人侧是 Free 档 $0/month、Go 档 $8/month、Plus 档 $20/month、Pro 档 Starting at $100/month；企业侧 Business 档 $20/user/month（2 人起，年付；按月付为 $25/month），Enterprise & Edu 为定制报价需联系销售（ChatGPT 官方定价页，2026-08-09 核对，以官方为准）。

订阅档的用量口径要特别注意：计量单位是 messages（消息数），窗口是 5 小时滚动窗口，而且同一档位下的区间跨度极大——官方给 Plus 的是 10–2,000 messages / 5h，Pro 是 50–40,000 messages / 5h，明确说明这取决于模型（Pro 还取决于档位）。所以正确的读法是「官方给的是一个随模型变化的区间」，不要把区间的任何一端当成「我能用多少」。

API Key 那条路是按 token 用量计费，走 OpenAI Platform 账户，没有 5 小时窗口这回事——它的约束不是「这一阵子用完了」，而是账单上的数字会一直往上走。

还有一条必须写明是限时活动而不是常规权益：官方公告口径里，限时内 Codex 包含在 ChatGPT Free 与 Go 中，并且 Plus、Pro、Business、Enterprise、Edu 的速率上限翻倍，更高上限在 app、CLI、IDE、cloud 四个面上都适用。活动会结束，别把它当作长期选型的依据。价格与活动随时可能调整，下单前请以官方页面为准。

桌面应用与 IDE 扩展怎么选

这两个面我们没有实测，只转述官方文档口径：桌面应用在登出界面选 “Continue to sign in” 走 ChatGPT 登录，选 “Sign in another way” 走 API key；IDE 扩展的登出界面则是 “Sign in with ChatGPT” 与 “Use API Key” 两个选项。界面表述会随版本变，以你手上那一版为准。

什么情况不适合按这篇来做

公司发的设备、公司的 workspace：认证方式很可能由管理员统一约束，你自己在 config.toml 里改 forced_login_method 未必生效，也未必合规。先问管理员。
需要精确成本预算：这篇给的是档位价与计费口径，不能据此推算「一个月要花多少钱」——那需要额外假设，官方没给这个换算。
多账号切换、企业 SSO 的具体配置、access token 的有效期：官方文档在这三处的细节不在本文核对范围内，别照着推断。

最后回到开头那三件事：钱从哪儿扣、受谁管、凭据在哪。这三个问题你能各答一句，认证这一步就算过了；答不上来的那一项，就是你接下来该去查的地方。