String AI
語言
登錄 立即開始
博客

企業網路中的 Codex CLI：CA 證書包、憑據儲存與登入

在受管網路上，Codex CLI 登入失敗通常與金鑰無關。要檢查的順序是：先信任，再憑據儲存，最後登入路徑。

String AI Editorial Team
企業網路中的 Codex CLI：CA 證書包、憑據儲存與登入

在企業代理之後或處於流量檢查網路之中的 Codex CLI，是一類獨立的配置問題。登入失敗時，本能反應是懷疑金鑰或賬戶，但在受管網路上，最常見的三個原因並非如此：由於企業 TLS 代理或私有根證書擋在鏈路中，證書鏈不被信任；CLI 依賴的憑據儲存被管理員鎖定或強制規定；或者登入路徑本身被阻斷，因為瀏覽器回撥無法回到這臺機器。每個問題有不同的修法，而且有一套可用的檢查順序：先信任，再儲存，最後登入路徑。個人機器上的對應內容涵蓋登入模式和本地憑據儲存；本文講的是企業環境。

codex cli login 證書錯誤：為什麼信任問題會穿上登入的外衣

團隊上報的症狀通常是“登入壞了”：CLI 卡在認證環節、握手失敗，或者昨天還能通的請求今天不再完成。證書鏈問題往往就是這樣表現的，而打印出的錯誤並不總把信任庫點名為根因。這就是為什麼在受管網路上第一步不是檢查金鑰，而是先問：在組織的攔截設定下，這臺機器究竟能否與端點完成 TLS。TLS 代理會用組織自己的根證書重新簽名流量；自帶 CA 信任配置的工具需要把這個根證書顯式提供給它。Codex CLI 正是支援這一點，使你可以在花時間折騰憑據之前，低成本地排除或確認證書問題。

可信 CA 證書包：登入前設定 CODEX_CA_CERTIFICATE

官方認證文件把這一設定講得很直白。如果你的網路使用企業 TLS 代理或私有根 CA，請在登入前將 CODEX_CA_CERTIFICATE 設定為 PEM 證書包，然後再登入：

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

文件中有三個細節在運維上很重要：

  1. 優先順序。 CODEX_CA_CERTIFICATE 的優先順序高於 SSL_CERT_FILE。未設定時，Codex 會回退到 SSL_CERT_FILE，因此已經統一使用該變數的環境仍可正常工作，但兩者同時存在時，Codex 專用變數優先。
  2. 作用範圍。同一套自定義 CA 設定適用於登入、普通 HTTPS 請求和安全 WebSocket 連線。這一點很重要，因為只為登入設定的證書包，會讓後續的工作會話同樣暴露在這些故障之下。
  3. 順序。在登入前設定。證書包必須位於登入程序自身的環境中，而這正是那些把它配在 shell profile 裡的團隊容易栽跟頭的地方——互動式登入和服務程序並不都會繼承它。

關於完整的環境變數行為，參見認證文件。

憑據儲存：cli_auth_credentials_store 的四種模式

CLI 把快取的憑據存在哪裡是一個配置決策，而在受管機器上，它與企業策略存在重疊。cli_auth_credentials_store 設定接受四個值：

  • file 將憑據儲存在 auth.json 中，位於 CODEX_HOME 之下，後者預設為 ~/.codex。
  • keyring 將憑據儲存在作業系統憑據儲存中，若該儲存不可用則失敗。這是受管機群傾向選擇的模式，但在強制推行之前，請先確認你的環境中確實存在該儲存。
  • auto 在可用時使用作業系統憑據儲存，否則回退到 auth.json，這使它成為混合環境中最寬容的選擇。
  • ephemeral 只在當前程序的記憶體中儲存憑據，適合容器和一次性任務——這些場景不應有任何內容持久化到磁碟。

由此產生兩個後果。第一，如果把儲存設為 file，就要把 ~/.codex/auth.json 當作密碼對待：它包含 access token，因此不得提交到程式碼庫、貼上進工單或在聊天中分享。第二，這個選擇並不總是由你來做：管理員可以通過本地認證要求強制規定憑據儲存和 ChatGPT base URL，而使用者無法通過 config.toml 或 CLI 覆蓋項來推翻這些要求。

無論選擇哪種模式，憑據本身仍然遵循金鑰生命週期規則：到期日期、輪換路徑和吊銷路徑，正如金鑰衛生指南所闡述的那樣。

當管理員強制規定這些設定時

當遇到“我改了，卻什麼都沒發生”時，這一節就是你要讀的。受管配置文件說明管理員會設定 cli_auth_credentials_store 和 chatgpt_base_url（以及登入方式和工作區限制），位置在本地系統要求檔案中，或通過 macOS MDM 要求。這些本地要求有兩個特性，解釋了大部分困惑：

  • 它們在憑據載入之前、在 Codex 獲取雲策略之前就生效，因此當其他任何環節讀取配置時，被強制的值已經生效。
  • 雲端管理側會忽略這幾個特定欄位；本地強制才是生效機制。

如果一臺 worker 機器拒絕了在同事筆記本上可用的憑據儲存模式，答案通常根本不在 config.toml 裡。它在管理員掌控的要求檔案中，解決辦法是去和那位管理員溝通，而不是改配置。

共享快取，共享意外

Codex 會快取登入資訊並在各個介面間複用：ChatGPT 桌面應用、CLI 和 IDE 擴充套件都參與同一套快取機制，而 CLI 與擴充套件更是共享同一份快取的登入資訊。如果有人在其中任一處退出登入，CLI 或擴充套件下次啟動時就需要重新登入。這些資訊以明文檔案形式儲存在本地 ~/.codex/auth.json，或儲存在作業系統專屬的憑據儲存中，具體取決於模式；對於 ChatGPT 登入會話，Codex 會在 token 到期前於使用過程中自動重新整理，因此活躍會話通常無需再走一趟瀏覽器。

