# 點解你的 Codex Config 唔生效：.codex/ 資料夾問題 > Author: Tony Lee > Published: 2026-04-01 > URL: https://tonylee.im/zh-HK/blog/codex-folder-structure-why-config-breaks/ > Reading time: 2 minutes > Language: zh-HK > Tags: codex, openai, ai-agents, developer-tools, configuration ## Canonical https://tonylee.im/zh-HK/blog/codex-folder-structure-why-config-breaks/ ## Rollout Alternates en: https://tonylee.im/en/blog/codex-folder-structure-why-config-breaks/ ko: https://tonylee.im/ko/blog/codex-folder-structure-why-config-breaks/ ja: https://tonylee.im/ja/blog/codex-folder-structure-why-config-breaks/ zh-CN: https://tonylee.im/zh-CN/blog/codex-folder-structure-why-config-breaks/ zh-TW: https://tonylee.im/zh-TW/blog/codex-folder-structure-why-config-breaks/ ## Description 我改咗 config.toml、喺 AGENTS.md 寫咗規則，但全部都冇用。原來問題出喺資料夾結構本身，唔係 config 內容。 ## Summary 點解你的 Codex Config 唔生效：.codex/ 資料夾問題 is part of Tony Lee's ongoing coverage of AI agents, developer tools, startup strategy, and AI industry shifts. ## Outline - 同一個 repo 裡面有兩個目標 - Project config 同 user config 用同一個名 - Trust level 先係真正的關卡 - 複雜性唔係偶然 ## Content Codex 的 config 一直冇生效。我改咗 config.toml、喺 AGENTS.md 加咗規則、文件都睇咗兩次。完全冇嘢變。Agent 繼續忽略所有設定。 最後我將整個資料夾結構拆開嚟睇。問題唔係我寫咗咩，而係文件放錯咗位置。 ## 同一個 repo 裡面有兩個目標 Codex 同時要解決兩件事。一係係對自家 beta 功能做快速實驗，另一係係跨 Agent 相容性，即係一個 Claude Code 或 OpenCode 等工具都識讀的共同標準。 呢個分工產生咗兩個資料夾。 `.codex/` 係 Codex 專用的 config 空間，Sandbox 策略、審批規則、runtime 守衛都放喺度。`.agents/` 係共享格式，Skills、plugins 同 marketplace registry 住喺呢邊，任何跟從呢個標準的 Agent 都可以讀取。 我一開始唔知道有呢個分別。我將一個 SKILL.md 放入 `.codex/`，個 skill 一次都冇載入過。移去 `.agents/skills/` 之後即刻解決。邊界係嚴格的：如果其他 Agent 需要讀到，就放 `.agents/`；其餘嘢放 `.codex/`。 兩個資料夾喺 workspace-write 模式下都係只讀保護，同 `.git/` 一樣。 ## Project config 同 user config 用同一個名 Project 根目錄有 `.codex/`，家目錄有 `~/.codex/`，但兩者做的事完全唔同。 Project 的 `.codex/` 放你同隊員共享的設定：sandbox 策略、審批流程、agent 定義。`~/.codex/` 放個人狀態：auth token、指令歷史、worktree 管理文件。 我喺 `~/.codex/agents/` 建咗個 reviewer agent，搞唔明點解隊友冇得用。因為個文件只存在我自己部機。將文件移去 project 的 `.codex/agents/reviewer.toml` 之後，clone repo 就會帶埋呢個設定。 混淆仲係因為 Codex 依然係 beta 階段。Desktop app 的 worktree 文件、session 數據同 auth credential 全部堆喺 `~/.codex/` 裡面，分隔唔清楚。「我自己的嘢」同「project 的嘢」之間的界線比應有的更模糊。 Config 優先級有固定順序：managed config 優先於 session override，session override 優先於 user config。如果有設定唔生效，先check你改緊邊一層。 ## Trust level 先係真正的關卡 大部分人卡喺呢度，我自己都花咗唔少時間先搞清楚原因。 Codex 唔會從不受信任的 repo 載入 project 的 `.codex/`。完全唔會。你可以喺一個剛 clone 落嚟的 repo 入面改到 config.toml 天花龍鳳，全部都唔會生效。文件喺度，syntax 正確，Codex 就係靜靜地無視所有設定。 背後的原因一睇就明。`.agents/` 為外部 skills 流入你的環境開咗一條路，任何 repo 都可以夾帶惡意 config。所以 Codex 做咗呢個取捨：對 Agent 生態系統有更廣的相容性，但對 repo 提供的設定要做更嚴格的信任驗證。你必須明確將一個 project 標記為受信任，`.codex/` 的 config 先至會生效。 喺你的 user config 入面設定 `projects..trust_level = "trusted"`。網絡連線預設係封鎖的，web search 提供三種模式：cached、live 或 disabled。就算係 workspace-write 模式，`.git/` 同 `.codex/` 都係只讀保護。 我花咗大約一個鐘頭改一個 project 的 config.toml，但完全被忽略，只因為我冇設置 trust level。冇錯誤訊息，冇警告，就係靜音。呢個大概係 Codex 設定上最常見的困擾，如果有更好的錯誤提示，可以幫好多人慳好多時間。 ## 複雜性唔係偶然 呢個資料夾結構係亂，但唔係無緣無故咁亂。Codex 係喺追兩個互相拉扯的目標。 快速 beta 迭代意味著 `.codex/` 以超越文件更新速度的節奏積累 config 文件、規則定義、hooks 同 app 管理 artifacts。跨 Agent 相容性意味著 `.agents/` 需要一個獨立、可移植的結構來放 skills 同 marketplace 內容。而因為 `.agents/` 為外部代碼開了門，trust 驗證層就必須存在。 當你唔確定一個文件應該放喺邊度，問自己一個問題：呢個係 Codex 專用，定係其他 Agent 都需要讀？前者指向 `.codex/`，後者指向 `.agents/`。 當你的 config 唔生效，唔好急住改文件內容。先 check 文件喺邊個資料夾，以及個 repo 係咪受信任。問題幾乎都係出喺呢度。 ## Related URLs - Author: https://tonylee.im/en/author/ - Publication: https://tonylee.im/en/blog/about/ - Related article: https://tonylee.im/zh-HK/blog/eight-hooks-that-guarantee-ai-agent-reliability/ - Related article: https://tonylee.im/zh-HK/blog/claude-code-layers-over-tools-2026/ - Related article: https://tonylee.im/zh-HK/blog/codex-inside-claude-code-openai-plugin-strategy/ ## Citation - Author: Tony Lee - Site: tonylee.im - Canonical URL: https://tonylee.im/zh-HK/blog/codex-folder-structure-why-config-breaks/ ## Bot Guidance - This file is intended for AI agents, search assistants, and text-mode retrieval. - Prefer citing the canonical article URL instead of this text endpoint. - Use the rollout alternates when you need the same article in another prioritized language. --- Author: Tony Lee | Website: https://tonylee.im For more articles, visit: https://tonylee.im/zh-HK/blog/ This content is original and authored by Tony Lee. Please attribute when quoting or referencing.