跳到主要内容

本文为非官方中文翻译，内容以 OpenAI 官方英文文档为准。
官方来源：https://developers.openai.com/codex/auth

身份验证

Codex 的登录方式

OpenAI 身份验证​

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

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

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

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

  • 使用 ChatGPT 登录时，Codex 的使用遵循你的 ChatGPT 工作区权限、RBAC，以及 ChatGPT Enterprise 保留和数据驻留设置
  • 使用 API key 时，使用情况则遵循你的 API organization 的保留和数据共享设置

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

使用 ChatGPT 登录​

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

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

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

使用 API key 登录​

你也可以使用 API key 登录 Codex 应用、CLI 或 IDE 扩展。可从 OpenAI dashboard 获取你的 API key。

OpenAI 会通过你的 OpenAI Platform 账户按标准 API 费率为 API key 的使用计费。请参见 API pricing page。

依赖 ChatGPT credits 的功能（例如 fast mode）仅在你使用 ChatGPT 登录时可用。如果你使用 API key 登录，Codex 将改为使用标准 API 定价。

我们建议将 API key 身份验证用于程序化的 Codex CLI 工作流，例如 CI/CD 作业。不要在不受信任或公开的环境中暴露 Codex 执行。

在企业自动化中使用 Codex 访问令牌​

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

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

有关设置步骤、权限、轮换和吊销的说明，请参阅 Access tokens。

保护你的 Codex cloud 账户​

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

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

有关设置说明，请参见：

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

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

如果你的账户支持多种登录方式，且其中一种是电子邮件和密码，那么你在访问 Codex 之前必须设置 MFA，即使你使用的是另一种登录方式。

登录缓存​

当你使用 ChatGPT 或 API key 登录 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 下的 auth.json 中（默认为 ~/.codex）。
  • keyring 将凭据存储在操作系统的凭据存储中。
  • auto 会在可用时使用操作系统凭据存储，否则回退到 auth.json。

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

强制指定登录方式或工作区​

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

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

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

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

这些设置通常通过受管配置来应用，而不是由每个用户单独设置。请参见 Managed configuration。

登录诊断​

直接运行 codex login 时，会在你配置的日志目录下写入一个专用的 codex-login.log 文件。当你需要调试浏览器登录或 device code 失败问题，或者支持团队要求提供与登录相关的日志时，可使用该文件。

自定义 CA bundles​

如果你的网络使用企业 TLS 代理或私有根 CA，请在登录前将 CODEX_CA_CERTIFICATE 设置为一个 PEM bundle。当未设置 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，在某些情况下，基于浏览器的登录 UI 可能无法工作：

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

在这些情况下，优先使用 device code 身份验证（beta）。在交互式登录 UI 中，选择 Sign in with Device Code，或直接运行 codex login --device-auth。如果 device code 身份验证在你的环境中不可用，请使用其中一种后备方法。

首选：device code 身份验证（beta）​

  1. 在你的 ChatGPT 安全设置（个人账户）或 ChatGPT 工作区权限（工作区管理员）中启用 device code 登录。
  2. 在你运行 Codex 的终端中，选择以下其中一种方式：
    • 在交互式登录 UI 中，选择 Sign in with Device Code。
    • 运行 codex login --device-auth。
  3. 在浏览器中打开链接，登录，然后输入一次性代码。

如果服务器未启用 device code 登录，Codex 会回退到标准的基于浏览器的登录流程。

后备方案：在本地完成身份验证并复制你的 auth cache​

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

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

像对待密码一样对待 ~/.codex/auth.json：它包含访问令牌。不要提交它，不要把它粘贴到工单里，也不要在聊天中分享它。

如果你的操作系统将凭据存储在凭据存储中而不是 ~/.codex/auth.json，则此方法可能不适用。有关如何配置基于文件的存储，请参见 Credential storage。

通过 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 runner 上的更高级版本，请参见 Maintain Codex account auth in CI/CD (advanced)。该指南说明了如何让 Codex 在正常运行期间刷新 auth.json，然后为下一次作业保留更新后的文件。对于自动化，默认仍然推荐使用 API keys。

回退方案：通过 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 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 会假定该提供方不需要认证。这对于本地模型很有用。