---
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 試試”糊弄。先確認登入方式、憑據儲存和管理員策略是否匹配當前入口。
