OpenAI Codex 的登录问题、API key 配置、无头环境认证失败和企业登录限制，通常都能在这里找到对应处理方式。CLI 和 IDE Extension 支持 ChatGPT 或 API key 登录；如遇浏览器回调失败，可改用设备码认证、复制 auth.json，或用 SSH 转发 localhost:1455 验证登录流程。

OpenAI Codex 身份认证与登录配置 #

OpenAI 认证方式 #

Codex 支持两种登录方式：

• Sign in with ChatGPT：使用 ChatGPT 订阅访问
• Sign in with an API key：按用量计费访问

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

登录方式也决定了哪些管理员控制和数据处理策略生效：

• 使用 ChatGPT 登录时，Codex 按 ChatGPT workspace 权限、RBAC，以及 ChatGPT Enterprise 的 retention 和 residency 设置执行
• 使用 API key 登录时，按 API organization 的 retention 和 data-sharing 设置执行

对 CLI 来说，如果没有有效 session，默认会走 ChatGPT 登录流程。

Sign in with ChatGPT #

从 Codex app、CLI 或 IDE Extension 使用 ChatGPT 登录时，Codex 会打开浏览器完成登录流程。登录后，浏览器会把 access token 返回给 CLI 或 IDE extension。

如果你的环境已经提供了 ChatGPT access token，CLI 可以从 stdin 读取：

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

Sign in with an API key #

你也可以使用 API key 登录 Codex app、CLI 或 IDE Extension。API key 可在 OpenAI dashboard 获取。

OpenAI 会按标准 API rates，通过你的 OpenAI Platform account 计费。参考 API pricing page。

依赖 ChatGPT credits 的功能，例如 fast mode，只有在 ChatGPT 登录时可用。使用 API key 登录时，Codex 会改用标准 API pricing。

对于程序化的 Codex CLI workflows，例如 CI/CD jobs，推荐使用 API key authentication。不要在不受信任或公开环境中暴露 Codex 执行。

用 Codex access tokens 做企业自动化 #

在 ChatGPT Enterprise workspace 中，管理员可以允许符合条件的成员创建 Codex access tokens，用于可信、非交互式的本地 Codex workflows。需要自动化同时保留 ChatGPT workspace access、ChatGPT-managed Codex entitlements，或 enterprise workspace controls 且不想走浏览器登录时，可以使用 access token。

Access token 适合可信脚本、调度器和私有 CI runners。一般的 OpenAI API 调用仍然继续使用 Platform API keys。

设置步骤、权限、轮换和吊销方式，请看 Access tokens。

如何保护 Codex cloud 账号 #

Codex cloud 会直接和你的 codebase 交互，因此安全要求比许多其他 ChatGPT 功能更高。请启用多因素认证（MFA）。

如果你使用社交登录提供商（Google、Microsoft、Apple），不强制要求在 ChatGPT 账号上启用 MFA，但你可以在社交登录提供商一侧配置：

• Google
• Microsoft
• Apple

如果你通过 single sign-on (SSO) 访问 ChatGPT，组织的 SSO administrator 应为所有用户强制 MFA。

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

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

登录缓存 #

使用 ChatGPT 或 API key 登录 Codex app、CLI 或 IDE Extension 后，Codex 会缓存登录信息，并在你下次启动 CLI 或 extension 时复用。CLI 和 extension 共用同一份缓存登录信息。如果你从任意一端退出，下一次启动 CLI 或 extension 时都需要重新登录。

Codex 会把登录信息本地缓存到明文文件 ~/.codex/auth.json，或者缓存到你的操作系统 credential store 中。

对于 ChatGPT sessions，Codex 会在 token 过期前自动刷新，因此活跃 session 通常不需要再次浏览器登录。

凭据存储 #

可以用 cli_auth_credentials_store 控制 Codex CLI 缓存凭据的位置：

# file | keyring | auto
cli_auth_credentials_store = "keyring"

• file：把凭据存到 CODEX_HOME 下的 auth.json，默认是 ~/.codex
• keyring：存到操作系统 credential store
• auto：优先使用操作系统 credential store，不可用时回退到 auth.json

如果使用 file-based storage，请把 ~/.codex/auth.json 当成密码处理，因为它包含 access tokens。不要提交它，不要贴到工单里，也不要在聊天中分享。

如何强制登录方式或 workspace #

在 managed environments 中，管理员可以限制用户允许的认证方式：

# 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 会让用户退出并退出程序。

