认证

Codex 的登录方式

认证

Codex 的登录方式。

OpenAI 认证

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

使用 ChatGPT 账号登录，享受订阅权益
使用 API 密钥登录，按用量计费

Codex Cloud 要求使用 ChatGPT 登录。Codex CLI 和 IDE 扩展同时支持两种登录方式。

你的登录方式也决定了适用的管理员控制策略和数据处理策略：

使用 ChatGPT 登录时，Codex 的使用遵循你所在的 ChatGPT 工作区权限、RBAC 以及 ChatGPT Enterprise 数据保留和驻留设置
使用 API 密钥时，使用行为遵循你 API 组织的数据保留和共享设置

对于 CLI，当没有有效会话时，默认的身份验证路径是 使用 ChatGPT 登录。

使用 ChatGPT 登录

当你从 Codex 桌面应用、CLI 或 IDE 扩展中选择”使用 ChatGPT 登录”时，Codex 会打开一个浏览器窗口来完成登录流程。登录后，浏览器会将访问令牌返回给 CLI 或 IDE 扩展。

如果你的环境已经提供了 ChatGPT 访问令牌，CLI 可以通过 stdin 读取它：

printenv CODEX_ACCESS_TOKEN | codex login --with-access-token

使用 API 密钥登录

你也可以使用 API 密钥登录 Codex 桌面应用、CLI 或 IDE 扩展。请从 OpenAI 仪表板获取你的 API 密钥。

OpenAI 通过你的 OpenAI Platform 账户按标准 API 费率对 API 密钥使用量进行计费。请参阅 API 定价页面。

依赖 ChatGPT 积分的功能（例如快速模式）仅在使用 ChatGPT 登录时可用。如果使用 API 密钥登录，Codex 将改为使用标准 API 定价。

对于程序化的 Codex CLI 工作流（例如 CI/CD 任务），我们推荐使用 API 密钥认证。避免在不受信任或公共环境中暴露 Codex 执行。

使用 Codex 访问令牌进行企业自动化

在 ChatGPT Enterprise 工作区中，管理员可以允许授权成员创建 Codex 访问令牌，用于受信任的非交互式 Codex 本地工作流。当自动化需要 ChatGPT 工作区访问权限、ChatGPT 管理的 Codex 权益或企业工作区控制，但又不需要浏览器登录时，应使用访问令牌。

访问令牌适用于受信任的脚本、调度器和私有 CI 运行器。对于一般的 OpenAI API 调用，请继续使用 Platform API 密钥。

有关设置步骤、权限、轮换和撤销指导，请参阅访问令牌。

保护你的 Codex Cloud 账户

Codex Cloud 会直接与你的代码库交互，因此它需要比许多其他 ChatGPT 功能更强的安全性。请启用多因素认证（MFA）。

如果你使用社交登录提供商（Google、Microsoft、Apple），不需要在 ChatGPT 账户上强制启用 MFA，但可以在你的社交登录提供商处设置 MFA。

设置说明请参阅：

如果你通过单点登录（SSO）访问 ChatGPT，你所在组织的 SSO 管理员应对所有用户强制执行 MFA。

如果你使用邮箱和密码登录，则必须在访问 Codex Cloud 之前在账户上设置 MFA。

如果你的账户支持多种登录方式，且其中一种是邮箱和密码，则即使你通过其他方式登录，也必须在访问 Codex 之前设置 MFA。

登录缓存

当你使用 ChatGPT 或 API 密钥登录 Codex 桌面应用、CLI 或 IDE 扩展时，Codex 会缓存你的登录信息，并在下次启动 CLI 或扩展时重用。CLI 和扩展共享相同的缓存登录信息。如果你从其中任何一个退出登录，下次启动 CLI 或扩展时需要重新登录。

Codex 将登录信息缓存在本地的明文文件 ~/.codex/auth.json 中，或存储在你的操作系统凭据存储中。

对于使用 ChatGPT 登录的会话，Codex 会在使用过程中自动刷新令牌（在令牌过期之前），因此活跃会话通常无需再次进行浏览器登录。

凭据存储

使用 cli_auth_credentials_store 来控制 Codex CLI 存储缓存凭据的位置：

# file | keyring | auto
cli_auth_credentials_store = "keyring"

file — 将凭据存储在 CODEX_HOME（默认为 ~/.codex）下的 auth.json 中
keyring — 将凭据存储在操作系统凭据存储中
auto — 当操作系统凭据存储可用时使用它，否则回退到 auth.json

