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/api，Key 在控制台生成。
具体操作路径是这样的：先到控制台创建 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/api，api_key_env对应的环境变量已导出，tool_calls = true。如果还是失败，去接入文档核对当前模型是否支持工具调用。
排查顺序建议从通道开始，再到权限，最后到规则归位。通道不通，后面全是空谈；权限不对，改了也白改；归位错了，规则体系会慢慢腐化。
7. 把自维护接进日常工作流
这套流程跑顺之后，我基本不再手写SKILL.md。任务做完，顺手触发一次复盘，规则就自己归位了。但有几件事仍然必须由人判断：这条经验是不是长期成立、作用域是不是划对了、能不能被触发、有没有验证方式。AI 负责搜索、归纳和写入，人负责判断规则的边界。
如果你刚开始搭这套体系，建议先从最小闭环做起：只维护一个仓库AGENTS.md和一个基础 Skill，跑通「触发 → 归位 → 写入 → 验证」四步，再逐步加专项 Skill。规则体系的价值不在于多，而在于每条规则都有唯一负责人、都能被命中、都经得起验证。
接入和 Key 管理走统一通道，配置和文档在控制台和接入文档里都能找到；想先验证模型对规则的理解能力，可以直接在模型对话里试；如果要把这套自维护流程长期挂在编码和 Agent 任务上，Coding Plan 更适合承载这种持续性的工作流。
