完成登入和認證

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