工程上的結論：“我這兒能用，他那兒不行”在機群中是預期會出現的一類問題，要比對的變數很具體：那臺機器上有哪個憑據儲存可用、那裡強制的是哪種模式、單使用者快取處於什麼狀態。這種比對比任何重灌都快。

在受限網路中如何選擇登入路徑

基於瀏覽器的登入流程有兩種文件記載的失敗情形，企業在其中屢屢受挫：在遠端或無頭環境中執行 CLI，以及本地網路阻斷了 Codex 在登入後回傳 OAuth token 所用的 localhost 回撥。在這些情況下，文件建議優先使用裝置程式碼認證（beta）：在互動式登入介面中選擇 Sign in with Device Code，或直接執行 codex login --device-auth。

有一個前提很重要，而且是組織層面的，不是技術層面的：裝置程式碼登入必須先被啟用，個人賬戶在 ChatGPT 安全設定中啟用，或由管理員在工作區許可權中啟用。這個啟用點與早前憑據指南中描述的是同一處，在受管網路上，它往往決定了是五分鐘搞定還是開一張支援工單。如果你的環境中沒有裝置程式碼認證，官方文件描述了把登入帶到機器上的兜底方法，而直接執行 codex login 會寫入一個專用的 codex-login.log 到已配置的日誌目錄下，那正是拿去溝通時該帶的產物，尤其是瀏覽器登入和裝置程式碼失敗的情況。

面向自動化的非互動式憑據

自動化使用的憑據與互動式登入不同，這條界線值得劃清：

  • CODEX_API_KEY 為非互動式的 Codex 程序提供 API key。文件給出的部署建議：在執行受倉庫控制的程式碼時，以內聯方式設定，而不是設為整個作業級別的環境變數，這樣作業中執行的程式碼就無法從環境中讀出該憑據。
  • CODEX_ACCESS_TOKEN 為可信自動化提供 ChatGPT 或 Codex access token；若要持久化登入，請把它通過管道傳給 codex login --with-access-token。access token 文件涵蓋了簽發配置。
  • 工作負載身份 覆蓋第三種模式，即由程序環境提供身份：OPENAI_FEDERATION_RULE_ID 選擇為該工作負載配置的聯邦規則，OPENAI_IDENTITY_TOKEN_FILE 指向包含當前 OIDC token 或 SPIFFE JWT-SVID 的檔案的絕對路徑，OPENAI_WORKLOAD_IDENTITY_CONTEXT 可選地提供有界的 JSON 識別符號，用於客戶端上報的審計歸因，且不影響認證或授權。當選擇工作負載身份時，codex login 和 codex logout 會被拒絕，因為認證由程序環境控制。

有一個界限需要記住：模型供應商的 API key 不是 CLI 憑據。對於供應商金鑰，Codex 會讀取由 env_key 在模型供應商配置中指名的變數，所以變數名本身並不固定。這些憑據在 CI 中的專用模式見CI 中的編碼 agent 指南。

排查順序

在受管網路上，按這個順序逐層排查：

  1. 信任層。 是否在執行登入程序的那個環境中，把 CODEX_CA_CERTIFICATE 設為企業的 PEM 證書包，並以 SSL_CERT_FILE 作為文件給出的回退選項？這一項放在最前，因為它的症狀會偽裝成其他所有問題。
  2. 儲存層。 生效的是哪一種 cli_auth_credentials_store 模式，底層儲存在這臺機器上是否真的可用，以及該模式是否由你無法推翻的本地要求強制？
  3. 登入路徑。 瀏覽器流程能否完成（回撥是否可達），還是裝置程式碼才是正確路線？失敗時保留 codex-login.log 作為證據。
  4. 應用層。 如果認證成功而請求仍然失敗，問題已經轉移了：區域和許可權拒絕在 403 指南 中有各自的分類，而通用的狀態碼分診見錯誤碼指南。

還有一種失敗會偽裝成配置問題：被固定的模型已經退役，所以請拿你的模型 ID 對照2026 年 10 月關閉彙總 核查。

清單

  1. 在存在 TLS 攔截時，登入前把 CODEX_CA_CERTIFICATE 設為 PEM 證書包；記住 SSL_CERT_FILE 這個回退選項，以及登入、HTTPS 和 WebSocket 的作用範圍。
  2. 確認該變數能到達真正的登入程序，而不只是互動式 shell。
  3. 有意識地選擇憑據儲存：有可用憑據儲存的受管機器用 keyring，容器用 ephemeral，混合環境用 auto。
  4. 把 auth.json 當作密碼對待，只要涉及 file 儲存。
  5. 當某項設定不生效時，先懷疑本地要求檔案，再懷疑 CLI。
  6. 對於無頭主機或回撥被阻斷的主機，啟用並使用裝置程式碼認證；保留失敗時的 codex-login.log。
  7. 對於自動化，選對憑據類別：受倉庫控制的程式碼用內聯的 CODEX_API_KEY，可信流水線用 CODEX_ACCESS_TOKEN，平臺簽發身份的場景用工作負載身份。
  8. 遇到“我這兒行、他那兒不行”，就在兩邊機器上比對證書包、憑據儲存可用性、強制配置和回撥可達性。

企業環境只獎勵一種習慣：先查信任再查憑據，先查憑據再查程式碼。你們團隊所呼叫的那個端點的端點級事實，就在平臺自己的文件。