Appearance
Codex 支持两种身份认证方式：用 ChatGPT 账号登录（适合订阅用户，支持积分计费和云端功能），或用 API Key 登录（适合 CI/CD 自动化）。本文说明两者的使用场景、凭据存储位置、无头/远程机器的登录方案，以及企业管理员如何强制限定登录方式。
Codex 身份认证
OpenAI 认证方式
Codex 支持两种登录方式：
- Sign in with ChatGPT：使用 ChatGPT 订阅访问
- Sign in with API Key：按用量计费访问
Codex cloud 必须用 ChatGPT 登录。Codex CLI 和 IDE 扩展两种方式都支持。
登录方式也决定了哪些管理控制和数据处理策略适用：
- 用 ChatGPT 登录时，Codex 使用遵循 ChatGPT 工作区的权限、RBAC，以及 ChatGPT Enterprise 的数据保留和驻留设置
- 用 API Key 登录时，使用 API 组织的数据保留和共享设置
CLI 在没有有效 session 的情况下，默认走 ChatGPT 登录流程。
用 ChatGPT 登录
从 Codex App、CLI 或 IDE Extension 用 ChatGPT 登录时，Codex 会打开浏览器让你完成登录流程。登录后，浏览器将访问 token 返回给 CLI 或 IDE 扩展。
用 API Key 登录
也可以用 API Key 登录 Codex App、CLI 或 IDE Extension。在 OpenAI 控制台获取 API Key。
API Key 使用按标准 API 费率通过 OpenAI 平台账号计费。
需要 ChatGPT 积分的功能（如 Fast 模式）只有在 ChatGPT 登录时才可用。API Key 登录时使用标准 API 定价。
建议：程序化的 Codex CLI 工作流（例如 CI/CD 任务）推荐使用 API Key 认证。不要在不受信任或公开的环境中暴露 Codex 执行权限。
保护 Codex Cloud 账号
Codex Cloud 直接与你的代码库交互，需要比其他 ChatGPT 功能更强的安全性。建议启用多因素认证（MFA）。
如果你使用社交登录（Google、Microsoft、Apple），不强制要求在 ChatGPT 账号上启用 MFA，但可以在社交登录提供商那边设置：
如果通过 SSO 访问 ChatGPT，组织的 SSO 管理员应为所有用户强制 MFA。
如果用邮箱和密码登录，必须在账号上设置 MFA 才能访问 Codex Cloud。
如果账号支持多种登录方式且其中包含邮箱+密码，即使你平时用其他方式登录，也必须设置 MFA 才能使用 Codex。
登录缓存
用 ChatGPT 或 API Key 登录 Codex App、CLI 或 IDE Extension 后，Codex 会缓存登录信息，下次启动时自动复用。CLI 和 IDE 扩展共用同一份缓存。从任意一端退出后，下次需要重新登录。
Codex 将登录信息以明文缓存在 ~/.codex/auth.json 或操作系统的凭据存储中。
对于 ChatGPT session，Codex 在过期前自动刷新 token，活跃 session 通常不需要再次浏览器登录。
凭据存储
用 cli_auth_credentials_store 控制 Codex CLI 缓存凭据的位置：
toml
# file | keyring | auto
cli_auth_credentials_store = "keyring"file：把凭据存在CODEX_HOME（默认~/.codex）下的auth.jsonkeyring：存在操作系统凭据存储中auto：优先用操作系统凭据存储，不可用时回退到auth.json
使用文件存储时，请像对待密码一样保护 ~/.codex/auth.json——它包含访问 token。不要提交到 git、粘贴到工单或在聊天中分享。
强制限定登录方式或工作区
在受管环境中，管理员可以限制用户的认证方式：
toml
# 只允许 ChatGPT 登录或只允许 API Key 登录
forced_login_method = "chatgpt" # 或 "api"
# ChatGPT 登录时，限制到特定工作区
forced_chatgpt_workspace_id = "00000000-0000-0000-0000-000000000000"如果当前凭据不符合配置的限制，Codex 会让用户退出并退出程序。
这些设置通常通过 受管配置 下发，而不是逐用户配置。
登录诊断
codex login 命令运行时会在配置的日志目录下生成专用的 codex-login.log 文件。调试浏览器登录或 device code 登录失败时，或 support 要求提供日志时，使用该文件。
自定义 CA 证书
如果网络使用了企业 TLS 代理或私有根 CA，在登录前设置 CODEX_CA_CERTIFICATE 指向 PEM 证书包。未设置 CODEX_CA_CERTIFICATE 时，Codex 回退到 SSL_CERT_FILE。自定义 CA 设置对登录、HTTPS 请求和 WebSocket 连接都生效。
shell
export CODEX_CA_CERTIFICATE=/path/to/corporate-root-ca.pem
codex login无头/远程设备登录
在以下情况下，标准浏览器登录可能无法正常工作：
- 在远程或无头环境中运行 CLI
- 本地网络配置阻止了 Codex 用于接收 OAuth token 的 localhost 回调
这些情况下，优先使用设备码认证（beta）。
首选：设备码认证（beta）
- 在 ChatGPT 安全设置（个人账号）或 ChatGPT 工作区权限（工作区管理员）中启用设备码登录
- 在运行 Codex 的终端中，选择以下任一方式：
- 在交互式登录界面选择 Sign in with Device Code
- 直接运行
codex login --device-auth
- 在浏览器中打开链接，登录后输入一次性代码
如果服务器未启用设备码登录，Codex 回退到标准浏览器登录流程。
回退方案：本地登录后复制认证缓存
如果可以在有浏览器的机器上完成登录，可以将缓存凭据复制到无头机器：
- 在有浏览器的机器上运行
codex login - 确认
~/.codex/auth.json存在 - 将
~/.codex/auth.json复制到目标机器的同一路径
警告：
auth.json包含访问 token，请像密码一样保护它。不要提交到 git、粘贴到工单或在聊天中分享。
通过 SSH 复制到远程机器：
shell
ssh user@remote 'mkdir -p ~/.codex'
scp ~/.codex/auth.json user@remote:~/.codex/auth.json复制到 Docker 容器：
shell
CONTAINER_HOME=$(docker exec MY_CONTAINER printenv HOME)
docker exec MY_CONTAINER mkdir -p "$CONTAINER_HOME/.codex"
docker cp ~/.codex/auth.json MY_CONTAINER:"$CONTAINER_HOME/.codex/auth.json"回退方案：通过 SSH 转发 localhost 回调
如果可以在本地机器和远程主机之间转发端口，可以通过隧道使用标准浏览器登录流程（Codex 默认使用 localhost:1455）：
- 在本地机器上启动端口转发：
shell
ssh -L 1455:localhost:1455 user@remote- 在 SSH 会话中运行
codex login，按提示在本地浏览器中操作
自定义 Model Provider 认证
定义自定义 model provider 时，可选以下认证方式：
- OpenAI 认证：设置
requires_openai_auth = true，使用 OpenAI 认证（ChatGPT 或 API Key 均可）。适合通过 LLM 代理服务器访问 OpenAI 模型时使用。设置后env_key会被忽略。 - 环境变量认证：设置
env_key = "<ENV_VARIABLE_NAME>"，从指定环境变量读取 provider 专用 API Key。 - 无认证：不设置
requires_openai_auth（或设为false）且不设置env_key时，Codex 假定该 provider 不需要认证。适合本地模型。
常见问题
Q: ChatGPT 登录和 API Key 登录该怎么选？
A: 个人日常使用选 ChatGPT 登录，可以用到 Fast 模式积分和云端功能；CI/CD 自动化脚本选 API Key，更方便密钥轮换和权限控制，不会消耗个人积分配额。
Q: auth.json 丢了或过期了怎么办？
A: 重新运行 codex login 即可。ChatGPT session 在活跃使用期间会自动刷新，一般不会无故过期。
Q: 企业环境里用设备码认证需要管理员操作吗？
A: 需要。ChatGPT 工作区管理员要在工作区权限页面开启"Enable device code authentication for Codex CLI"开关，用户才能使用 codex login --device-auth。