1. 为什么我想让 Codex 自己维护 AGENTS.md 和 Skill长期用 Codex 做项目的人大概率都经历过同一个尴尬每次开新会话都要重新解释一遍项目结构、编码习惯、哪些目录不能动、测试该写到什么粒度。解释完一轮任务还没开始上下文已经烧掉一半。更麻烦的是这些规则明明上次已经说清楚了只是没被持久化下来。我一开始的做法是手写一份越来越长的提示词把所有规则堆进去。结果就是提示词膨胀到几千字Codex 每次都要读一遍真正关键的约束反而被淹没。后来我把规则拆成两层仓库里的AGENTS.md放团队硬规则~/.codex/AGENTS.md放我个人的路由习惯再把领域知识拆成一个个 Skill。这套分层确实好用了但新的问题来了——规则会漂移。代码改了Skill 里引用的路径过期了新加了一个专项 Skill上层路由却没登记两个 Skill 开始说同一件事改一处要同步三处。我真正想要的不是「写一份完美的规则文档」而是让 Codex 在每次任务结束后自己把这次踩到的坑、纠正过的做法归位到正确的文件里。规则应该从真实任务里长出来而不是靠我提前想象。这篇就交付一套可复制的config.toml骨架以及一次完整的自维护流程触发 Codex 更新AGENTS.md和 Skill然后验证它到底改对了没有。2. 前置统一 Key 与 API 通道让 Codex 稳定接入要让 Codex 具备「读写本地规则文件」的能力前提是它得先能稳定地跑起来并且在一个会话里能连续执行多步操作——读文件、改文件、再读回来确认。如果接入通道不稳定自维护流程做到一半断掉规则文件可能停在半改状态比不改还糟。我现在的做法是通过统一通道接入把 Key 和 API 地址集中管理不散落在各个工具的配置里。这样换模型、换工具时只需要改一处。接入地址用https://taotoken.net/apiKey 在控制台生成。具体操作路径是这样的先到控制台创建 API Key然后按接入文档把 Codex 的配置指向统一通道。这里有个细节值得说Codex 的配置文件和普通聊天工具不一样它需要的是能支撑多轮工具调用的通道而不是单轮问答。所以配置里要确认模型名、base_url、以及是否允许工具调用这几项。我试过把 Key 直接写死在项目里的config.toml后来发现一旦要换环境就得改代码很别扭。现在改成从环境变量读取config.toml里只留变量名。这样仓库里的配置可以提交Key 不会泄露。注意不要把 API Key 提交到 Git 仓库。用环境变量或本地未跟踪的配置文件承载密钥仓库里只保留变量引用。3. 可复制的 config.toml 骨架下面这份骨架是我实际在用的结构脱敏后可以直接抄。它分成四块模型接入、工具权限、规则文件路径、自维护开关。每一块我都标了为什么这么写。# ~/.codex/config.toml # Codex 长期项目配置骨架 [model] # 统一通道接入Key 从环境变量读取不写死 provider openai-compatible base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY model your-model-name # 自维护流程需要多轮工具调用必须开启 tool_calls true max_tool_rounds 12 [tools] # 允许 Codex 读写规则文件这是自维护的前提 allow_file_read true allow_file_write true # 限制写入范围避免它乱改项目源码 write_scope [ AGENTS.md, ~/.codex/AGENTS.md, ~/.codex/skills/**/SKILL.md, ] # 禁止它碰这些防止误伤 deny_paths [ .git/**, **/node_modules/**, **/*.lock, ] [rules] # 两层 AGENTS 的路径Codex 启动时按顺序加载 repo_agents AGENTS.md local_agents ~/.codex/AGENTS.md # Skill 根目录 skills_root ~/.codex/skills [self_maintain] # 自维护开关默认关闭需要时手动触发 enabled false # 任务结束后是否自动复盘 review_after_task true # 复盘时允许修改的文件类型 targets [agents, skill] # 修改前先备份出问题能回滚 backup_before_write true backup_dir ~/.codex/backups几个关键点解释一下。write_scope是这套配置里最重要的安全阀。自维护的本质是让 Codex 改自己的规则文件如果不限制范围它可能顺手把项目源码也改了。我把范围锁死在AGENTS.md和SKILL.md上源码一律不碰。max_tool_rounds设成 12 是经验值。自维护流程通常要经历「读现有规则 → 对比本次任务 → 判断归位 → 写入 → 读回验证」这几步轮数太少会中途截断太多又浪费。12 轮基本够用。backup_before_write一定要开。规则文件被改坏比代码被改坏更难排查因为它影响的是后续所有任务。备份目录按时间戳存回滚就是复制回去的事。配置写完后先别急着开自维护。用一次普通任务验证通道是通的export TAOTOKEN_API_KEY你的Key codex 读取当前目录的 AGENTS.md告诉我里面有几条硬规则如果它能正确读出文件内容并回答说明文件读取和通道都正常。这一步没过后面的自维护不用谈。4. 触发一次自维护让 Codex 更新 AGENTS.md 与 Skill配置就绪后自维护的触发方式不是让它「随便优化一下规则」那样它会漫无目的地改。我的做法是绑定一次真实任务任务做完后立刻复盘。这样提炼出来的经验有具体来源不会变成空泛的教条。假设刚做完一个任务给某个模块加了一个新的错误码并且发现原来的错误处理 Skill 里没有覆盖「用户可见错误」和「内部日志错误」的区分。任务代码已经改完现在触发自维护。第一步把self_maintain.enabled临时改成true然后发这样一段指令刚才的任务已经完成。现在做一次规则复盘按以下步骤执行 1. 读取仓库 AGENTS.md 和 ~/.codex/AGENTS.md列出当前已有的硬规则和路由规则。 2. 读取 ~/.codex/skills 下所有 SKILL.md列出每个 Skill 的职责。 3. 回顾刚才的任务我纠正了什么、哪个判断是重复出现的、哪条经验仅靠搜索不容易稳定得到。 4. 判断这条经验应该归位到哪一层 - 全仓硬规则 - 仓库 AGENTS.md - 我的本地使用习惯 - ~/.codex/AGENTS.md - 领域专项知识 - 对应的 SKILL.md 5. 检查是否与现有规则重复或冲突。如果重复合并到唯一负责人不要新增。 6. 写入前先备份到 ~/.codex/backups。 7. 写入后读回文件确认修改生效并告诉我改了哪个文件的哪一段。这段指令的关键在于第 4 步和第 5 步。第 4 步强制它做归位判断而不是一股脑塞进一个文件。第 5 步强制它先查重避免规则越堆越多。很多人让 AI 写规则失败就是因为少了这两步结果规则文件变成新的垃圾场。Codex 执行时会先读文件然后给出一个归位方案。比如刚才那个错误码任务它可能会判断「用户可见错误与内部日志错误的区分」属于错误治理领域应该更新到alert-error-governance这个 Skill而不是塞进仓库 AGENTS.md。这个判断是对的因为不是所有代码修改都涉及错误语义。如果它的判断是错的比如把领域规则塞进了全仓硬规则你要当场纠正并让它把这次纠正本身也记下来。规则体系的边界也是从纠偏里长出来的。5. 验证检查 AGENTS.md 与 Skill 是否按预期更新写入完成不等于改对了。我每次都会做三层验证缺一层都可能留下隐患。第一层看文件是否真的变了以及变在哪。用 diff 对比备份和当前文件diff -u ~/.codex/backups/AGENTS.md.bak ~/.codex/AGENTS.md diff -u ~/.codex/backups/skills/alert-error-governance/SKILL.md.bak \ ~/.codex/skills/alert-error-governance/SKILL.md预期结果是AGENTS.md没有变化因为这次经验不属于全仓硬规则而alert-error-governance/SKILL.md多了一段关于错误语义区分的说明。如果AGENTS.md被改了说明归位判断出了问题要回滚重来。第二层验证规则能被触发。规则写进去不代表下次任务会加载它。我会开一个新会话发一个相关任务看 Codex 是否主动引用了新规则codex 给用户登录失败加一个错误返回注意错误语义如果它回答时提到「按 alert-error-governance 的约定用户可见错误和内部日志错误要分开」说明规则不仅写进去了还能被路由命中。这一步是很多人忽略的——规则写了但没入口等于没写。第三层检查规则体系本身有没有腐化。隔一段时间我会让 Codex 做一次体检检查 ~/.codex/skills 下所有 Skill 1. 是否存在 Skill 文件但上层 AGENTS.md 的路由里没有列出它 2. 是否有 SKILL.md 引用了已经不存在的路径或文件 3. 是否有两个 Skill 的职责描述高度重叠 只报告问题不要直接修改。实测下来这个体检每次都能查出点东西。最常见的是「专项 Skill 已经建了但路由没登记」导致它永远不会被加载。其次是旧 Skill 还引用着已经重构掉的目录。这些问题不体检根本发现不了因为平时任务能跑通只是没用到那条规则而已。验证通过后把self_maintain.enabled改回false。自维护是手动触发的动作不适合常开否则每次任务结束它都想改规则反而干扰正常开发。6. 常见错误与排查自维护流程跑不顺通常卡在几个固定位置。我把踩过的坑列出来对照排查。错误一Codex 说改了但文件没变。大概率是write_scope没覆盖到目标路径。检查config.toml里的write_scope确认~/.codex/skills/**/SKILL.md这种通配写法被支持。有些版本对**的支持不一致可以改成显式列出具体 Skill 目录。错误二规则被写进了错误的层级。表现是全仓AGENTS.md越来越长塞满了本该属于专项 Skill 的内容。根因是复盘指令里没强调归位判断。回到第 4 节的指令把第 4 步的归位规则写得更明确并让它每次写入前先说明「为什么放这一层」。错误三新规则写了但下次任务不生效。先确认规则文件路径和config.toml里的skills_root一致。再确认上层AGENTS.md的路由里有没有列出这个 Skill。Skill 必须在被选择之前完成路由不能靠 Skill 正文要求自己被加载——这是最容易搞反的一点。错误四两个 Skill 开始说同一件事。这是规则漂移的典型信号。不要继续往两边补文档而是让 Codex 比对后合并到唯一负责人另一个删掉或改成引用。发现重复时合并通常比补充更正确。错误五自维护跑到一半中断文件停在半改状态。这就是backup_before_write存在的意义。从~/.codex/backups找到最近一次备份复制回去然后检查是不是max_tool_rounds太小导致截断。适当调大或者把复盘任务拆成「先出方案、再执行」两步。错误六通道报错工具调用失败。自维护依赖多轮工具调用如果通道不支持或配置里tool_calls没开流程会在第一步就断。确认base_url指向https://taotoken.net/apiapi_key_env对应的环境变量已导出tool_calls true。如果还是失败去接入文档核对当前模型是否支持工具调用。排查顺序建议从通道开始再到权限最后到规则归位。通道不通后面全是空谈权限不对改了也白改归位错了规则体系会慢慢腐化。7. 把自维护接进日常工作流这套流程跑顺之后我基本不再手写SKILL.md。任务做完顺手触发一次复盘规则就自己归位了。但有几件事仍然必须由人判断这条经验是不是长期成立、作用域是不是划对了、能不能被触发、有没有验证方式。AI 负责搜索、归纳和写入人负责判断规则的边界。如果你刚开始搭这套体系建议先从最小闭环做起只维护一个仓库AGENTS.md和一个基础 Skill跑通「触发 → 归位 → 写入 → 验证」四步再逐步加专项 Skill。规则体系的价值不在于多而在于每条规则都有唯一负责人、都能被命中、都经得起验证。接入和 Key 管理走统一通道配置和文档在控制台和接入文档里都能找到想先验证模型对规则的理解能力可以直接在模型对话里试如果要把这套自维护流程长期挂在编码和 Agent 任务上Coding Plan 更适合承载这种持续性的工作流。