完成登录和认证

OpenAI 认证

使用 OpenAI 模型时，Codex 支持两种登录方式：

使用 ChatGPT 登录，走订阅权益。
使用 API key 登录，走按量计费。

Codex cloud（云端 Codex）必须使用 ChatGPT 登录。Codex CLI 和 IDE extension 同时支持这两种登录方式。

你选择的登录方式，也会决定适用哪些管理员控制项和数据处理策略。

使用 ChatGPT 登录时，Codex 的使用会遵循你的 ChatGPT workspace permissions（工作区权限）、RBAC（基于角色的访问控制），以及 ChatGPT Enterprise 的 retention（保留）和 residency（数据驻留）设置。
使用 API key 登录时，Codex 的使用会改为遵循你的 API organization（API 组织）的 retention 和 data-sharing（数据共享）设置。

在 CLI 里，如果当前没有可用会话，默认认证路径是 Sign in with ChatGPT（使用 ChatGPT 登录）。

使用 ChatGPT 登录

当你从 Codex app、CLI 或 IDE Extension 使用 ChatGPT 登录时，Codex 会打开浏览器窗口，让你完成登录流程。

登录完成后，浏览器会把 access token（访问令牌）返回给 CLI 或 IDE extension。

使用 API key 登录

你也可以使用 API key 登录 Codex app、CLI 或 IDE Extension。API key 可以从 OpenAI dashboard 获取：

https://platform.openai.com/api-keys

使用 API key 产生的费用，会通过你的 OpenAI Platform 账号按标准 API 价格计费。价格见 API pricing page：

https://openai.com/api/pricing/

依赖 ChatGPT credits（ChatGPT 额度）的功能，例如 fast mode（快速模式），只有在使用 ChatGPT 登录时才可用：

https://developers.openai.com/codex/speed

如果你使用 API key 登录，Codex 会改用标准 API 价格。

官方建议：程序化的 Codex CLI 工作流，例如 CI/CD jobs（持续集成 / 持续交付任务），更适合使用 API key 认证。不要把 Codex 执行能力暴露在不可信或公开环境里。

保护你的 Codex cloud 账号

Codex cloud 会直接和你的代码库交互，因此它需要比许多其他 ChatGPT 功能更强的安全保护。请启用 multi-factor authentication（MFA，多因素认证）。

如果你使用社交登录提供商，例如 Google、Microsoft 或 Apple，你不一定需要在 ChatGPT 账号里单独启用 MFA，但可以在对应社交登录提供商那里设置 MFA。

设置说明：

如果你通过 single sign-on（SSO，单点登录）访问 ChatGPT，你所在组织的 SSO 管理员应该为所有用户强制启用 MFA。

如果你使用邮箱和密码登录，在访问 Codex cloud 之前，必须先为账号设置 MFA。

如果你的账号支持多种登录方式，并且其中一种是邮箱和密码，那么即使你平时用其他方式登录，也必须在访问 Codex 前设置 MFA。

登录缓存

当你用 ChatGPT 或 API key 登录 Codex app、CLI 或 IDE Extension 时，Codex 会缓存你的登录信息，并在下次启动 CLI 或扩展时复用。

CLI 和 extension 共享同一份缓存登录信息。如果你从其中任意一个退出登录，下次启动 CLI 或 extension 时都需要重新登录。

Codex 会把登录信息缓存在本地明文文件 ~/.codex/auth.json，或者保存在操作系统专用的 credential store（凭据存储）里。

对于使用 ChatGPT 登录的会话，Codex 会在使用过程中自动刷新 token（令牌），避免 token 过期。因此活跃会话通常不需要再次打开浏览器登录。

凭据存储

使用 cli_auth_credentials_store 可以控制 Codex CLI 把缓存凭据存放在哪里：

# file | keyring | auto
cli_auth_credentials_store = "keyring"

file：把凭据存储在 CODEX_HOME 下的 auth.json 文件里。CODEX_HOME 默认是 ~/.codex。
keyring：把凭据存储在操作系统的 credential store 里。
auto：如果操作系统 credential store 可用，就使用它；否则回退到 auth.json。

如果你使用文件存储，请把 ~/.codex/auth.json 当作密码处理：它包含 access tokens。不要提交到 Git，不要贴进工单，也不要发到聊天里。

强制登录方式或 workspace

在受管理环境里，管理员可以限制用户允许使用的认证方式：

# 只允许 ChatGPT 登录，或只允许 API key 登录。
forced_login_method = "chatgpt" # or "api"

# 使用 ChatGPT 登录时，把用户限制在指定 workspace。
forced_chatgpt_workspace_id = "00000000-0000-0000-0000-000000000000"

如果当前有效凭据不符合这些限制，Codex 会让用户退出登录并退出程序。

这些设置通常通过 managed configuration（托管配置）应用，而不是让每个用户自己配置。参考 Managed configuration：

