身份验证

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

• 使用 ChatGPT 登录，以获得订阅访问权限
• 使用 API key 登录，以按用量访问

ChatGPT 桌面应用、Codex CLI 和 IDE 扩展均支持使用这两种登录 方式开展本地工作。Codex cloud 要求使用 ChatGPT 登录。

你的登录方式还决定了适用的管理控制和数据处理政策。

• 使用 ChatGPT 登录时，Codex 的使用遵循你的 ChatGPT 工作区 权限、基于角色的访问控制 (RBAC)，以及 ChatGPT Enterprise 的 数据保留和驻留设置。
• 使用 API key 时，用量则遵循你的 API 组织的数据保留和 数据共享设置。

对于托管工作区，身份验证只是访问控制的一层。工作区 成员资格和预配决定谁可以登录，而席位和 工作区角色决定他们可以使用哪些产品界面和功能。 对于 ChatGPT 桌面应用、Codex CLI 或 IDE 扩展中的本地工作， 权限配置档案会约束智能体可以在设备上执行的操作。请参阅 组和预配 以及角色和工作区权限， 以规划这些控制。

使用 ChatGPT 登录

要在桌面端、移动端和网页端使用 Work Cloud 的本地计算机访问功能：

1. 使用 ChatGPT 登录符合条件的工作区。

2. 请工作区所有者启用 Work Cloud，然后在 Work Cloud 下开启允许访问本地计算机。在 ChatGPT 桌面应用上本地使用 Codex 不是前提条件。

API key 和 Codex 访问令牌无法启用 Work Cloud 的本地计算机访问功能。有关前提条件，请参阅角色和工作区权限及 Work 管理员常见问题；有关设置方法，请参阅 Work Cloud 和 dots 的本地计算机访问。

从 ChatGPT 桌面应用、Codex CLI 或 IDE 扩展使用 ChatGPT 登录时，登录流程会打开浏览器窗口。登录后，浏览器会将你的凭据返回给 Codex。

ChatGPT 网页版

打开 ChatGPT，登录并选择你希望 使用的工作区。ChatGPT 网页版会在浏览器中保留已认证的会话。

ChatGPT 桌面应用

在已退出登录的界面上，选择 继续登录（Continue to sign in），然后完成 浏览器流程。

Codex CLI

运行 codex login，然后完成浏览器中的流程。这是在没有有效会话时 使用的默认认证方式。

IDE 扩展

在未登录界面上，选择使用 ChatGPT 登录，然后完成 浏览器中的流程。

使用 API key 登录

你也可以使用 API key 登录 ChatGPT 桌面应用、Codex CLI 或 IDE 扩展。从 OpenAI 控制面板获取 API key。

ChatGPT 桌面应用

在已退出登录的界面上，选择 使用其他方式登录（Sign in another way），输入密钥，然后 选择 继续（Continue）。

Codex CLI

通过 stdin 将密钥以管道方式传入 codex login：

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

IDE 扩展

在未登录界面上，选择 使用 API key，输入你的密钥，然后选择 确定。

OpenAI 会通过你的 OpenAI Platform 账号按标准 API 费率对 API key 用量计费。请参阅 API 定价页面。

API key 身份验证支持本地 Codex 工作流，但部分依赖 ChatGPT 工作区访问权限或云服务的功能会受限或不可用。 请在 功能可用性中比较不同套餐支持的功能。

在 Codex CLI 和 ChatGPT 桌面应用中的 Codex 中，使用 API key 进行身份验证 即可访问受支持的 OpenAI 精选插件。部分插件 不可用，因为其连接流程需要尚不支持的 OAuth 功能。参阅使用插件。

使用 API key 登录时，Codex 采用标准 API 定价，而不使用 ChatGPT 套餐内含的额度。

请将 API key 身份验证用于编程式 Codex CLI 工作流，例如 CI/CD 作业。请勿在不受信任或公开的环境中开放 Codex 执行能力。

打开个人资料菜单，确认当前账户和工作区。要结束该浏览器中的 ChatGPT 网页会话，请选择 退出登录。

打开个人资料菜单，查看当前账号或 API key 状态。选择 退出登录（Log out） 以清除当前凭据。

运行 codex login status，查看当前身份验证方式。对于已存储的 身份验证凭据，运行 codex logout 可清除当前凭据。当 进程选择工作负载身份时，Codex 会拒绝 codex login 和 codex logout，因为身份验证由进程环境控制。

打开个人资料菜单，查看当前账户或 API key 状态。选择 退出登录，清除当前凭据。

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

在 ChatGPT Enterprise 工作区中，管理员可以授予访问令牌 权限，使获准的成员能够为受信任的 非交互式 Codex 本地工作流创建 Codex 访问令牌。当自动化 需要 ChatGPT 工作区访问权限、由 ChatGPT 管理的 Codex 权益，或 无需浏览器登录即可应用企业工作区控制时，请使用访问令牌。

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

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

