哪個 Codex CLI 設定會贏：七層配置優先順序

Codex CLI 裡“不生效”的設定，幾乎總是層級問題，而不是語法問題。同一個鍵可以寫在好幾個地方，而最終生效的值由文件規定的順序決定，而不是由你最後編輯了哪個檔案決定。官方配置文件把這個順序定義為七層，優先順序從高到低，外加一道安全閘門：專案未被信任時，它會靜默地關掉整個一層。這三條資訊足以解釋大多數配置上的意外：順序、信任閘門，以及在改動任何東西之前先定位“獲勝層”的習慣。

下面的順序和引文來自官方的配置基礎頁面，欄位級的背景在 Codex 手冊裡。構建時請對照當前頁面核實。

按文件順序排列的七個層級

Codex 明確列出了這個解析順序，優先順序從高到低。這裡按原樣複述，不合並任何層級：

1. CLI 標誌和--config配置覆蓋項。該次呼叫在命令列上傳入的值。
2. 專案配置檔案 .codex/config.toml，從專案根目錄一直到你當前的工作目錄，離得最近的檔案獲勝，僅限受信任的專案。
3. Profile 檔案，通過--profile profile-name對應的命令列標誌選擇，~/.codex/profile-name.config.toml以獨立檔案的形式存放在 Codex 配置目錄下。
4. 使用者配置，位於~/.codex/config.toml使用者主目錄下的 config.toml。
5. 雲端託管的config.toml預設值，在已登入的 workspace 下會被下發。
6. 系統配置，如果存在的話：/etc/codex/config.tomlUnix 上系統級路徑下的 config.toml。
7. 內建預設值。

那份清單裡有兩個細節很容易被略過。專案層不是一個檔案：Codex 從倉庫根目錄一路走到你正在工作的目錄，最近的那個檔案獲勝，這就是 monorepo 能讓某個子目錄擁有不同設定而不必複製一切的方式。而 profile 層位於使用者配置之上，而不是之下，這意味著 profile 可以覆蓋你個人配置裡已經設好的鍵。

一個有用的心智模型是一疊覆蓋項，而不是一組檔案：每一層只貢獻它實際設定的鍵，而第一個提到某個鍵的層決定該鍵的值。對某個鍵保持沉默的層對它沒有任何貢獻。

專案層上的信任閘門

最能解釋“我的專案配置為什麼被忽略”這類反饋的那句話，就在同一頁面的開頭：

出於安全考慮，Codex 只在你信任該專案時才載入專案的.codex/配置層。

優先順序表在括號裡重複了這個約束：僅限受信任的專案。頁面也說明了未受信任專案的後果：Codex 會跳過專案範圍內的.codex/配置層，包括專案本地的配置、hooks 和 rules；而使用者配置和系統配置仍然會載入，包括使用者級和全域性的 hooks 與 rules。

這是安全邊界，不是 bug。你克隆下來的一個倉庫，不應該僅僅因為裡面包含一個目錄就能改變你的 agent 的行為，所以專案層在你明確同意之前是關著的。如果.codex/config.toml config.toml 裡的某個設定看起來毫無效果，先檢查專案的信任狀態，優先於任何 TOML 除錯。

策略不是一個你能覆蓋的層

還有第二種機制看起來像優先順序，其實不是：託管要求。文件把分工說得很直白：

要求約束行為；配置值提供預設值。

配置層決定哪個預設值適用；要求決定什麼根本被允許。在受管機器上，組織可以通過requirements.toml強制執行約束，比如禁止某種審批策略或 sandbox 模式。去找一個優先順序更高的配置層贏不過一條要求，因為要求並不在同一條梯子上競爭。當某個值在受管裝置上拒絕改變時，要問的是有沒有一條要求按住了它，而不是你還有哪個配置檔案沒改。

一個設定該放在哪裡

順序清楚之後，實際問題就變成放在哪。文件自己的指引很簡潔：利用優先順序把共享預設值放在config.toml使用者配置裡，並讓 profile 檔案只專注於那些不同的取值。

