1. 从焚决这个说法聊起Codex 这次到底更新了什么焚决这个词在圈子里流传开来的时候我第一反应是——又是一个被过度包装的营销词。但把最近围绕 Codex 的一系列变化捋了一遍之后我承认这次的动静确实不小。所谓焚决说白了就是一套把 Codex 从能写代码的聊天框改造成能自己调度工具、自己管理上下文、自己完成多步任务的智能体的配置方法论。核心抓手就是三个东西AGENTS.md、Skills以及围绕它们建立起来的一整套工作流。如果你之前只是把 Codex 当成一个补全工具或者偶尔问问代码问题那这次的变化值得你重新认识它。因为 AGENTS.md 和 Skills 的组合本质上是在解决一个老问题大模型很聪明但它不知道你的项目长什么样、你的规范是什么、你希望它按什么流程干活。过去我们靠一遍遍在对话里重复用 TypeScript 严格模式测试文件放tests目录提交前跑 lint现在这些都可以固化下来变成模型每次启动就自动读取的上下文。这篇文章适合三类人看一是刚接触 Codex、还在纠结怎么安装配置的新手二是已经在用但总觉得它不够听话的中级用户三是想自己写 Skills、把团队规范沉淀下来的进阶玩家。我会从概念讲到实操从安装讲到 Skills 开发中间穿插我自己踩过的坑。不吹不黑只讲能落地的东西。先说清楚一个前提Codex、Claude Code 这类工具的本质都是带工具调用能力的编码智能体。它们能读文件、写文件、跑命令、搜索代码库区别在于上下文管理策略、工具集设计和扩展机制。AGENTS.md 和 Skills 就是 Codex 这一侧的扩展机制理解了这一点后面所有内容都好懂了。2. AGENTS.md 到底是什么给模型看的项目说明书2.1 它和 README 的根本区别很多人第一次听说 AGENTS.md会下意识觉得这不就是给 AI 看的 README 吗。方向对但定位完全不同。README 是写给人看的讲的是项目是什么、怎么跑起来、怎么贡献。AGENTS.md 是写给模型看的讲的是你在这个仓库里干活时必须遵守哪些规则、知道哪些背景、避开哪些雷区。举个具体的例子。README 里会写本项目使用 pnpm 作为包管理器这是给人看的说明。而 AGENTS.md 里会写禁止使用 npm 或 yarn 安装依赖一律使用 pnpm新增依赖前先检查 package.json 是否已存在同名包不要擅自升级已有依赖的版本号。看出来了吗前者是陈述事实后者是行为约束。模型需要的是后者。我在自己的项目里放了一份 AGENTS.md 之后最直观的感受是模型不再动不动就npm install了也不再自作主张地把某个库从 3.2 升到 4.0 然后引发一堆 breaking change。这些看似琐碎的约束累积起来能省掉大量返工。2.2 一份能用的 AGENTS.md 应该包含哪些块我摸索下来一份实用的 AGENTS.md 大致分这么几块你可以按需增减项目概览一两句话说清楚这是个什么项目、技术栈是什么。别写太长模型不需要读你的创业故事。目录结构约定哪些目录放什么。比如src/放源码、tests/放测试、scripts/放脚本。模型据此判断新文件该放哪。编码规范命名风格、缩进、是否用分号、导入顺序。这些如果项目里有 ESLint/Prettier 配置直接说遵循现有 lint 配置即可不用重复。命令清单装依赖、跑测试、构建、启动开发服务器分别用什么命令。这是模型最需要的硬信息。禁区哪些文件不要动、哪些操作不要做。比如不要修改migrations/下的历史迁移文件不要提交.env。提交规范commit message 格式、是否需要关联 issue 号。我见过有人把 AGENTS.md 写成几千字的长文结果模型反而不太买账——上下文是有限的塞太多无关信息会稀释真正重要的约束。我的建议是控制在 100 到 300 行之间只写模型真正需要知道的。2.3 一个真实的 AGENTS.md 片段下面这段是我某个前端项目里实际在用的你可以参考这个颗粒度# AGENTS.md ## 项目概览 React 18 TypeScript Vite 的组件库项目使用 pnpm 管理依赖。 ## 命令 - 安装依赖pnpm install - 开发pnpm dev - 测试pnpm testVitest - 构建pnpm build - 类型检查pnpm typecheck ## 目录约定 - src/components/ 每个组件一个目录含 index.tsx 和 index.test.tsx - src/hooks/ 自定义 hooks - src/utils/ 纯函数工具 ## 规范 - 组件一律使用函数式 hooks禁止 class 组件 - 导出使用具名导出禁止 default export除页面级组件 - 所有 props 必须有显式类型定义禁止 any - 样式使用 CSS Modules文件名 xxx.module.css ## 禁区 - 不要修改 src/legacy/ 下的任何文件 - 不要升级 react 和 react-dom 的主版本 - 不要引入新的 UI 库现有组件优先复用这份文件放进去之后模型生成代码的返工率肉眼可见地下降了。以前它总爱用 default export现在基本不会了。2.4 AGENTS.md 和 CLAUDE.md 的关系热词里同时出现了 AGENTS.md 和 CLAUDE.md很多人搞不清这俩的关系。简单说CLAUDE.md 是 Claude Code 的约定文件名AGENTS.md 是更通用的、被多个工具采纳的约定。有些工具会优先读 AGENTS.md有些读自己专属的文件名。实际使用中如果你同时用多个工具可以维护一份主文件然后用软链接或者简单复制让各个工具都能读到。我自己的做法是以 AGENTS.md 为准如果某个工具只认自己的文件名就建一个软链接指过去。这样规范只有一份改一处全生效不会出现改了 A 忘了改 B的尴尬。3. Skills 机制拆解把重复劳动打包成可复用的能力3.1 Skills 解决的核心痛点如果说 AGENTS.md 解决的是模型不知道项目背景的问题那 Skills 解决的就是模型不知道怎么做某件具体的事的问题。这两者经常被混为一谈其实分工很清晰。打个比方AGENTS.md 像是给新员工的《员工手册》告诉他公司规矩、办公区在哪、报销流程怎么走。Skills 则像是《岗位操作手册》告诉他做月度报表这件事具体分几步、每步用什么工具、输出成什么格式。举个我自己的例子。我经常需要把一段 Markdown 转成排版规范的 LaTeX。以前每次都要在对话里描述一遍用 article 文档类、中文用 ctex、代码用 listings 宏包、页边距 2.5cm……说一次两次还行说十次就烦了。后来我把这套流程写成了一个 Skill之后只要说用 latex 排版这个文档模型就自动按我预设的模板走一步到位。3.2 Skills 的目录结构和文件格式Skills 通常是一个目录里面至少有一个描述文件一般是SKILL.md或类似名字可能还带一些辅助脚本、模板文件。描述文件一般包含两部分元信息名字、描述、触发条件和正文指令具体怎么做。一个典型的 Skill 目录长这样skills/ latex-typesetting/ SKILL.md templates/ article.tex scripts/ build.shSKILL.md的头部通常是 YAML 格式的元信息下面是指令正文。大致结构如下--- name: latex-typesetting description: 将 Markdown 内容排版为规范的中文 LaTeX 文档 --- ## 使用场景 当用户要求把文档排版成 LaTeX 或 PDF 时使用本技能。 ## 步骤 1. 读取用户提供的 Markdown 内容 2. 使用 templates/article.tex 作为基础模板 3. 中文使用 ctex 宏包代码块用 listings 4. 页边距设为 2.5cm 5. 生成 .tex 文件后调用 scripts/build.sh 编译 ## 注意事项 - 特殊字符 % $ # _必须转义 - 代码块要指定语言否则 listings 无法高亮关键点在于description 字段。模型是根据这个描述来判断当前任务要不要调用这个 Skill的所以描述要写得准确、具体既不能太宽泛导致误触发也不能太窄导致该用的时候用不上。3.3 触发机制模型怎么知道该用哪个 Skill这是很多人困惑的地方。Skills 不是靠关键词硬匹配的而是模型读了所有 Skill 的 description 之后根据当前任务语义判断该调用哪个。所以 description 的写法直接决定了 Skill 的命中率。我踩过的坑一开始我把某个 Skill 的 description 写成处理文档相关任务结果它在我做任何跟文件有关的事情时都被触发非常烦。后来改成将 Markdown 转换为带目录、页眉页脚、代码高亮的 PDF 文档命中就精准多了。提示description 里最好包含什么时候用和产出什么两个信息模型判断起来更准。3.4 常用 Skills 类型盘点从热词看大家关心的 Skills 类型集中在几个方向我按自己的使用频率排一下Skill 类型典型用途使用频率代码规范类按团队规范生成/重构代码极高文档排版类Markdown 转 LaTeX/PDF/Word高测试生成类根据源码自动生成单测高图片生成类调用绘图能力产出配图中数据处理类清洗、转换、分析数据中建模辅助类数学建模的公式推导与求解中代码规范类和文档排版类是我用得最多的因为它们对应的任务重复度最高固化下来收益最大。4. 从零把 Codex 跑起来安装、登录与首次配置4.1 安装路径的选择Codex 的安装方式取决于你用哪个平台。命令行版本一般通过包管理器安装桌面版则有独立的安装包。我两个都用过说下区别。命令行版胜在轻量、可脚本化适合已经习惯终端工作流的人。桌面版胜在开箱即用、图形化配置适合不想折腾环境的人。如果你是在 Windows 上桌面版会省掉不少配置麻烦如果你在 macOS 或 Linux 上命令行版体验更顺。安装完之后第一件事是验证版本确认装的是最新的codex --version如果提示命令找不到八成是 PATH 没配好。Windows 上常见于用包管理器装完之后没重开终端macOS/Linux 上常见于全局 bin 目录不在 PATH 里。这个坑很基础但很常见。4.2 登录与认证登录环节是新手最容易卡住的地方。热词里出现了codex auth token is unavailable和codex 打不开我猜不少人在这栽过跟头。认证失败通常有几个原因一是网络环境导致认证请求发不出去二是本地缓存的 token 过期或损坏三是配置文件里的认证信息格式不对。排查顺序建议是先确认网络能正常访问认证服务再检查本地配置目录下的认证文件最后考虑清掉缓存重新登录。# 查看配置目录不同系统路径不同 # macOS/Linux 通常在 ~/.config 或 ~/.codex # Windows 通常在 %APPDATA%清缓存重登这个操作能解决相当一部分莫名其妙打不开的问题。我遇到过好几次都是删掉本地认证缓存后重新登录就好了。4.3 首次配置把 AGENTS.md 和 Skills 目录挂上装好登录好之后别急着让它写代码。先做两件配置一是把 AGENTS.md 放到项目根目录二是把 Skills 目录配置到工具能识别的位置。AGENTS.md 的位置一般是项目根目录模型启动时会自动读取。Skills 目录则需要在配置里指定路径或者放到约定的默认目录下。具体路径各版本可能不同建议查一下当前版本的文档确认。配置好之后做个验证随便问一个跟项目规范有关的问题比如这个项目用什么包管理器如果模型能准确回答说明 AGENTS.md 读进去了。4.4 接入其他模型以 DeepSeek 为例热词里有codex 接入 deepseek说明不少人想换后端模型。这类工具通常支持配置自定义的模型端点。配置的核心是填对 API 地址、模型名和密钥。这里要提醒一句不同模型对工具调用的支持程度不一样。有些模型原生支持 function calling接进来就能用有些需要额外的适配层。接入之前先确认目标模型是否支持工具调用否则会出现能聊天但不能干活的情况。配置大致长这样具体字段名以实际版本为准# 示例配置字段名请以官方文档为准 [model] provider custom base_url 你的模型服务地址 model 模型名称 api_key 你的密钥注意密钥不要硬编码在会提交到仓库的文件里用环境变量或者本地不纳入版本控制的配置文件。5. 写一个自己的 Skill从需求到落地5.1 先判断这件事值不值得做成 Skill不是所有事都值得做成 Skill。我的判断标准是三条重复频率高不高、步骤是否固定、有没有容易出错的细节。三条都满足才值得固化。比如生成一个 React 组件这件事重复频率极高但步骤不够固定每个组件需求不同做成 Skill 收益有限。而把组件按团队规范格式化这件事步骤固定、细节多导出方式、类型定义、样式方案做成 Skill 就很值。5.2 拆解步骤把我会做变成模型能照着做写 Skill 最难的一步是把你自己习以为常的操作拆成模型能执行的明确步骤。因为很多细节你做得太熟练已经意识不到自己在做了。我的方法是自己完整做一遍边做边记把每个决策点都写下来。比如排版 LaTeX 时我会下意识地转义特殊字符、指定代码语言、设置页边距——这些如果不写进 Skill模型就不会做。拆解完之后按输入 → 处理步骤 → 输出 → 注意事项的结构组织。步骤要具体到可执行注意事项要覆盖你踩过的坑。5.3 一个完整的 Skill 示例Markdown 转规范 PDF下面这个 Skill 是我实际在用的简化版展示一下完整结构--- name: md-to-pdf description: 将 Markdown 文档转换为带目录、代码高亮、规范页边距的 PDF --- ## 触发条件 用户要求把 Markdown 转成 PDF或要求排版成文档时使用。 ## 输入 - 一个 Markdown 文件路径或直接粘贴的 Markdown 内容 ## 步骤 1. 检查内容中的特殊字符 % $ # _ { }在 LaTeX 中转义 2. 使用 ctexart 文档类设置 2.5cm 页边距 3. 一级标题生成目录代码块用 listings 宏包并指定语言 4. 生成 .tex 文件调用 xelatex 编译两次第二次为了目录页码正确 5. 输出 PDF 路径给用户 ## 注意事项 - 中文字体必须用 xelatex 编译pdflatex 会乱码 - 代码块没指定语言时默认按 text 处理并提示用户 - 编译报错时把 .log 文件的关键错误行提取出来给用户看这个 Skill 写完之后我排版文档的时间从每次十几分钟降到了几十秒。5.4 调试 Skill 的实用技巧Skill 写完不是就完事了得调试。我的调试流程是先拿一个最简单的输入测确认基本流程能跑通再拿一个边界情况的输入测看注意事项有没有覆盖到最后拿一个真实复杂输入测看会不会崩。调试时最常见的两类问题一是 description 写得太模糊导致不触发二是步骤写得太笼统导致模型自由发挥。前者改 description后者把步骤写细。提示可以在 Skill 里加一段如果遇到 X 情况先问用户确认避免模型在信息不足时瞎猜。6. 那些让人抓狂的报错排查链路实录6.1 cc switch local proxy failed 这类报错热词里出现了cc switch local proxy failed while handling codex endpoint /responses这是个典型的代理转发失败。虽然我不能展开讲网络配置的细节但排查思路可以分享。这类报错通常指向请求在转发环节出了问题。排查顺序先确认本地服务是否正常启动再确认目标端点地址是否写对最后看日志里具体的失败原因。日志是关键别只看表面的报错信息往下翻通常有更具体的错误码。我遇到过一次表面报错是转发失败实际原因是配置文件里端点地址末尾多了个斜杠导致路径拼接错误。这种细节不看日志根本发现不了。6.2 model is not supported 的应对热词里有the gpt-5.6-sol model is not supported when using codex with a...这类报错的意思是你配置的模型名当前工具版本不认。原因一般有两个一是模型名拼写错误或用了不存在的名字二是工具版本太旧不认识新模型。解决办法先核对模型名的准确拼写再检查工具是否需要升级。这里有个经验模型名是大小写敏感的而且经常带版本后缀。少一个字符、错一个大小写都会报这个错。复制粘贴比手打靠谱。6.3 认证相关的疑难杂症codex auth token is unavailable这个报错前面提过核心是认证信息不可用。除了清缓存重登还要检查系统时间是否准确——时间偏差过大会导致 token 校验失败这个坑很隐蔽我调了半天才发现是系统时间慢了。另外如果你在多个设备上登录同一个账号有时会出现 token 互相顶掉的情况。这种就老老实实重新登录别想着同时用。6.4 排查的通用心法调了这么多次我总结出一个通用心法从外到内从简到繁。先确认最外层的东西网络、服务是否启动再往里查配置、认证最后才怀疑工具本身有 bug。大部分问题都出在外层工具本身的 bug 反而是少数。还有一点保留完整的日志。很多人报错时只截一行那根本没法定位。把完整的日志留下来尤其是报错前后的几行信息量大得多。7. 把 Codex 用出效率我的日常配置与习惯7.1 项目级配置和全局配置的分工我的做法是全局配置放通用偏好项目级配置放项目专属规则。全局的比如回答用中文代码注释用英文项目的比如这个项目用 pnpm测试框架是 Vitest。这样分工的好处是换项目时不用重复配置通用部分项目级的规则又足够具体。全局配置改一次全项目生效项目配置只影响当前仓库。7.2 让模型少犯错的几个习惯用久了会发现模型犯错往往不是能力问题是信息问题。几个我养成的习惯任务开始前先让它复述理解让它用自己的话说一遍要做什么理解偏了当场纠正比做完再返工省事。大任务拆成小步骤一次让它做太多容易顾此失彼。拆成几步每步验证。关键改动要求它先说明方案涉及架构调整或大范围重构时先让它说打算怎么改确认了再动手。善用 AGENTS.md 沉淀教训每次它犯了重复的错就把对应的约束加进 AGENTS.md下次就不会再犯。7.3 上下文管理别让它忘事上下文窗口是有限的长对话到后面模型会忘掉前面的内容。我的应对办法是重要信息写进 AGENTS.md 或 Skill而不是靠对话记忆。对话里说的东西会随上下文滚动丢失写进文件的东西每次都会重新读取。另外长任务中间可以主动让它总结一下当前进度把关键结论固化下来避免后面跑偏。7.4 团队协作场景下的配置管理如果是团队用AGENTS.md 和 Skills 应该纳入版本控制让所有人共享同一套规范。这样新人入职拉下代码就自带规范不用口口相传。但要注意个人偏好不要写进团队共享的配置。比如你喜欢某种特定的代码风格但团队没这个约定就别往 AGENTS.md 里塞。团队配置只放大家都认可的规则。8. 关于 Skills 生态的一些观察Skills 这个东西有意思的地方在于它天然适合分享和复用。你写好的 Skill别人拿去改改就能用。热词里出现skills 市场常用 skills 源网站说明已经有人在往这个方向做了。我的看法是通用型 Skill 适合分享业务型 Skill 适合自留。像Markdown 转 PDF生成单元测试这种通用需求别人写的往往比自己写的好直接用就行。但涉及你公司业务逻辑的 Skill比如按我们的数据模型生成 API这种分享出去别人也用不了自己维护就好。找现成 Skill 的时候重点看它的 description 写得清不清楚、注意事项全不全。一个连注意事项都没写的 Skill大概率是没经过实战检验的。自己写 Skill 时我建议从最小的可用版本开始别一上来就追求大而全。先解决一个具体问题用起来再慢慢加功能。我第一个 Skill 就三行指令现在迭代到几十行了都是一次次用出来的。最后分享一个我自己的体会AGENTS.md 和 Skills 的价值不在于写得多漂亮而在于坚持维护。我见过太多人兴致勃勃写了一大篇用两天就扔那不管了规范过期了也不更新结果模型按过时的规范干活反而添乱。这东西跟文档一样是要养的。每次发现模型犯错就顺手补一条约束每次发现自己重复描述同一件事就顺手抽成一个 Skill。日积月累它才真正变成你的效率工具而不是一个摆设。