HoRain 云小助手个人主页⛺️生活的理想就是为了理想的生活!⛳️ 推荐前些天发现了一个超棒的服务器购买网站性价比超高大内存超划算忍不住分享一下给大家。点击跳转到网站。目录⛳️ 推荐什么是 AGENTS.mdCodex 如何发现指南三层加载机制第一步创建全局配置创建配置目录编写全局约定验证配置是否生效第二步按仓库分层配置添加仓库级约定为子目录添加覆写完整目录结构验证加载顺序高级选项自定义文件名切换配置目录验证与调试快速检查开启详细日志常见问题排查AGENTS.md 是 Codex 的自定义指令文件允许你为 Codex 设置全局指导和工作流规范。本节详细介绍如何创建和使用 AGENTS.md。什么是 AGENTS.mdCodex 在启动时会自动读取AGENTS.md文件通过「全局配置 项目级覆写」的层级机制让每次任务都能继承一致的工作约定无论你打开的是哪个代码仓库。AGENTS.md 是 Codex 在执行任何工作之前读取的指令文件允许你设置全局编码规范定义项目特定的工作流程为不同目录提供不同的指导标准化团队的开发实践通过 AGENTS.md你可以确保 Codex 在整个代码库中遵循一致的规范。Codex 如何发现指南Codex 按以下优先级构建指令链。三层加载机制层级加载规则说明全局层读取~/.codex/AGENTS.override.md若不存在则读取~/.codex/AGENTS.md只取第一个非空文件项目层从 Git 根目录逐级向当前目录扫描每层依次检查AGENTS.override.md→AGENTS.md→project_doc_fallback_filenames中的备选文件名合并层从根到叶依次拼接越靠近当前目录的文件出现越晚优先级越高合并后的总大小上限默认为 32 KiB由project_doc_max_bytes控制超出部分会被截断。第一步创建全局配置全局配置作用于所有项目适合放通用工作约定。创建配置目录mkdir -p ~/.codex确保 Codex 主目录存在所有全局配置都放在这个目录下。编写全局约定创建~/.codex/AGENTS.md文件写入所有项目通用的约定# ~/.codex/AGENTS.md ## 全局工作约定 - 修改 JavaScript 文件后始终运行 npm test - 安装依赖时优先使用 pnpm - 新增生产依赖前先请求确认验证配置是否生效运行以下命令Codex 应当回显你写入的条目codex --ask-for-approval never Summarize the current instructions.若需要临时全局覆写可以创建AGENTS.override.md删除该文件即可恢复原始配置。第二步按仓库分层配置项目级文件让 Codex 遵守仓库专属规范同时仍会继承全局配置。添加仓库级约定在项目根目录创建AGENTS.md# AGENTS.md ## 仓库约定 - 提 PR 前运行 npm run lint - 修改公共工具行为时同步更新 docs/ 中的文档为子目录添加覆写对于有特殊需求的子目录如services/payments/创建AGENTS.override.md进行局部覆写# services/payments/AGENTS.override.md ## 支付服务规则 - 使用 make test-payments 替代 npm test - 轮换 API Key 前必须通知安全频道完整目录结构以下是一个典型仓库加载AGENTS.md后的目录布局repo/ ├── AGENTS.md # 仓库级约定加载 └── services/ ├── payments/ │ ├── AGENTS.md # 被跳过override 优先 │ └── AGENTS.override.md # 支付服务覆写加载 └── search/ └── AGENTS.md # 搜索服务约定加载同一目录下AGENTS.override.md存在时同级的AGENTS.md会被跳过。验证加载顺序从子目录启动 Codex查看加载的指令来源codex --cd services/payments --ask-for-approval never \ List the instruction sources you loaded.预期结果依次列出全局文件、仓库根目录文件、支付服务覆写文件。高级选项以下两个功能适用于需要进一步定制指令加载行为的场景。自定义文件名如果项目已有约定俗成的TEAM_GUIDE.md可以在配置文件中追加到回退列表Codex 会把它当作指令文件处理# ~/.codex/config.toml # 追加回退文件名并提高合并上限 project_doc_fallback_filenames [TEAM_GUIDE.md, .agents.md] project_doc_max_bytes 65536修改后每个目录的检查顺序变为AGENTS.override.md→AGENTS.md→TEAM_GUIDE.md→.agents.md取第一个存在的文件。修改配置后需重启 Codex 才能使config.toml的变更生效。切换配置目录通过CODEX_HOME环境变量可以为不同项目或自动化流程使用独立的配置 profileCODEX_HOME$(pwd)/.codex codex exec List active instruction sources此时 Codex 会从当前目录的.codex子目录读取全局配置而非默认的~/.codex。验证与调试以下命令可以快速检查当前生效的指令来源。快速检查# 从仓库根目录检查全局 项目指令 codex --ask-for-approval never Summarize the current instructions. # 从子目录检查嵌套覆写 codex --cd subdir --ask-for-approval never Show which instruction files are active.开启详细日志若需要详细审计指令加载过程可以开启 TUI 日志# 输出 TUI 日志到本地目录 codex -c log_dir./.codex-log # 日志文件位于 ./.codex-log/codex-tui.log常见问题排查下表汇总了配置过程中可能遇到的问题及排查方向。现象排查方向什么都没加载确认文件非空运行codex status检查工作区根目录是否正确出现了错误的指令检查上级目录是否有遗留的AGENTS.override.md回退文件名不生效确认config.toml中拼写无误重启 Codex 使其生效指令内容被截断提高project_doc_max_bytes或将大文件拆分到多级目录Profile 混乱运行echo $CODEX_HOME确认指向的是预期目录❤️❤️❤️本人水平有限如有纰漏欢迎各位大佬评论批评指正如果觉得这篇文对你有帮助的话也请给个点赞、收藏下吧非常感谢! Stay Hungry Stay Foolish 道阻且长,行则将至,让我们一起加油吧