这些设置通常通过 Managed configuration 下发，而不是按用户单独配置。

登录诊断 #

直接运行 codex login 时，Codex 会在你配置的日志目录下写入专用的 codex-login.log 文件。遇到 browser-login 或 device-code 失败，或者 support 要求提供登录日志时，可以查看这个文件。

自定义 CA bundles 怎么配置 #

如果你的网络使用 corporate TLS proxy 或 private root CA，可以在登录前设置 CODEX_CA_CERTIFICATE 指向 PEM bundle。未设置 CODEX_CA_CERTIFICATE 时，Codex 会回退到 SSL_CERT_FILE。这套自定义 CA 设置对登录、普通 HTTPS requests 和 secure WebSocket connections 都生效。

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

无头设备登录失败怎么解决 #

如果你使用 Codex CLI 登录 ChatGPT，下面两种情况可能会让 browser-based login UI 失效：

• 你在 remote 或 headless environment 中运行 CLI
• 本地网络配置阻止了 Codex 用来把 OAuth token 返回给 CLI 的 localhost callback

遇到这种情况，优先用 device code authentication（beta）。如果 device code authentication 在你的环境里也不可用，再用下面的 fallback 方法。

首选：Device code authentication（beta） #

1. 在 ChatGPT security settings（个人账号）或 ChatGPT workspace permissions（workspace admin）中启用 device code login。
2. 在运行 Codex 的终端中，选择以下任一方式：
   • 在 interactive login UI 中选择 Sign in with Device Code
   • 直接运行 codex login --device-auth
3. 在浏览器中打开链接，登录后输入 one-time code。

如果服务器没有启用 device code login，Codex 会回退到标准 browser-based login flow。

回退：先在本地登录，再复制 auth cache #

如果你能在有浏览器的机器上完成登录，可以把缓存凭据复制到 headless machine。

1. 在有浏览器的机器上运行 codex login
2. 确认 ~/.codex/auth.json 存在
3. 把 ~/.codex/auth.json 复制到 headless machine 的同一路径

~/.codex/auth.json 包含 access tokens，要像密码一样保护。不要提交，不要贴到工单，也不要在聊天里分享。

如果你的 OS 把凭据存到 credential store，而不是 ~/.codex/auth.json，这种方法可能不适用。可先看 Credential storage 了解如何切换为 file-based 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 container：

# 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，并把更新后的文件保留给下一次 job。自动化场景下，API keys 仍然是推荐默认方案。

回退：通过 SSH 转发 localhost callback #

如果你能在本地机器和远程主机之间转发端口，可以通过隧道使用标准 browser-based login flow，Codex 默认使用 localhost:1455 作为 local callback server。

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

ssh -L 1455:localhost:1455 user@remote

2. 在这个 SSH session 中运行 codex login，并按终端打印的地址在本地机器上完成登录。

其他 model provider 怎么认证 #

当你在配置文件里定义 custom model provider 时，可以选择下面几种认证方式：

• OpenAI authentication：设置 requires_openai_auth = true，使用 OpenAI authentication。此时可以用 ChatGPT 或 API key 登录。适合通过 LLM proxy server 访问 OpenAI models 的场景。设置 requires_openai_auth = true 后，Codex 会忽略 env_key。
• Environment variable authentication：设置 env_key = "<ENV_VARIABLE_NAME>"，从本地环境变量 <ENV_VARIABLE_NAME> 读取 provider-specific API key。
• No authentication：如果你没有设置 requires_openai_auth（或把它设为 false），并且也没有设置 env_key，Codex 会假定这个 provider 不需要认证。适合本地 models。

常见问题 #

OpenAI Codex 怎么选 ChatGPT 登录还是 API key 登录？ #

日常使用、需要 ChatGPT credits 或 Codex cloud 时，选 ChatGPT 登录。程序化工作流、CI/CD jobs 或需要按标准 API rates 计费时，选 API key 登录。CLI 默认在没有有效 session 时走 ChatGPT 登录。

Codex 无头机器登录失败怎么处理？ #

优先启用 device code authentication（beta），用 codex login --device-auth 完成登录；如果可在本地完成登录，也可以把 ~/.codex/auth.json 复制到无头机器，或者通过 SSH 转发 localhost:1455 完成浏览器登录流程。

auth.json 为什么不能随便分享？ #

因为它包含 access tokens。无论你把它存到 ~/.codex/auth.json 还是切到 file-based storage，都应当像密码一样保护，不能提交、外发或贴到聊天里。