https://developers.openai.com/codex/enterprise/managed-configuration

登录诊断

直接运行 codex login 时，Codex 会在你配置的日志目录下写入专用的 codex-login.log 文件。

当你需要调试 browser-login（浏览器登录）或 device-code（设备码）失败，或者支持团队要求你提供登录相关日志时，可以使用这个日志文件。

自定义 CA bundles

如果你的网络使用企业 TLS proxy（TLS 代理）或私有 root CA（根证书颁发机构），请在登录前把 CODEX_CA_CERTIFICATE 设置为 PEM bundle（PEM 证书包）。

如果没有设置 CODEX_CA_CERTIFICATE，Codex 会回退使用 SSL_CERT_FILE。

相同的自定义 CA 设置会用于登录、普通 HTTPS 请求和安全 websocket 连接。

`export` CODEX_CA_CERTIFICATE=/path/to/corporate-root-ca.pem
codex login

在 headless devices 上登录

如果你用 Codex CLI 登录 ChatGPT，有些情况下基于浏览器的登录界面可能无法使用：

你在远程环境或 headless environment（无图形界面环境）里运行 CLI。
你的本地网络配置阻止了 localhost callback。本地回调是 Codex 在你完成登录后，把 OAuth token 返回给 CLI 的方式。

遇到这种情况，优先使用 device code authentication（设备码认证，beta）。在交互式登录界面里选择 Sign in with Device Code，或者直接运行：

codex login --device-auth

如果设备码认证在你的环境里不可用，再使用下面的兜底方法。

首选：Device code authentication（beta）

在你的 ChatGPT security settings（个人账号）或 ChatGPT workspace permissions（工作区管理员）里启用 device code login。
在运行 Codex 的终端里选择一种方式：
- 在交互式登录界面里选择 Sign in with Device Code。
- 运行 codex login --device-auth。
在浏览器里打开链接并登录，然后输入一次性代码。

如果服务器端没有启用 device code login，Codex 会回退到标准的浏览器登录流程。

兜底：本地认证后复制认证缓存

如果你可以在一台带浏览器的机器上完成登录流程，就可以把缓存凭据复制到 headless 机器上。

在能使用浏览器登录流程的机器上运行 codex login。
确认登录缓存存在于 ~/.codex/auth.json。
把 ~/.codex/auth.json 复制到 headless 机器上的 ~/.codex/auth.json。

请把 ~/.codex/auth.json 当作密码处理：它包含 access tokens。不要提交到 Git，不要贴进工单，也不要发到聊天里。

如果你的操作系统把凭据存储在 credential store 里，而不是 ~/.codex/auth.json 文件里，这种方法可能不适用。要配置文件存储方式，请看本篇前面的“凭据存储”。

通过 SSH 复制到远程机器：

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

也可以用一个不依赖 scp 的 one-liner（一行命令）：

ssh user@remote 'mkdir -p ~/.codex && cat > ~/.codex/auth.json' < ~/.codex/auth.json

复制到 Docker container（Docker 容器）里：

# 把 MY_CONTAINER 替换成容器名称或 ID。
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"

如果你要在可信的 CI/CD runners（CI/CD 运行器）上使用同一模式的高级版本，请参考：

https://developers.openai.com/codex/auth/ci-cd-auth

这篇指南解释了如何让 Codex 在正常运行过程中刷新 auth.json，并把更新后的文件保留下来供下一次 job 使用。即便如此，API keys 仍然是自动化场景下推荐的默认方式。

兜底：通过 SSH 转发 localhost callback

如果你可以在本机和远程主机之间转发端口，就可以通过隧道转发 Codex 的本地回调服务器，继续使用标准浏览器登录流程。默认回调地址是 localhost:1455。

从本机启动端口转发：

ssh -L 1455:localhost:1455 user@remote

在这个 SSH 会话里运行 codex login，然后在本机浏览器里打开终端打印出来的地址。

替代模型供应商

当你在配置文件里定义 custom model provider（自定义模型供应商）时，可以选择以下认证方式：

https://developers.openai.com/codex/config-advanced#custom-model-providers

OpenAI authentication（OpenAI 认证）：设置 requires_openai_auth = true，使用 OpenAI 认证。之后你可以用 ChatGPT 或 API key 登录。通过 LLM proxy server（大模型代理服务器）访问 OpenAI 模型时，这个方式很有用。当 requires_openai_auth = true 时，Codex 会忽略 env_key。
Environment variable authentication（环境变量认证）：设置 env_key = "<ENV_VARIABLE_NAME>"，使用本地环境变量 <ENV_VARIABLE_NAME> 中的供应商专用 API key。
No authentication（无认证）：如果不设置 requires_openai_auth，或把它设为 false，同时也不设置 env_key，Codex 会认为这个供应商不需要认证。这对本地模型很有用。

On this page