结论先说
- 同一目录下,
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 条评论
还没有评论,来抢沙发~