| 情形 | 該用的層 |
| --- | --- |
| 團隊共享預設值 | 使用者配置，~/.codex/config.toml使用者主目錄下的 config.toml |
| 倉庫特定行為 | 倉庫裡的 config.toml.codex/config.toml，同時記得信任要求 |
| 環境或角色差異 | 一個 profile 檔案加上--profile profile-name對應命令列標誌 |
| 一次性或指令碼化呼叫 | 命令列上的--config覆蓋項 |
| 全機器範圍、無策略的預設值 |/etc/codex/config.toml Unix 上的系統配置 |

鍵本身的語義，包括 provider 欄位及其預設值，在自定義 provider 指南裡。還有一條相關邊界值得理清：憑證來自哪裡是它自己的話題，不是一個配置層，儲存模式在憑證指南裡。

CI 裡的取捨

持續整合讓分層變得可見，因為 CI runner 恰恰是那種不能假定專案層存在的環境。一次 checkout 的信任狀態不是流水線該依賴的東西，而那臺機器上的使用者配置可能根本不是你寫的。由此有兩個習慣。對每個環境不同的值，一個 profile--profile 保留一小組具名配置；對每次呼叫不同的值，--config命令列覆蓋項把它們顯式傳進去。兩種情況裡，重要的值都在流水線裡寫明，而不是從某個沒人審計過的層繼承。在流水線裡跑編碼 agent 的更多模式在 CI 指南裡。

如果問題裡的設定是受管網路上的證書包或代理配置，那它屬於企業環境的話題，而不是層級挑選；企業網路指南講了這些。

除錯一個怎麼都改不動的值

從上往下過這些層，停在第一個提供該值的層：

1. 信任狀態。專案到底被信任了嗎？如果沒有，到此為止：專案層根本不在場。
2. 命令列。這次呼叫是否帶了--config配置覆蓋項，或者某個設定該鍵的標誌？
3. 專案層。對於受信任的專案，是否存在一個比你編輯的那個更靠近工作目錄的.codex/config.toml config.toml？
4. Profile。是否有某個--profile profile 處於啟用狀態，而那個 profile 檔案設定了同一個鍵？
5. 使用者配置。這個值是否在~/.codex/config.toml使用者 config.toml 裡，而且可能比你記得的更舊？
6. 雲端託管的預設值。是否有已登入的 workspace 在下發某個託管的config.toml預設值？
7. 系統配置和內建預設值。最後，檢查/etc/codex/config.toml Unix 上的系統配置，再看文件列出的內建預設值。

這個順序也是驗證假設最快的方式：用--config覆蓋項為當前這次呼叫設一次值。如果行為變了，就說明鍵是對的，問題在放置位置；如果沒變，問題在鍵本身或要求層。把你改過的層和獲勝的層記下來；這一對是一次配置決策唯一持久的記錄，也能讓下一個人省掉同一趟排查。

CLI 和 IDE 共享同一套層

文件指出 CLI 和 IDE 擴充套件共享同一套配置層。從任一介面編輯使用者配置都會同時改變兩者的行為，這很方便，直到有人編輯了一個專案檔案，以為它只會影響 IDE。文件裡開啟檔案的路徑很短：在 IDE 擴充套件裡，點選右上角的齒輪圖示，然後進入 Codex Settings > Open config.toml。在 ChatGPT 桌面應用裡，同一個檔案通過 Settings > Configuration > Open config.toml 開啟，手冊如此說明。同一套層，從任一工具看過去，都以相同的順序解析。

檢查清單

1. 在除錯任何專案層的值之前，先確認專案的信任狀態。
2. 用一次性的--config覆蓋項復現生效值。
3. 把共享預設值放在使用者配置裡，而不是散落在各個專案檔案中。
4. 把倉庫特定的值放進.codex/config.toml config.toml，並記住信任閘門。
5. 讓 profile 只專注於那些不同的取值，用--profile對應標誌來選擇。
6. 在 CI 裡顯式寫明關鍵值，而不是依賴專案層。
7. 當受管機器拒絕某項改動時，先查要求，再查配置層。
8. 從上到下走一遍這七層，並把團隊的放置約定一次性寫下來。

七層，一道信任閘門，還有一個站在梯子之外的策略機制。大多數配置之謎都能收攏成一個問題：這裡哪一層有權說話，又是哪一層在說話。本站記錄的相容服務的端點級細節在它自己的文件裡，而第一次把這些層放進上下文的四工具配置在共享金鑰指南裡。一如既往，請對照構建時官方頁面的當前內容核實順序和引文。