OpenAI Codex 中文文档（4.14更新）
联系我 ↗
官方文档 ↗

认证

了解 Codex 的登录方式、凭据缓存和企业环境下的认证限制。

OpenAI 认证

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

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

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

你使用哪种登录方式，也决定了适用哪些管理员控制项和数据处理策略：

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

对于 CLI，如果当前没有可用的有效会话，默认认证路径是 Sign in with ChatGPT。

使用 ChatGPT 登录

当你在 Codex App、CLI 或 IDE 扩展中通过 ChatGPT 登录时，Codex 会打开一个浏览器窗口让你完成登录流程。登录后，浏览器会把访问令牌返回给 CLI 或 IDE 扩展。

使用 API key 登录

你也可以在 Codex App、CLI 或 IDE 扩展中通过 API key 登录。API key 可从 OpenAI 控制台 获取。

OpenAI 会按照标准 API 价格通过你的 OpenAI Platform 账户为 API key 使用量计费。详情请参见 API 定价。

依赖 ChatGPT credits 的功能，例如快速模式，只有在你使用 ChatGPT 登录时才可用。如果你使用 API key 登录，Codex 将按标准 API 价格计费。

对于程序化的 Codex CLI 工作流，例如 CI/CD 任务，推荐使用 API key 认证。不要把 Codex 的执行暴露在不受信任或公开的环境中。

保护你的 Codex 云端账户

Codex 云端会直接与你的代码库交互，因此它对账户安全性的要求高于许多其他 ChatGPT 功能。请启用多因素认证（MFA）。

如果你使用社交登录提供方，例如 Google、Microsoft 或 Apple，你不一定需要在 ChatGPT 账户中单独开启 MFA，但仍然可以在对应登录提供方中完成配置。

设置说明请参见：

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

如果你使用邮箱和密码登录，那么在访问 Codex 云端前，必须先为该账户设置 MFA。

如果你的账户支持多种登录方式，而其中一种是邮箱加密码，那么即便你实际使用的是另一种登录方式，也必须先设置 MFA，才能访问 Codex。

登录缓存

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

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

对于 ChatGPT 登录会话，Codex 会在 token 过期前自动刷新，因此处于活跃状态的会话通常无需再次打开浏览器重新登录。

凭据存储

你可以使用 cli_auth_credentials_store 来控制 Codex CLI 将缓存凭据存储到哪里：

# file | keyring | auto
cli_auth_credentials_store = "keyring"
  • file：把凭据存到 CODEX_HOME 下的 auth.json 中，默认通常是 ~/.codex
  • keyring：把凭据存到操作系统凭据存储中
  • auto：如果系统支持就使用操作系统凭据存储，否则回退到 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 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 在登录后通过 localhost 回调把 OAuth token 返回给 CLI

在这些情况下，应优先使用设备码（device code）认证（Beta）。你可以在交互式登录界面中选择 Sign in with Device Code，或者直接运行 codex login --device-auth。如果设备码认证在你的环境中不可用，再使用后面的备用方式。

首选：设备码（device code）认证（Beta）

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

如果服务端未启用设备码登录，Codex 会回退到标准浏览器登录流程。

备选：在本地完成认证并复制认证缓存

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

  1. 在能使用浏览器登录流程的机器上运行 codex login
  2. 确认登录缓存位于 ~/.codex/auth.json
  3. 把 ~/.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 runner 上实现这个模式的更高级版本，请参见官方文档 Maintain Codex account auth in CI/CD (advanced)。那份指南解释了如何在正常运行期间让 Codex 刷新 auth.json，并把更新后的文件保留给下一次任务使用。但对于自动化场景，默认仍然推荐 API key。

备选：通过 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 proxy 访问 OpenAI 模型的场景。当 requires_openai_auth = true 时，Codex 会忽略 env_key。
  • 环境变量认证：设置 env_key = "<ENV_VARIABLE_NAME>"，让 Codex 从名为 <ENV_VARIABLE_NAME> 的本地环境变量中读取该提供方的 API key。
  • 不使用认证：如果你既不设置 requires_openai_auth（或显式将其设为 false），也不设置 env_key，Codex 就会假定该提供方无需认证。这适合本地模型。

来源：https://developers.openai.com/codex/auth