---
title: "完成登录和认证"
description: "区分 ChatGPT 登录、API key 登录、云端认证、凭据缓存和受管理环境中的认证控制。"
verifiedAt: "2026-05-06"
---

import { Cards, Card } from 'fumadocs-ui/components/card';

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

> [!WARNING]
> `auth.json`、API key、access token 都应按密码处理。不要提交到 Git，不要贴进工单，不要发到聊天里，不要写进日志。

<Cards>
  <Card title="Authentication" href="https://developers.openai.com/codex/auth">
    查看 Codex 认证、凭据缓存、headless 登录和企业限制的官方说明。
  </Card>
  <Card title="Pricing" href="https://developers.openai.com/codex/pricing">
    了解 ChatGPT 计划、Codex credits 和 API key 计费差异。
  </Card>
  <Card title="Managed configuration" href="https://developers.openai.com/codex/enterprise/managed-configuration">
    在受管理环境里统一登录方式、workspace 和策略。
  </Card>
</Cards>

## 两种主要登录方式

```mermaid
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`。

配置示例：

```toml
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。

```shell
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 试试”糊弄。先确认登录方式、凭据存储和管理员策略是否匹配当前入口。
