1. 从“焚决”说起Codex 这次到底更新了什么“焚决”这个词最近在开发者圈子里传得挺凶第一次看到的时候我还以为是哪个玄幻小说里的功法后来才反应过来这是社区对 Codex 一次重大能力升级的戏称——意思是“烧掉旧玩法重开新局”。我前后折腾了大概两周时间把新版 Codex 的 AGENTS.md、Skills 体系、以及和 CLAUDE.md 的配合方式都跑了一遍踩了不少坑也摸出了一些门道。这篇文章就把我这两周的实际操作经验完整拆开讲从核心思路到具体配置从 Skills 开发到常见报错排查尽量做到你看完就能上手复现。先说清楚这个内容适合谁看。如果你已经在用 Codex 做日常开发辅助但还停留在“对话式问答”的阶段那这次升级值得你花时间重新理解一遍如果你是从 Claude Code 或者其他 AI 编程工具迁移过来的那 AGENTS.md 和 Skills 这两套机制是你必须搞懂的核心如果你是完全的新手想从零开始搭建一套属于自己的 AI 编程工作流那这篇文章会帮你少走至少一个月的弯路。核心关键词就几个Codex、AGENTS.md、Skills、CLAUDE.md、GPT-6 Astra后面我会围绕这几个点逐一展开。我个人的判断是这次升级的本质不是“模型变强了”这么简单而是 Codex 从“一个会写代码的聊天框”变成了“一个可配置、可扩展、可复用的开发代理系统”。这个转变的意义比单纯提升代码生成质量要大得多。打个比方以前的 Codex 像是一个随叫随到的临时工你每次都得重新交代背景现在的 Codex 更像是一个你亲手带出来的固定搭档你把项目规范、技术栈偏好、代码风格都写进 AGENTS.md它就能一直按你的规矩干活不用每次重复解释。2. 核心机制拆解AGENTS.md 与 Skills 到底解决什么问题2.1 AGENTS.md给 AI 立规矩的“项目宪法”AGENTS.md 这个东西第一次接触的人容易把它当成 README 的变体随便写两句就完事。我一开始也是这么想的结果发现 Codex 根本不按我的预期干活生成的代码风格和项目里现有的完全对不上。后来我才意识到AGENTS.md 不是“说明文档”而是“约束文件”——它的作用是告诉 Codex 在这个项目里什么能做、什么不能做、必须怎么做。我实测下来一个有效的 AGENTS.md 至少要包含这几块内容项目技术栈和版本约束、目录结构约定、代码风格规范、测试要求、以及禁止事项。举个具体的例子我在一个前端项目里写了这么一条“所有组件必须使用函数式写法禁止使用 class 组件状态管理统一用 Zustand不要引入 Redux。”就这一条直接让 Codex 生成的代码从“能跑但风格混乱”变成了“基本可以直接合并”。这里有个很多人忽略的细节AGENTS.md 的加载是有优先级的。Codex 会从当前工作目录向上逐级查找 AGENTS.md子目录的配置会覆盖父目录的配置。这意味着你可以在项目根目录放一份全局规范然后在特定子模块里放一份更细化的规范。我试过在一个 monorepo 里用这个机制根目录管通用规范前端目录管 UI 规范后端目录管 API 规范效果比把所有规则堆在一个文件里好得多。注意AGENTS.md 里写的规则要具体、可执行不要写“代码要优雅”这种模糊表述。Codex 对模糊指令的处理方式是“自由发挥”结果往往不是你想要的。2.2 Skills把重复劳动打包成“技能包”Skills 是这次升级里我觉得最有价值的部分。简单说Skills 就是把一类特定任务的完整处理流程打包成一个可复用的模块Codex 在遇到对应场景时会自动调用。你可以把它理解成给 Codex 装的“插件”但比插件更轻量本质上就是一套结构化的提示词加配套资源。我拿一个实际场景来说明。我们团队经常需要把设计稿转成前端代码以前的做法是每次手动描述设计稿内容然后让 Codex 生成来回改好几轮。后来我写了一个“设计稿转组件”的 Skill里面固化了我们团队的组件命名规范、样式方案Tailwind CSS Modules、以及响应式断点标准。现在只需要把设计稿截图丢进去Codex 就能直接产出符合规范的组件代码省掉了大量来回沟通的时间。Skills 的目录结构一般是这样的一个SKILL.md作为入口文件描述这个技能的用途、触发条件和执行步骤然后可以附带references/目录放参考资料scripts/目录放辅助脚本assets/目录放模板文件。这个结构设计的好处是技能本身是自包含的你可以直接打包分享给同事也可以从社区下载别人写好的技能包直接用。2.3 CLAUDE.md 与 AGENTS.md 的关系别搞混了很多人会问CLAUDE.md 和 AGENTS.md 是不是一回事我一开始也困惑过。实测下来两者定位不同CLAUDE.md 是 Claude Code 的配置文件AGENTS.md 是 Codex 的配置文件格式类似但加载逻辑和优先级规则有差异。如果你同时用这两个工具建议分别维护不要指望一份文件两边通用。不过有个技巧你可以把通用的项目规范抽到一个公共文件里然后在 CLAUDE.md 和 AGENTS.md 里分别引用。我现在的做法是维护一份PROJECT_RULES.md作为单一事实来源然后在两个配置文件里用引用语法指向它。这样改一处就能同步两边省得维护两份容易不一致。3. 实操全流程从安装到跑通第一个 Skill3.1 安装与初始配置Codex 的安装方式取决于你的使用场景。如果你是在终端里用直接通过包管理器安装 CLI 版本就行如果你习惯在编辑器里用VS Code 的扩展市场里可以搜到官方插件。我两种都试过终端版适合快速执行任务编辑器版适合边写边改的交互式开发建议都装上按场景切换。安装完成后第一件事是配置认证。这里有个常见的坑很多人卡在codex auth token is unavailable这个报错上。我排查下来的原因通常是认证信息没有正确写入配置文件或者环境变量没有生效。解决办法是重新走一遍登录流程确认配置文件里 token 字段有值。如果用的是 Windows 桌面版注意配置文件路径和 Linux/macOS 不一样别找错地方了。配置好之后建议先跑一个最简单的任务验证环境是否正常。我会用“在当前目录创建一个 hello.py打印当前时间”这种任务来测试如果 Codex 能正确创建文件并执行说明基础环境没问题。这一步别跳过我见过太多人环境没配好就开始折腾复杂功能结果排查半天发现是认证没生效。3.2 编写你的第一个 AGENTS.md我建议从一个小项目开始练手不要一上来就在大型项目里配。找一个你熟悉的个人项目按下面的结构写一份 AGENTS.md# 项目规范 ## 技术栈 - 语言Python 3.11 - 框架FastAPI - 数据库PostgreSQL 15 ## 代码风格 - 使用 black 格式化行宽 88 - 类型注解必须完整 - 函数必须有 docstring ## 目录结构 - src/ 放源码 - tests/ 放测试 - scripts/ 放运维脚本 ## 禁止事项 - 禁止在业务代码里直接写 SQL - 禁止使用 print 调试统一用 logging写完之后让 Codex 做一个需要遵循这些规范的任务比如“新增一个用户查询接口”。观察它生成的代码是否符合你的规范。如果不符合说明你的规范写得不够具体需要继续细化。这个过程可能要迭代两三轮但一旦调好后面就省心了。3.3 开发一个实用 Skill 的完整过程我拿“LaTeX 排版”这个 Skill 作为例子因为社区里问的人多而且这个场景足够典型。假设你要写一个自动生成学术论文格式的 Skill步骤如下第一步创建技能目录结构mkdir -p skills/latex-formatter/{references,scripts,assets} touch skills/latex-formatter/SKILL.md第二步编写 SKILL.md 的入口内容。这个文件要回答三个问题这个技能是干什么的、什么时候触发、具体怎么做。我通常会写成这样# LaTeX 排版技能 ## 用途 将 Markdown 格式的学术内容转换为符合期刊要求的 LaTeX 文档。 ## 触发条件 当用户提到“生成 LaTeX”“论文排版”“期刊格式”等关键词时启用。 ## 执行步骤 1. 读取 references/journal-template.tex 作为模板 2. 解析用户提供的 Markdown 内容 3. 按模板结构填充内容 4. 调用 scripts/validate.py 检查语法 5. 输出 .tex 文件第三步准备参考资料和脚本。references/里放期刊模板文件scripts/里放校验脚本。这些资源的作用是让技能执行时有据可依不用每次重新生成。第四步测试技能。找一个实际的 Markdown 文档让 Codex 调用这个技能处理检查输出结果。我第一版做的时候模板里的占位符没处理好导致生成的 LaTeX 里有残留的{{title}}这种标记。后来在 SKILL.md 里加了一步“检查并替换所有占位符”问题就解决了。提示Skill 的调试比普通对话麻烦因为出错时你看到的是最终结果不知道中间哪一步出了问题。我的做法是在 SKILL.md 里加详细的日志输出步骤方便定位问题。3.4 接入不同模型的配置要点社区里讨论比较多的一个话题是 Codex 接入不同模型的问题。我实测下来不同模型对 AGENTS.md 和 Skills 的支持程度有差异。有些模型对结构化指令的遵循度更高有些则在创意类任务上表现更好。我的建议是根据任务类型切换模型而不是一个模型用到底。配置模型切换的时候注意看报错信息。比如遇到the gpt-5.6-sol model is not supported when using codex with a...这类提示说明当前配置的模型和 Codex 的某个功能不兼容。解决办法要么换模型要么关掉冲突的功能。这类问题没有通用解只能根据具体报错逐个排查。4. 常见问题与排查技巧实录4.1 安装与认证类问题速查问题现象可能原因解决方法codex auth token is unavailable认证信息未写入或过期重新登录检查配置文件 token 字段codex 打不开端口占用或进程残留检查端口杀掉残留进程后重启Windows 桌面版安装失败权限不足或路径含中文用管理员权限安装路径改纯英文VS Code 插件无法连接版本不匹配升级插件和 CLI 到同一版本4.2 Skills 加载失败的排查思路Skills 不生效是最常见的问题我总结了一个排查顺序先确认技能目录位置对不对Codex 只会在特定路径下查找技能再检查 SKILL.md 的格式是否符合规范特别是触发条件那部分写得太模糊会导致技能永远不被调用最后看技能之间的优先级如果多个技能触发条件重叠可能会出现预期外的行为。我踩过的一个坑是技能命名冲突。有两个技能都叫“code-helper”结果只有一个生效。后来改成“python-code-helper”和“js-code-helper”就正常了。所以命名要具体别用太泛的词。4.3 代理与网络相关报错的正确处理社区里偶尔能看到cc switch local proxy failed while handling codex endpoint /responses这类报错。遇到这种问题我的建议是优先检查本地网络配置和代理设置是否符合你所在环境的要求确认相关服务是否正常运行。如果是在企业内网环境可能需要联系网络管理员确认访问策略。这类问题的排查思路是先确认基础网络连通性再检查应用层配置最后看日志定位具体失败环节。4.4 实操心得三个让我少走弯路的习惯第一个习惯是版本锁定。Codex 和 Skills 生态更新很快我现在的做法是在项目里记录当前使用的版本号升级前先在测试环境验证确认没问题再同步到主环境。这样避免某天突然更新导致工作流中断。第二个习惯是技能备份。我把自己写的所有 Skill 都放在一个独立的 Git 仓库里管理每次改动都有记录。有次误删了一个技能目录直接从仓库恢复五分钟搞定。如果没有备份重新写一遍至少半天。第三个习惯是渐进式配置。不要一次性把所有规范都写进 AGENTS.md而是遇到问题加一条慢慢积累。我现在的 AGENTS.md 是经过三个月迭代出来的每一条都对应一个实际踩过的坑。这种“问题驱动”的配置方式比一开始就追求大而全要实用得多。5. 进阶玩法Skills 生态与工作流整合5.1 从社区获取现成 Skills 的注意事项现在社区里已经有不少人分享自己写的 Skills从代码审查到文档生成都有。我的建议是下载别人的 Skill 之后不要直接用先通读一遍 SKILL.md确认它的执行逻辑符合你的预期。我遇到过一些 Skill 里嵌入了特定的工具调用或者外部请求如果不检查直接用可能会有意外行为。另外注意 Skill 的依赖问题。有些 Skill 依赖特定的脚本或库下载后需要先安装依赖才能用。我一般会在一个隔离环境里先测试确认没问题再放到主工作流里。5.2 把 Skills 串成工作流单个 Skill 的价值有限真正强大的是把多个 Skill 串起来形成完整工作流。比如我现在的一个典型流程是需求分析 Skill 先拆解任务然后代码生成 Skill 产出初版接着代码审查 Skill 检查问题最后测试生成 Skill 补上单元测试。这四个 Skill 串起来基本覆盖了从需求到交付的主要环节。串联的方式是在 AGENTS.md 里定义工作流顺序或者在 SKILL.md 里写明“完成后自动调用下一个技能”。我倾向于前者因为集中管理更清晰改起来也方便。5.3 团队协作中的 Skills 管理如果是团队使用Skills 的管理需要额外考虑几点版本一致性、权限控制、以及知识沉淀。我的做法是建一个团队共享的 Skills 仓库所有人从这里拉取技能修改通过 PR 流程审核。这样既保证了版本一致又能让好的实践沉淀下来。还有一点很重要定期清理不再使用的 Skill。我见过一个团队积累了上百个 Skill其中一半已经过时了但没人敢删因为不知道谁还在用。后来我们加了一个使用日志功能记录每个 Skill 的调用次数三个月没被调用的就标记为待清理。这个机制帮我们精简了将近一半的技能库。6. 关于 GPT-6 Astra 与未来的一些实际观察GPT-6 Astra 这个名字最近出现频率很高很多人问怎么用。我实际体验下来的感受是它在长上下文理解和复杂指令遵循上确实有提升但并不是“换了模型就万事大吉”。如果你的 AGENTS.md 写得乱七八糟换什么模型都救不了。反过来如果你把规范写清楚了即使是用之前的模型效果也不会差太多。我的建议是先把 AGENTS.md 和 Skills 这套基础设施搭好再去考虑模型升级的事。基础设施是地基模型是装修地基不稳装修再好也白搭。至于 GPT-6 Astra 的具体接入方式等官方文档更新后再跟进也不迟不用急着当第一批吃螃蟹的人。最后分享一个我最近在用的技巧把每次让 Codex 执行的任务和结果都记录下来定期回顾。你会发现有些任务反复出现这些就是值得做成 Skill 的候选。我现在的 Skill 库就是这么攒出来的每一个都对应一个真实的高频场景没有一个是拍脑袋想出来的。这个习惯坚持了两个月我的开发效率大概提升了三成左右而且代码质量比以前更稳定因为规范都固化在配置里了不依赖我每次手动提醒。