24 · 自定义回退文件名与配置切换
概述
AGENTS.md 是 Codex 的默认项目指令文件名，但并非所有团队都希望使用这个名称。有些团队已经有了内部的开发指南文档（如TEAM_GUIDE.md），有些团队则希望使用更隐蔽的文件名（如.agents.md），还有些团队需要在不同的工作场景之间切换不同的配置集。
Codex 提供了三大配置灵活性机制来解决这些问题：
project_doc_fallback_filenames：自定义回退文件名列表project_doc_max_bytes：调整加载大小上限CODEX_HOME环境变量 + 多 Profile 管理：在配置目录间切换
本文将逐一深入解析这些机制，并提供完整的使用案例。
自定义回退文件名
为什么需要自定义文件名？
在实际使用中，你可能遇到以下这些情况：
- 团队已有文档规范：你所在的团队已经有
TEAM_GUIDE.md或CODING_STANDARDS.md作为开发指南。你不希望再增加一个AGENTS.md文件造成混乱。 - 多工具兼容：你的项目同时使用多个 AI 辅助工具，不同工具有不同的配置文件命名约定。通过自定义回退文件名，可以让同一个 Markdown 文件被多个工具识别。
- 减少根目录文件数量：项目根目录已经有很多配置文件（
README.md、CONTRIBUTING.md、CHANGELOG.md等），你希望将 AI 指令放在一个不那么显眼的文件名下。 - 历史遗留兼容：从其他工具迁移到 Codex，你希望保持已有的文件名不受影响。
配置项：project_doc_fallback_filenames
project_doc_fallback_filenames是一个列表配置项，用来指定当 Codex 在当前目录找不到AGENTS.md时，应该依次尝试哪些备选文件名。
默认值（实际上等于只使用AGENTS.md）：
{"project_doc_fallback_filenames":[]}自定义配置示例：
{"project_doc_fallback_filenames":["TEAM_GUIDE.md",".agents.md","CODING_STANDARDS.md"]}回退查找逻辑
当 Codex 启动并在某个目录寻找指令文件时，它按以下顺序查找：
- 首先查找
AGENTS.md（标准文件名，始终优先） - 如果不存在，依次查找
project_doc_fallback_filenames列表中的每个文件名 - 找到第一个存在的文件后，停止查找并使用该文件
- 如果所有文件都不存在，该目录没有指令文件
注意：project_doc_fallback_filenames仅在AGENTS.md不存在时生效。如果AGENTS.md存在，它永远被优先使用，不会去查找回退文件名。
完整配置方法
在~/.codex/config.json中设置：
{"project_doc_fallback_filenames":["TEAM_GUIDE.md",".agents.md"
