结论先说
- 用
project_doc_fallback_filenames就能免拷贝复用CLAUDE.md。在~/.codex/config.toml或受信任仓库的.codex/config.toml顶层加入project_doc_fallback_filenames = ["CLAUDE.md"],Codex 在找不到AGENTS.md时就会自动回退加载它。 - 回退是「逐级目录独立判断」而非全仓二选一。Codex 从仓库根目录向下遍历到当前工作目录时,每一层都按
AGENTS.override.md→AGENTS.md→ 回退文件名列表的顺序只取命中的首个非空文件。 - 总长度受
project_doc_max_bytes约束。全局配置与各级目录拼接后的指令总字节数默认上限为 32768 字节(32 KiB),复用篇幅较长的团队文档时可按需适度调大,但不要无限制塞入整本手册。 - 回退名单越精简越好。如果把冗长的
README.md放到回退列表里,容易在每个子目录把营销介绍、安装徽章一起读进上下文,拖慢响应并挤占有效工作窗口。 - 在多仓库高频运行 Codex 规则校验与重构建议配足额度。国内用户如无外币支付渠道,可在本站自助开通 ChatGPT Plus 或配额更高的 ChatGPT Pro,多人研发团队统一规范部署也可查看 ChatGPT Business 团队定制。

图:本站根据 OpenAI Codex 官方文档:AGENTS.md 整理的示意图
本文根据 OpenAI Codex 官方文档《Custom instructions with AGENTS.md》《Configuration Reference》整理,资料核对于 2026-11-19。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 OpenAI 官方网站。
适用于谁
- 仓库里原本已经长期维护
CLAUDE.md、.github/copilot-instructions.md或TEAM_GUIDE.md,不想重复拷贝一份AGENTS.md的开发者; - 团队成员同时使用 Codex、Claude Code 等多款编程助手,希望维持「单一规则源」减少文档漂移的研发团队;
- 接手历史大型代码库,希望 Codex 启动时自动吸收既有开发规范与架构约定的工程师。
一、project_doc_fallback_filenames 的精确加载顺序
在默认情况下,Codex 只认两类项目指令文件名:AGENTS.override.md 和 AGENTS.md(完整的层级合并机制可先看 /guides/codex-agents-md-how-it-reads 与 /guides/codex-agents-override-md-hierarchy-priority)。但现实里很多团队早期已经沉淀了非常完善的 CLAUDE.md 或 DEV_RULES.md,如果手动复制一份 AGENTS.md,几周后两份文档就会各改各的、互相打架。
配置 project_doc_fallback_filenames 后,Codex 在扫描「仓库根 → 中间父目录 → 当前工作目录」的每一层时,按以下严格顺序挑选该层的唯一有效规则文件:
- 首先检查该目录是否存在非空的
AGENTS.override.md; - 若不存在,再检查该目录是否存在非空的
AGENTS.md; - 若前两者都缺失,才按照
project_doc_fallback_filenames数组里从左到右的顺序依次查找,命中第一个存在且非空的文件即停止本层查找; - 所有层级命中的文件自顶向下拼接,连同用户主目录
~/.codex/AGENTS.md(或AGENTS.override.md)一起注入会话上下文。
这意味着一个非常灵活的共存模式:仓库根目录可以直接复用现有的 CLAUDE.md,而某个只需要给 Codex 单独补充沙箱或测试命令的子目录,放一个 AGENTS.md 就能在该层优先接管,不需要动团队原有文件结构。
二、实战配置模板与 project_doc_max_bytes 调优
打开全局配置文件 ~/.codex/config.toml(Windows 位于 %USERPROFILE%\.codex\config.toml),或在受信任项目内新建 .codex/config.toml(配置文件总览见 /guides/codex-config-toml-complete-guide)。
模板 1:全局复用 CLAUDE.md 与团队约定文档
toml
#:schema https://developers.openai.com/codex/config-schema.json
# 当目录内没有 AGENTS.override.md 和 AGENTS.md 时,按顺序回退查找
project_doc_fallback_filenames = ["CLAUDE.md", "TEAM_GUIDE.md", ".agents.md"]
# 默认上限 32768 字节(32 KiB);多级 Monorepo 文档偏长时可酌情上调
project_doc_max_bytes = 65536
模板 2:临时单次命令行覆盖测试
在修改全局 config.toml 之前,可以用 -c 覆写参数快速验证目标文档是否真的被读入,避免写错文件名或路径层级:
bash
codex -c 'project_doc_fallback_filenames=["CLAUDE.md","CONTRIBUTING.md"]' \
"请列出你在本次会话中读取到的项目构建命令与代码规范要点"
如果返回内容准确引用了 CLAUDE.md 里的测试命令与目录约束,说明回退链路已经跑通。

