4. 登录与认证

本节目标：学会两种登录方式、搞懂认证流程、知道远程环境怎么登录、会管理多个账号。

装好的 Codex 还是个「不认识你」的空壳，得登录绑上账号才能干活。在你的项目目录里启动 CLI：

codex

没有有效登录态时，它会默认引导你登录。

两种登录方式

Codex 支持两种登录方式，选哪个取决于你的使用场景。

方式	怎么登	适合谁	计费
ChatGPT 账号（默认推荐）	浏览器授权	大多数人、要用云端功能	走你的 ChatGPT 套餐额度
API Key	从 OpenAI 后台拿 key	CI/CD、程序化跑 CLI	按标准 API 价格计费

ChatGPT 账号登录

启动 Codex 后选 “Sign in with ChatGPT”，它会弹出浏览器走 OAuth 授权流程。授权完浏览器把 access token 送回 CLI，就登上了。

ChatGPT 的 Free、Go、Plus、Pro、Business、Edu、Enterprise 套餐都包含 Codex 用量（Free 和 Go 额度较少，Plus 起可用 GPT-5.6 全系列）。你日常开发用套餐额度就够，还能用上云端任务。

API Key 登录

从 OpenAI 后台拿一个 API key，选用 API key 登录。OpenAI 按标准 API 价格从你的 Platform 账户扣费，跟套餐里那份额度是两本账。

Warning

用 API key 登录时，部分依赖 ChatGPT 工作区的功能会受限或不可用。比如云端 Codex 就强制要 ChatGPT 登录。本地 CLI 用 API key 跑是没问题的。

Tip

我自己日常开发用 ChatGPT 账号登录—套餐里的额度够用，还能用上云端任务。API key 只在写自动化脚本、放进 CI 时才用，因为它不需要浏览器交互，适合无人值守。

认证流程详解

ChatGPT 账号登录的完整流程是这样的：

在终端敲 codex 启动
选择 “Sign in with ChatGPT”
浏览器自动打开 OpenAI 授权页面
在浏览器里登录你的 ChatGPT 账号并授权
授权完成后，浏览器把 access token 送回 CLI
终端显示登录成功，可以开始干活

登录成功后，凭据缓存在本地，下次启动直接复用，不用重登。ChatGPT 登录的会话，Codex 会在过期前自动刷新 token，所以正常用着一般不用反复登。

登录凭据存在哪

登录凭据缓存在本地文件 ~/.codex/auth.json 里，或存在 OS 系统凭据存储里（macOS 上可能走 Keychain）。

你可以用配置项 cli_auth_credentials_store 指定存储方式：

# ~/.codex/config.toml
cli_auth_credentials_store = "file"  # 明文文件
# cli_auth_credentials_store = "keyring"  # 系统凭据存储
# cli_auth_credentials_store = "auto"  # 自动选择

Warning

~/.codex/auth.json 里装着你的 access token，把它当密码看：别提交进 Git、别贴进工单、别发到聊天里。

两个关键点：

CLI 和 IDE 扩展共享同一份登录缓存—在一边登出，另一边下次启动也得重登
桌面应用各自独立登录

远程服务器登录

在远程服务器、headless 环境（没有图形界面的服务器）、或本机网络挡了 localhost 回调时，浏览器登录这条路走不通。官方首选解法是设备码登录（Device Code Login）。

在交互登录界面选 “Sign in with Device Code”，或直接运行：

codex login --device-auth

它会给你一个链接和一次性验证码，你在任意能上网的浏览器打开链接、输码，就登上了。完全不依赖本机有没有浏览器。

Note

设备码登录是测试版（beta）功能。需要先在 ChatGPT 安全设置（个人）或工作区权限（管理员）里开启。如果服务器端没开、设备码走不通，还有两条退路。

退路一：拷贝认证缓存

在一台有浏览器的机器上正常 codex login，确认生成了 ~/.codex/auth.json，再把它拷到 headless 机器的同一路径：

ssh user@remote 'mkdir -p ~/.codex'
scp ~/.codex/auth.json user@remote:~/.codex/auth.json

退路二：SSH 端口转发

把 Codex 的本地回调端口（默认 localhost:1455）从远程转发到本地：

ssh -L 1455:localhost:1455 user@remote

然后在这个 SSH 会话里跑 codex login，按提示在你本地浏览器打开地址即可。

多账号管理

有时候你有多个 ChatGPT 账号或 API key，想在不同场景用不同的。Codex 提供了几种方式管理。

用 profile 切换

一个 profile 就是 CODEX_HOME 下一个单独的文件，名字是 <档名>.config.toml。你可以给不同账号建不同 profile：

# ~/.codex/work.config.toml
# 工作账号的配置

# ~/.codex/personal.config.toml
# 个人账号的配置

用 --profile 选它：

codex --profile work
codex --profile personal

Note

自 Codex 0.134.0 起，--profile 不再读 config.toml 里的 [profiles.档名] 旧写法，改用单独的 ~/.codex/<名字>.config.toml 文件。老配置需要迁移。

用 CODEX_HOME 切换

更彻底的方式是设不同的 CODEX_HOME 环境变量，让每个账号有完全独立的配置、认证、历史目录：

# 工作账号
CODEX_HOME=~/.codex-work codex

# 个人账号
CODEX_HOME=~/.codex-personal codex

Tip

CODEX_HOME 是 Codex 存所有本地东西的地方—配置、登录凭据、历史记录、日志。默认在 ~/.codex。设了它，目录必须已经存在。

用环境变量临时指定 API key

对于 codex exec 非交互模式，可以用环境变量临时提供 API key：

CODEX_API_KEY=sk-xxx codex exec "检查一下这个文件"

Warning

CODEX_API_KEY 只支持 codex exec，不支持交互式 CLI。运行仓库可控代码时，请内联设置它，而不是在整个 job 范围内设置，防止泄露。

登出

需要登出或切换账号时：

codex logout

这会清除本地缓存的登录凭据。下次启动需要重新登录。

小结

两种登录方式：ChatGPT 账号是默认推荐（套餐额度、功能全），API key 适合 CI/CD（按量计费、部分功能受限）
认证流程：浏览器 OAuth 授权，凭据缓存在 ~/.codex/auth.json，自动刷新 token
远程环境：首选 codex login --device-auth，退路是拷贝 auth.json 或 SSH 端口转发
多账号管理：用 --profile 切配置预设，或用 CODEX_HOME 完全隔离

登录搞定后，下一章咱们跑通第一个任务。