Codex 設定為什麼沒有生效：.codex/ 資料夾的問題

Codex 的設定完全沒有生效。我編輯了 config.toml、在 AGENTS.md 加了規則、把文件看了兩遍。什麼都沒有改變，agent 繼續無視所有設定。

後來我把整個資料夾結構重新梳理了一遍，才發現問題不在檔案裡寫了什麼，而在於檔案放在哪裡。

一個 repo 裡住著兩個目標

Codex 同時在解決兩件事。一是快速迭代自己的 beta 功能，二是跨 agent 的相容性，也就是讓 Claude Code 或 OpenCode 這類工具也能讀取的共用標準。

這個分歧造就了兩個資料夾。

.codex/ 是 Codex 專屬的設定空間，沙盒策略、審核規則、執行時的限制都放在這裡。.agents/ 是共用格式，技能、外掛和市集的 registry 放在這一側，任何遵循這個標準的 agent 都可以讀取。

我一開始不知道這個區分。我把 SKILL.md 丟進 .codex/，技能始終沒有載入。把它移到 .agents/skills/ 之後，立刻就生效了。邊界是嚴格的：如果其他 agent 需要讀取這個檔案，就要放在 .agents/。其他所有東西才放在 .codex/。

這兩個資料夾在 workspace-write 模式下都受到唯讀保護，跟 .git/ 一樣。

專案設定和使用者設定用了同一個名字

你的專案根目錄有一個 .codex/，home 目錄下有一個 ~/.codex/。這兩個做的事情完全不同。

專案的 .codex/ 放的是要和團隊共用的設定：沙盒策略、審核流程、agent 定義。~/.codex/ 放的是個人狀態：auth token、指令歷史、worktree 管理檔案。

我曾經把一個 reviewer agent 放在 ~/.codex/agents/ 裡，然後一直搞不清楚為什麼隊友那邊沒有這個 agent。因為它只存在於我的電腦上。把檔案移到專案的 .codex/agents/reviewer.toml 之後，clone repo 的人就都能拿到了。

因為 Codex 還在 beta 階段，這個混亂更加嚴重。Desktop app 的 worktree 檔案、session 資料和 auth 憑證全都堆進 ~/.codex/，沒有清楚的分層。「我的東西」和「專案的東西」之間的界線比應該有的更模糊。

設定的優先順序有固定的規則：managed config 優先於 session override，session override 再優先於 user config。當設定沒有套用，先確認你改的是哪一層。

信任等級才是真正的門檻

這是大多數人卡住的地方，我也在這上面浪費了不少時間才搞懂。

Codex 不會從不受信任的 repo 載入專案的 .codex/，完全不會。你在剛 clone 下來的 repo 裡把 config.toml 改得再仔細，什麼都不會套用。檔案在那裡，語法也正確，Codex 就是默默地忽略它。

道理在看清楚之後其實說得通。.agents/ 為外部技能進入你的環境開了一條路，任何 repo 都可能夾帶惡意設定。所以 Codex 做了這個取捨：和 agent 生態系的相容性更廣，但來自 repo 的設定需要更嚴格的信任驗證。你必須明確地把一個專案標記為受信任，它的 .codex/ 設定才會生效。

在 user config 裡設定 projects.<path>.trust_level = "trusted"。網路存取預設也是封鎖的，web search 有三種模式可選：cached、live 或 disabled。即使在 workspace-write 模式下，.git/ 和 .codex/ 依然是寫保護的。

我花了將近一個小時在編輯一個完全被忽略的 config.toml，就是因為沒有設定信任等級。沒有錯誤訊息，沒有任何警告，就只是沉默。這大概是 Codex 設定最常見的挫折點，如果錯誤訊息能做得更好，可以幫很多人省下大量時間。

這個複雜度不是意外

資料夾結構很亂，但不是隨機亂。Codex 同時在追求兩個方向相反的目標。

快速的 beta 迭代讓 .codex/ 累積了設定檔、規則定義、hooks 和 app 管理的各種 artifacts，速度快到文件根本跟不上。跨 agent 相容性讓 .agents/ 需要一個獨立、可攜的結構來放技能和市集內容。而因為 .agents/ 開了讓外部程式碼進來的門，信任驗證層就必須存在。

當你不確定一個檔案要放哪裡，問自己一個問題：這是 Codex 專屬的，還是其他 agent 也需要讀取？前者放 .codex/，後者放 .agents/。

當設定沒有生效，不要先去改檔案內容。先確認它放在哪個資料夾，以及這個 repo 是否已經被信任。問題幾乎都在這裡。