如果你的环境已提供 Codex 访问令牌，请通过管道将其传给 CLI：

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

保护你的 Codex cloud 账号

Codex cloud 会直接与你的代码库交互，因此它需要比许多其他 ChatGPT 功能更强的安全保护。请启用多重身份验证 (MFA)。

如果你使用社交登录提供商（Google、Microsoft、Apple），则无需在 ChatGPT 账号上启用 MFA，但可以通过社交登录提供商进行设置。

有关设置说明，请参阅：

• Google
• Microsoft
• Apple

如果你通过单点登录 (SSO) 访问 ChatGPT，你所在组织的 SSO 管理员应为所有用户强制启用 MFA。

如果你使用电子邮件和密码登录，则必须先在账号上设置 MFA，才能访问 Codex cloud。

如果你的账号支持多种登录方式，且其中一种是电子邮件和密码，则必须先设置 MFA 才能访问 Codex，即使你使用其他方式登录也是如此。

登录缓存

无论使用 ChatGPT 还是 API key 登录 ChatGPT 桌面应用、Codex CLI 或 IDE 扩展，登录信息都会被缓存并复用。CLI 和扩展共享同一份缓存的登录信息。如果从其中任一端退出登录，则下次启动 CLI 或扩展时需要重新登录。

Codex 会将登录信息以明文文件形式缓存在本地的 ~/.codex/auth.json 中，或存入操作系统专用的凭据存储区。

对于使用 ChatGPT 登录的会话，Codex 会在令牌过期前于使用期间自动刷新令牌，因此活跃会话通常无需再次通过浏览器登录即可继续。

凭据存储

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

# file | keyring | auto | ephemeral
cli_auth_credentials_store = "keyring"

• file 将凭据存储在 auth.json 中，该文件位于 CODEX_HOME 下（默认为 ~/.codex）。
• keyring 将凭据存储在操作系统的凭据存储中，如果该存储不可用则失败。
• auto 在操作系统凭据存储可用时使用它，否则回退到 auth.json。
• ephemeral 仅在当前进程的内存中保留凭据。

有关完整的 config.toml 架构，请参阅配置参考。

管理员可以强制执行 cli_auth_credentials_store 和 chatgpt_base_url，具体通过 本地身份验证要求进行配置。 用户无法通过 config.toml 或 CLI 覆盖项来覆盖这些要求。

强制使用登录方式或工作区

在托管环境中，管理员可以限制允许用户采用的身份验证方式：

# Only allow ChatGPT login or only allow API key login.
forced_login_method = "chatgpt" # or "api"

# When using ChatGPT login, restrict users to a specific workspace.
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。
• 你的本地网络配置阻止了 localhost 回调，Codex 使用该回调在你登录后将 OAuth 令牌返回给 CLI。

在这些情况下，优先使用设备码身份验证（测试版）。在交互式登录界面中，选择 使用设备码登录，或直接运行 codex login --device-auth。如果设备码身份验证在你的环境中无法正常工作，请使用一种备用方法。

首选：设备码身份验证（测试版）

1. 在 ChatGPT 安全设置（个人账户）或 ChatGPT 工作区权限（工作区管理员）中启用设备码登录。
2. 在运行 Codex 的终端中，选择以下任一选项：
   • 在交互式登录界面中，选择 使用设备码登录。
   • 运行 codex login --device-auth。
3. 在浏览器中打开链接，登录，然后输入一次性验证码。

如果你的环境无法使用设备码登录，请使用下方的一种 备用方法。

备用方法：在本地完成身份验证并复制身份验证缓存

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

1. 在可以使用浏览器登录流程的机器上，运行 codex login。
2. 确认登录缓存位于 ~/.codex/auth.json。
3. 将 ~/.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 容器中：

# Replace MY_CONTAINER with the name or ID of your container.
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 key。

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

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

1. 在本地机器上启动端口转发：

ssh -L 1455:localhost:1455 user@remote

2. 在该 SSH 会话中，运行 codex login，然后在本地机器上打开输出的地址。

其他模型提供商

在配置文件中定义自定义模型提供商时，可以选择以下任一种身份验证方式：

• OpenAI 身份验证：设置 requires_openai_auth = true 以使用 OpenAI 身份验证。随后可以使用 ChatGPT 或 API key 登录。通过 LLM 代理服务器访问 OpenAI 模型时，这种方式非常实用。当 requires_openai_auth = true 时，Codex 会忽略 env_key。
• 环境变量身份验证：设置 env_key = "<ENV_VARIABLE_NAME>"，以使用名称为 <ENV_VARIABLE_NAME> 的本地环境变量中提供商专用的 API key。
• 无身份验证：如果未设置 requires_openai_auth（或将其设置为 false），并且也未设置 env_key，Codex 会假定该提供商不需要身份验证。这适用于本地模型。