結論先說
- 同一目錄下,
AGENTS.override.md會整份替代AGENTS.md,而不是增量合併。按官方文檔,Codex 在每個目錄層級最多隻加載一個非空指令文件,優先級嚴格為:AGENTS.override.md>AGENTS.md>project_doc_fallback_filenames。 - 跨目錄則是「自頂向下」依次拼接。Codex 先讀個人主目錄(
~/.codex/或$CODEX_HOME/),再從 Git 倉庫根目錄一路向下掃描到當前工作目錄,更深層子目錄的指令拼在後面,對具體子模組擁有更高話語權。 - 不改倉庫提交文件的最佳本地覆蓋法是配合
.git/info/exclude。把AGENTS.override.md寫進倉庫本地的.git/info/exclude(無需修改團隊共享的.gitignore),即可放心做臨時覆蓋且完全不污染git status。 - 警惕 32 KiB 共享字節上限導致的「靜默截斷」。所有層級拼接後的總大小預設受
project_doc_max_bytes = 32768限制;如果根目錄AGENTS.md寫得太臃腫,深層子目錄的規則會被直接截掉。 - 在大型 Monorepo 中頻繁加載多層規則並執行多輪重構,需要穩定配額支撐。國內若無外幣銀行卡或綁卡受阻,可在本站自助開通 ChatGPT Plus 或高配額 ChatGPT Pro,團隊規範化部署可了解 ChatGPT Business 團隊定製。

圖:本站根據 OpenAI Codex 官方文檔:Custom instructions with AGENTS.md 整理的示意圖
本文根據 OpenAI Codex 官方文檔《Custom instructions with AGENTS.md》《Configuration Reference》《Projects》整理,資料核對於 2026-11-19。配圖為本站整理的示意圖,不是介面截圖。本站(bigolab.com)不是 OpenAI 官方網站。
適用於誰
- 在多人協作倉庫工作,想臨時調整 Codex 的測試命令、輸出語言或代碼風格,卻不想直接改動受版本控制的
AGENTS.md的開發者; - 在大型 Monorepo 中維護根目錄與多個子包規則,搞不清
AGENTS.override.md到底會「合併」還是「整份替換」原文件的人; - 發現子目錄裏新寫的
AGENTS.md或AGENTS.override.md莫名沒生效,懷疑觸發了字節上限截斷的團隊。
一、同目錄替換 vs 跨目錄疊加:一次搞懂優先級邏輯
基礎 AGENTS.md 寫法與定位可先回顧 /guides/codex-agents-md-how-it-reads(以及與記憶功能的分工 /guides/codex-memories-how-to-use-vs-agents-md)。在多人倉庫與 Monorepo 場景中,理解下面兩條規則就不會寫錯位置:
| 生效範圍 | 存在哪些文件 | Codex 實際加載結果 |
|---|---|---|
個人全局目錄(~/.codex/) | 同時存在 AGENTS.override.md 與 AGENTS.md | 僅加載 ~/.codex/AGENTS.override.md |
倉庫根目錄(repo/) | 同時存在 AGENTS.override.md 與 AGENTS.md | 僅加載 repo/AGENTS.override.md,跳過根 AGENTS.md |
Monorepo 子包(repo/apps/web/) | 根有 AGENTS.md,子包有 AGENTS.override.md | 兩者先後拼接加載(根在前,子包覆蓋文件在後) |
| 歷史遷移目錄 | 無 AGENTS.*,但有 CLAUDE.md 且配了回退列表 | 按 project_doc_fallback_filenames 順序加載首個命中文件 |
特別注意第二行的常見誤解:很多開發者在倉庫根目錄建了一個只有三句話的 AGENTS.override.md,以為它會在原 AGENTS.md 末尾追加三句話;實際上只要同目錄存在非空的 AGENTS.override.md,該目錄的 AGENTS.md 會被完全屏蔽。如果你還想保留團隊原規則裏的構建和測試約定,應先複製原 AGENTS.md 裏的關鍵條目,再補充你的臨時要求。
二、實戰:臨時覆蓋倉庫全局規則且不污染 Git 提交
想在本地調優某個棘手故障(例如臨時要求 Codex 跳過耗時的端到端測試、只跑單文件單測並輸出詳細中文推理過程),又不想在 PR 裏留下髒文件,本站建議按以下三步操作:
第 1 步:把覆蓋文件名加入本地私有排除表
不要去改團隊共享的 .gitignore,而是寫入僅對你本機生效的 .git/info/exclude:
bash
printf "\nAGENTS.override.md\n**/AGENTS.override.md\n" >> .git/info/exclude
這樣無論你在倉庫根目錄還是任意子包下創建 AGENTS.override.md,git status 都保持徹底乾淨,不會誤 git add 提交到遠端分支。
第 2 步:按需編寫最小化的 AGENTS.override.md
如果放在倉庫根目錄,記得保留必要的團隊基礎約束;如果只針對某個子模組做臨時規則覆蓋,直接放在對應子目錄(如 services/billing/AGENTS.override.md)即可,上層根目錄的 AGENTS.md 會照常加載:
markdown
# 本地臨時調試覆蓋規則(僅本機生效)
- 本次調試只關注 services/billing 模組,不要修改共享庫 packages/common。
- 每次改動後僅運行 `pytest tests/test_billing.py -q`,暫不觸發全倉集成測試。
- 所有改動說明與風險提示請用簡潔中文列出,並附帶修改文件名與行號。
第 3 步:調優配置防截斷併兼容舊版命名
若倉庫層級較深、文檔篇幅偏大,或者團隊還在從其他工具的規範文件過渡,可在 ~/.codex/config.toml(完整配置見 /guides/codex-config-toml-complete-guide)中補上這兩項官方參數:
toml
# 調高所有層級指令文件的累計字節上限(預設 32768 即 32 KiB)
project_doc_max_bytes = 65536
# 目錄中不存在 AGENTS.override.md 與 AGENTS.md 時的備選回退文件名
project_doc_fallback_filenames = ["CLAUDE.md", "TEAM_GUIDE.md"]

