24-自定义回退文件名与配置切换

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_filenamesproject_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"