图:本站根据 OpenAI Codex 官方文档:Configuration Reference 整理的示意图
订阅与账号准备提示:在 Monorepo 里开启多级项目规则并持续执行长对话重构时,每轮请求都会携带系统指令与代码片段,额度消耗节奏比轻度问答更快(限额机制参考 /guides/codex-usage-limits)。若高频遇到额度受限,可在本站升级 ChatGPT Pro 充值 或支持自动续订的 ChatGPT Pro 5x iOS 可覆盖档;新注册 OpenAI 账号若在手机号环节受阻,可查看 Codex 注册手机验证服务。
三、多工具共存避坑清单(本站建议)
把 CLAUDE.md 直接喂给 Codex 虽然省事,但两个工具的命令体系与工具名并不完全一致,落地前建议检查以下四点:
- 剔除或隔离工具专属指令。如果旧
CLAUDE.md里写死了特定工具的斜杠命令或私有插件名称,建议在文档里分出「通用工程规范」和「工具专属说明」两段,或把通用部分抽成共享规范文件(跨工具单一规则源设计思路见 /guides/claude-md-agents-md-cursor-rules-single-source)。 - 慎把
README.md塞进回退列表。不少开源项目的README.md动辄上万字节,充斥徽章链接、更新日志和截图说明,放进回退列表不仅容易撑爆project_doc_max_bytes导致后半段关键规范被截断,还会白白消耗每轮上下文 Token。 - 留意项目级
.codex/config.toml的信任前提。团队如果把project_doc_fallback_filenames写进仓库内的.codex/config.toml随代码提交,成员首次拉取仓库时必须先确认信任该目录,否则项目级配置不会生效。 - 控制单文件体积与层级深度。本站建议将回退数组保持在 2 到 3 个高信噪比文件名内,并把核心规则(目录边界、单测命令、禁止修改区域)放在文件最靠前的位置,这样即便多级拼接接近字节上限,关键硬约束也不会被截掉。
常见问题
问:仓库里同时存在 AGENTS.md 和 CLAUDE.md 时,Codex 会把两个文件合并读取吗?
答:不会合并。同一目录层级内只要找到了非空的 AGENTS.override.md 或 AGENTS.md,Codex 就会直接采用它,不再继续触发该层的 project_doc_fallback_filenames 回退查找。
问:写了 project_doc_fallback_filenames = ["docs/rules.md"] 带子目录路径怎么不生效?
答:该参数按设计匹配的是目录内的「文件名」而不是多层相对路径。如果团队文档放在 docs/ 下,更稳妥的做法是在根目录放置一个精简的 AGENTS.md 指向核心约束,或在 CLAUDE.md / 根目录文件名中保持同层命名。
问:国内没有外币信用卡,或者公司团队需要开增值税发票报销,怎么开通能跑 Codex 的订阅?
答:可在本站 AI 会员充值总览 按需选购 ChatGPT Plus、ChatGPT Plus 官网直充 或高配额的 ChatGPT Pro,团队多人采购可直接查看 ChatGPT Business 团队定制。支持支付宝、微信支付与 AlipayHK,自助兑换无需交出账号密码,并可开具增值税发票;实时价格以商品页为准,售后执行掉订阅按剩余天数折退、封号不在质保范围的政策。
相关教程
- Codex AGENTS.md 读取机制与分层合并规则详解
- Codex AGENTS.override.md 多层优先级覆盖规则说明
- CLAUDE.md、AGENTS.md 与 Cursor Rules 单一规则源维护方案
- Codex config.toml 配置文件完整指南
参考资料
- OpenAI Developers 文档:Custom instructions with AGENTS.md — https://developers.openai.com/codex/guides/agents-md
- OpenAI Developers 文档:Codex Configuration Reference — https://developers.openai.com/codex/config-reference
- OpenAI Codex 官方文档:Configuration Reference — https://learn.chatgpt.com/docs/config-file/config-reference
- OpenAI Codex GitHub 仓库 — https://github.com/openai/codex
0 条评论
还没有评论,来抢沙发~