English
主导航

推荐
API 仪表板

身份验证

Codex 登录方式

OpenAI 身份验证

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

  • 使用 ChatGPT 登录以获取订阅访问权限
  • 使用 API 密钥登录以获取按用量计费的访问权限

Codex 云端版需要使用 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 平台账户按标准 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 调用，请继续使用平台 API 密钥。

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

保护你的 Codex 云端版账户

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

如果你使用社交登录服务提供商 (Google、Microsoft、Apple)，则无需在你的 ChatGPT 账户上启用 MFA，但你可以在你的社交登录服务提供商处进行设置。

For setup instructions, see:

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

如果你使用邮箱和密码登录，则必须在访问 Codex 云端版之前在账户上设置 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 将凭据存储在 auth.json 下 CODEX_HOME (默认为 ~/.codex).
  • keyring 将凭据存储在操作系统的凭据存储中。
  • auto 在可用时使用操作系统凭据存储，否则回退到 auth.json.

如果你使用基于文件的存储，请将 ~/.codex/auth.json 视为密码：它包含访问令牌。请勿提交它、将其粘贴到工单中或在聊天中分享。

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

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

# 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。
  • 你的本地网络配置阻止了 Codex 用于在你登录后将 OAuth token 返回给 CLI 的 localhost 回调。

在这些情况下，建议使用设备代码身份验证（beta）。在交互式登录界面中，选择 使用设备代码登录，或者运行 codex login --device-auth 。如果设备代码身份验证在你的环境中不起作用，请使用备选方法之一。

首选：设备代码身份验证（beta）

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

如果服务器未启用设备代码登录，Codex 将回退到标准的基于浏览器的登录流程。

回退方案：在本地完成身份验证并复制身份验证缓存

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

  1. 在可以使用基于浏览器的登录流程的机器上，运行 codex login.
  2. 确认登录缓存存在于 ~/.codex/auth.json.
  3. 复制 ~/.codex/auth.json to ~/.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 密钥。

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

如果你可以在本地机器和远程主机之间转发端口，则可以通过隧道传输 Codex 的本地回调服务器（默认 localhost:1455).

  1. 从本地机器启动端口转发：
ssh -L 1455:localhost:1455 user@remote
  1. 在该 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>" 以使用本地环境变量中特定于提供商的 API 密钥，该环境变量名为 <ENV_VARIABLE_NAME>.
  • 无身份验证: 如果您未设置 requires_openai_auth （或将其设置为 false）并且你没有设置 env_key, Codex 将假定该提供程序不需要身份验证。这对于本地模型很有用。