圖:本站根據 OpenAI Codex 官方文檔:Configuration Reference 整理的示意圖
訂閱與帳號準備提示:把多層目錄規則梳理乾淨能顯著減少模型返工,但在大倉多模組迭代時仍建議提前規劃好訂閱額度(配額說明見 /guides/codex-usage-limits)。個人主力開發如 Plus 額度緊張,可在本站升級 ChatGPT Pro 充值 或選擇 ChatGPT Pro 20x 檔位;新註冊帳號若在手機短訊核驗受阻,也可查看 Codex 註冊手機驗證服務。
三、如何核驗指令是否真正生效、有沒有被截斷
配完規則後不要靠猜,用下面兩個檢查動作就能立刻確認(新手梳理陌生項目指令可一併參考 /guides/codex-onboard-unfamiliar-project-agents-md):
- 在 TUI 會話內輸入
/status:查看當前會話已加載的指令文件清單,確認目標AGENTS.override.md出現在列表中,且同目錄的AGENTS.md已按預期被替換。 - 排查深層目錄未加載的三大原因:一是某份
AGENTS.override.md是空文件(空白文件會被忽略,從而回落到AGENTS.md);二是根文件太大吃光了預設的 32 KiB 預算,把深層文件直接擠掉;三是啟動codex時所在的工作目錄(pwd)還在倉庫根而不在子目錄裏,導致子目錄的指令尚未被路徑掃描覆蓋到。
常見問題
問:如果我在根目錄放了一個空的 AGENTS.override.md,能不能起到「完全禁用原 AGENTS.md」的效果?
答:不能。按官方文檔,空文件會被跳過,Codex 會繼續向下尋找並加載同目錄的 AGENTS.md。若想臨時屏蔽原目錄規則,需在 AGENTS.override.md 中至少寫入一行非空說明(例如寫明本次會話僅遵循對話內即時指令)。
問:~/.codex/AGENTS.override.md 放着長期不用忘了刪,會有什麼後果?
答:它會持續替換你的全局 ~/.codex/AGENTS.md,且對所有項目生效。本站建議全局層盡量只維護常規 AGENTS.md,把 AGENTS.override.md 嚴格限定為項目本地的短期覆蓋手段,任務結束即刪除。
問:國內沒有外幣信用卡,或者公司團隊需要增值稅發票報銷,怎麼開通能跑 Codex 的訂閱?
答:可通過本站 AI 會員充值總覽 按需選購 ChatGPT Plus或高配額 ChatGPT Pro,團隊統一部署可了解 ChatGPT Business 團隊定製。支持支付寶、微信支付及 AlipayHK,支持自助兌換無需交出帳號密碼,並可開具增值稅發票;實時價格以商品頁展示為準,售後遵循掉訂閱按剩餘天數折退、封號不在質保範圍的政策。
相關教學
- Codex AGENTS.md 怎麼讀取與生效機制詳解
- Codex Memories 記憶功能怎麼用:與 AGENTS.md 的區別
- 陌生代碼庫怎麼快速寫好第一版 AGENTS.md
- Codex config.toml 配置文件完整指南
參考資料
- OpenAI Codex 官方文檔:Custom instructions with AGENTS.md — https://learn.chatgpt.com/docs/agent-configuration/agents-md
- OpenAI Codex 官方文檔:Configuration Reference — https://learn.chatgpt.com/docs/config-file/config-reference
- OpenAI Codex 官方文檔:Projects — https://learn.chatgpt.com/docs/projects
- OpenAI Developers 文檔:Codex Configuration Reference — https://developers.openai.com/codex/config-reference
0 條評論
還沒有評論,來搶沙發~