完成登录和认证

Codex 认证方式会影响可用功能、计费路径、数据处理设置和管理员控制。开始使用前，先区分 ChatGPT 登录和 API key 登录。

两种主要登录方式

flowchart TB
    Login["Codex 登录"]
    ChatGPT["ChatGPT 登录<br/>使用订阅权益和 workspace 控制"]
    API["API key 登录<br/>使用 API organization 和按量计费"]
    Local["CLI / IDE / App"]
    Cloud["Cloud / Web"]

    Login --> ChatGPT
    Login --> API
    ChatGPT --> Local
    ChatGPT --> Cloud
    API --> Local

选择方式：

• 使用 Codex Cloud / Web：通常需要 ChatGPT 登录。
• 本地 CLI、IDE、App：可根据场景选择 ChatGPT 登录或 API key 登录。
• 程序化 CI/CD：通常更适合 API key 或官方 CI/CD 认证方案。
• 企业环境：遵守 workspace、RBAC、retention、residency 和 managed configuration。

不要只看“能不能登录成功”。还要看登录方式背后的数据处理和费用路径。

ChatGPT 登录

适合：

• 日常个人使用。
• Codex App、IDE、CLI 的交互式使用。
• 需要使用 ChatGPT plan 中包含的 Codex 权益。
• 需要遵守 ChatGPT workspace 管理策略。

特点：

• 通过浏览器完成登录。
• 使用 ChatGPT workspace permissions 和管理员控制。
• Enterprise / Edu 等环境可能有 retention、residency、RBAC 配置。
• Cloud / Web 场景通常依赖这种登录方式。

安全建议：

• 为账号启用 MFA。
• 使用组织 SSO 时由管理员强制 MFA。
• 不要把浏览器登录产生的 token 复制到不可信机器。

API key 登录

适合：

• 本地 CLI 或 IDE 的 API 计费场景。
• 脚本化或自动化任务。
• 需要明确使用 API organization 设置的环境。
• 不适合或无法使用 ChatGPT 登录的执行环境。

特点：

• 使用 OpenAI Platform API key。
• 费用走 API pricing。
• 数据处理遵循 API organization 设置。
• 某些依赖 ChatGPT workspace 或 credits 的功能可能不可用。

安全建议：

• API key 只放在环境变量或受控 secret store。
• 不要把 key 写入 config.toml、.env.example 或文档。
• 自动化 runner 使用最小权限和可轮换凭据。

凭据缓存

Codex 会缓存登录信息，避免每次启动都重新登录。缓存位置取决于配置和系统能力：

• 操作系统 credential store。
• CODEX_HOME/auth.json。

配置示例：

cli_auth_credentials_store = "keyring"

可选值通常包括：

• keyring：优先使用系统凭据存储。
• file：使用 auth.json 文件。
• auto：系统凭据可用时用 keyring，否则回退到文件。

如果使用文件存储，auth.json 就是敏感凭据。复制、备份、同步时都要按密钥处理。

Headless 和远程环境

无图形界面或远程主机上，浏览器回调可能不可用。优先考虑：

1. Device code authentication。
2. 受控 CI/CD 认证方案。
3. 通过 SSH 转发 localhost callback。
4. 在可信机器上登录后转移缓存凭据。

最后一种方式风险最高，只应在可信机器之间使用，并确保文件权限、传输方式和目标机器都受控。

如果目标环境是 CI/CD，优先使用官方 CI/CD 认证指南，而不是临时复制个人 token。

受管理环境

企业或团队可以限制：

• 只允许 ChatGPT 登录或 API key 登录。
• 只允许特定 ChatGPT workspace。
• 使用 managed configuration 统一安全策略。
• 配置 cloud、本地入口、reviewer、MCP、网络和权限边界。

这类设置应由管理员下发，不应依赖每个用户手动配置。

证书和企业网络

如果企业网络使用 TLS proxy 或私有 root CA，需要在登录前配置证书 bundle。

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

如果没有设置专用变量，Codex 可能会回退到通用 TLS 证书环境变量。具体行为以官方认证文档为准。

登录诊断

登录失败时，先区分问题类型：

• 浏览器无法打开。
• localhost callback 被阻断。
• device code 未启用。
• workspace 权限不足。
• API key 无效或组织不匹配。
• 企业 TLS 证书链不被信任。
• 本地凭据缓存损坏。

排查顺序：

1. 运行 codex login 复现。
2. 查看登录日志。
3. 检查当前凭据存储方式。
4. 确认 workspace 或 API organization。
5. 必要时退出登录后重新认证。

认证问题不要用“换个 token 试试”糊弄。先确认登录方式、凭据存储和管理员策略是否匹配当前入口。