如果你使用基于文件的存储，请像对待密码一样对待 ~/.codex/auth.json：它包含访问令牌。不要将其提交到版本控制、粘贴到工单中或在聊天中分享。

强制登录方式或工作区

在托管环境中，管理员可以限制用户的认证方式：

# 仅允许 ChatGPT 登录或仅允许 API 密钥登录。
forced_login_method = "chatgpt" # 或 "api"

# 使用 ChatGPT 登录时，限制用户只能使用特定工作区。
forced_chatgpt_workspace_id = "00000000-0000-0000-0000-000000000000"

如果当前凭据不匹配配置的限制，Codex 会登出用户并退出。

这些设置通常通过托管配置应用，而不是按用户设置。请参阅托管配置。

登录诊断

直接的 codex login 运行会在你配置的日志目录下写入一个专门的 codex-login.log 文件。当你需要调试浏览器登录或设备代码登录失败，或者支持人员要求提供登录专用日志时，可以使用它。

自定义 CA 证书包

如果你的网络使用企业 TLS 代理或私有根 CA，请在登录前将 CODEX_CA_CERTIFICATE 设置为 PEM 证书包。当 CODEX_CA_CERTIFICATE 未设置时，Codex 会回退使用 SSL_CERT_FILE。相同的自定义 CA 设置适用于登录、普通 HTTPS 请求和安全 WebSocket 连接。

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

在无头设备上登录

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

你正在远程或无头环境中运行 CLI
你的本地网络配置阻止了 Codex 用于在登录后将 OAuth 令牌返回给 CLI 的 localhost 回调

在这些情况下，优先使用设备代码认证（Beta）。在交互式登录界面中，选择 使用设备代码登录，或直接运行 codex login --device-auth。如果设备代码认证在你的环境中不适用，请使用以下备用方法。

备用方案：在本地认证并复制认证缓存

如果你可以在有浏览器的机器上完成登录流程，则可以将缓存的凭据复制到无头机器上。

在可以使用浏览器登录流程的机器上，运行 codex login
确认登录缓存存在于 ~/.codex/auth.json
将 ~/.codex/auth.json 复制到无头机器的 ~/.codex/auth.json

⚠️ 请像对待密码一样对待 ~/.codex/auth.json：它包含访问令牌。不要将其提交到版本控制、粘贴到工单中或在聊天中分享。

如果你的操作系统将凭据存储在凭据存储中而不是 ~/.codex/auth.json，此方法可能不适用。请参阅凭据存储了解如何配置文件存储。

通过 SSH 复制到远程机器：

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

或使用避免 scp 的单行命令：

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

复制到 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 运行器上使用此模式的更高级版本，请参阅在 CI/CD 中维护 Codex 账户认证（高级）。该指南解释了如何让 Codex 在正常运行时刷新 auth.json，然后为下一个作业保留更新后的文件。对于自动化场景，API 密钥仍然是推荐的默认选项。

备用方案：通过 SSH 转发 localhost 回调

如果你可以在本地机器和远程主机之间转发端口，则可以通过隧道传输 Codex 的本地回调服务器（默认为 localhost:1455）来使用标准的基于浏览器的流程。

从你的本地机器启动端口转发：

ssh -L 1455:localhost:1455 user@remote

在该 SSH 会话中，运行 codex login 并在你的本地机器上按照打印的地址操作。

替代模型提供商

在配置文件中定义自定义模型提供商时，你可以选择以下认证方式之一：

OpenAI 认证：设置 requires_openai_auth = true 以使用 OpenAI 认证。然后你可以使用 ChatGPT 或 API 密钥登录。当你通过 LLM 代理服务器访问 OpenAI 模型时，这非常有用。当 requires_openai_auth = true 时，Codex 会忽略 env_key。
环境变量认证：设置 env_key = "<ENV_VARIABLE_NAME>"，以使用本地环境变量 <ENV_VARIABLE_NAME> 中提供的提供商特定 API 密钥。
无认证：如果你不设置 requires_openai_auth（或将其设为 false）且不设置 env_key，Codex 会假定该提供商不需要认证。这对于本地模型非常有用。

Concepts

App 桌面应用

IDE 扩展

CLI

Web 云端

集成

Codex Security

Plugins 插件

Skills 技能

Enterprise

认证

认证