1. 从焚决这个词说起Codex 这次到底更新了什么焚决这个词最近在开发者圈子里传得挺凶第一次看到的时候我还以为是哪个玄幻小说的功法名。后来才搞明白这是社区里对 Codex 一次重大能力升级的戏称——大概意思是烧掉旧规则、重写新玩法的那种感觉。结合热搜词里出现的 AGENTS.md、Skills、GPT-6 Astra 这些关键词基本可以判断这次更新的核心方向Codex 从单纯的代码补全工具正在往可编排的智能体工作流平台方向演进。我接触 Codex 有一段时间了从最早的命令行版本到后来的 IDE 插件再到现在的 Skills 体系变化确实大。这次更新最值得关注的点我个人认为有三个一是 AGENTS.md 这个配置文件的引入让项目级的智能体行为可以被显式定义二是 Skills 技能库的开放意味着你可以把常用的工作流封装成可复用的模块三是底层模型能力的提升让复杂任务的完成度明显上了一个台阶。这篇文章不打算写成官方文档的翻译版那种东西网上到处都是。我想做的是把这几个核心变化拆开揉碎结合我自己踩过的坑和实际跑通的流程讲清楚它们分别解决什么问题、怎么配置、有哪些容易翻车的地方。不管你是刚听说 Codex 想上手试试还是已经在用但没搞明白 Skills 和 AGENTS.md 的关系应该都能从下面找到有用的东西。先说清楚适用人群如果你日常写代码、做技术方案、或者需要处理大量重复性的文本/代码任务这套东西值得花时间研究。如果你只是想找个自动补全工具那可能用不上这么重的配置。下面进入正题。2. AGENTS.md 到底该怎么写从能跑到跑得好的分界线2.1 为什么需要这个文件而不是靠默认行为很多人第一次用 Codex 的时候直接开个对话就开始提需求能用是能用但你会发现每次都要重复交代背景项目用什么语言、代码风格是什么、哪些目录不要动、测试怎么跑。这种重复劳动在单次对话里还能忍一旦项目变大、任务变多效率损耗就非常明显。AGENTS.md 的出现就是为了解决这个问题。它的本质是一个项目级的智能体行为声明文件放在项目根目录下Codex 在读取项目时会自动加载它把里面的规则作为后续所有操作的上下文。你可以把它理解成给智能体写的一份入职须知——告诉它这个项目的规矩是什么。我自己的做法是每个新项目初始化的时候第一件事就是写 AGENTS.md哪怕只有几行。这个习惯带来的收益在项目进行到第二周、第三周的时候会特别明显因为那时候你已经记不清当初为什么这么设计了但文件里写着。2.2 一份能直接抄的 AGENTS.md 骨架下面这个骨架是我在多个项目里迭代出来的你可以根据自己的技术栈调整# 项目智能体配置 ## 项目概述 - 技术栈TypeScript React Vite - 包管理器pnpm不要用 npm 或 yarn - 代码风格ESLint Prettier提交前必须通过 ## 目录约定 - src/components只放纯展示组件 - src/hooks自定义 hooks - src/servicesAPI 调用层 - 不要修改 dist/ 和 node_modules/ ## 常用命令 - 开发pnpm dev - 测试pnpm test - 构建pnpm build ## 行为约束 - 修改代码前先说明改动范围 - 新增依赖必须说明理由 - 涉及数据库 schema 的改动必须先确认这份骨架的关键在于具体。我见过不少人写的 AGENTS.md 全是请写出高质量代码注意性能这种废话智能体读了跟没读一样。规则要可执行、可验证比如包管理器用 pnpm就比使用合适的包管理工具有用一百倍。2.3 几个容易踩的坑第一个坑是规则写太多。我一开始恨不得把所有编码规范都塞进去结果发现智能体反而变得畏手畏脚简单任务也要反复确认。后来我精简到只保留不写会出错的规则效果反而更好。经验值是控制在 50 行以内超过这个长度就要考虑拆分或者删减。第二个坑是路径写错。AGENTS.md 里的相对路径是相对于文件所在位置的如果你在子目录里也放了 AGENTS.md要注意层级关系。我有一次在 monorepo 里配置因为路径没写对智能体一直在错误的目录里找文件排查了半天才发现问题。第三个坑是和 CLAUDE.md 混淆。热搜词里同时出现了 AGENTS.md 和 CLAUDE.md这两个文件的作用类似但服务对象不同。如果你同时用多个工具建议保持内容同步否则会出现在这个工具里能跑、换个工具就报错的情况。我的做法是维护一份主文件其他文件用软链接或者构建脚本同步。3. Skills 技能库把重复劳动封装成可复用模块3.1 Skills 解决的核心痛点在没有 Skills 之前我处理重复任务的模式是这样的把上次用过的提示词复制过来改改参数再跑一遍。这种方式的问题很明显——提示词散落在各个聊天记录里找起来费劲改起来容易漏团队协作时更是灾难。Skills 的思路是把这些提示词和配套的操作步骤封装成独立的模块每个模块有明确的输入输出定义可以像调用函数一样调用。这个设计思路其实不新鲜但在 Codex 这个场景下落地得比较完整因为它把技能定义、参数校验、执行流程都标准化了。举个我实际用到的例子我经常需要把一段中文技术文档翻译成英文同时保持 Markdown 格式不变。以前每次都要写一遍请翻译以下内容保持格式专业术语用标准译法这一长串。现在我把这个封装成了一个 skill调用的时候只需要传入文档内容就行。3.2 一个 skill 的最小结构一个可用的 skill 通常包含这几个部分name: translate-doc description: 将中文技术文档翻译为英文保持 Markdown 格式 inputs: - name: content type: string description: 待翻译的文档内容 - name: glossary type: string optional: true description: 术语对照表 steps: - 识别文档结构保留所有 Markdown 标记 - 按段落翻译技术术语优先使用 glossary 中的对照 - 输出前检查格式完整性这个结构看起来简单但每个字段都有讲究。description要写清楚这个 skill 干什么、什么时候用因为智能体在决定调用哪个 skill 的时候会参考这个描述。inputs的类型定义要准确否则传参的时候容易出错。steps是执行逻辑写得越具体结果越稳定。3.3 我常用的几个 skill 和它们的配置要点文档翻译 skill前面提到的那个配置要点是术语表要单独维护不要每次临时输入。我建了一个glossary.md放在项目里skill 执行时自动读取。代码审查 skill输入是 diff 内容输出是审查意见。这个 skill 的关键是审查规则要分层——先看安全问题再看逻辑问题最后看风格问题。如果混在一起智能体容易在风格问题上花太多篇幅忽略真正重要的逻辑缺陷。测试用例生成 skill输入是函数签名和功能描述输出是测试用例。这个 skill 我踩过的坑是如果不指定测试框架生成的用例可能用错断言方式。所以配置里一定要写明使用 Vitest 的 expect 语法这类具体约束。LaTeX 排版 skill热搜词里有人问怎么做一个 latex 排版 skills这个我确实做过。核心是把常用的排版规则公式编号方式、参考文献格式、图表标题位置固化下来输入原始内容输出编译好的 PDF 或者 .tex 文件。配置要点是模板文件要单独存放skill 只负责填充内容。3.4 skill 的安装和管理Skills 的安装方式取决于你用的具体工具版本。一般来说有两种途径一种是从官方或社区维护的技能库里直接拉取另一种是自己写好了放在本地目录里。我建议的做法是本地维护一份自己的技能库把常用的、经过验证的 skill 放在里面需要的时候同步到项目里。管理上要注意版本问题。我遇到过 skill 更新后行为变化导致原有流程失败的情况所以现在我会在 skill 文件里标注版本号和变更记录。团队协作时skill 的版本要和项目代码一起纳入版本控制避免你那边能跑我这边报错的尴尬。4. GPT-6 Astra 接入后的实际体验变化4.1 能力提升体现在哪些具体场景热搜词里gpt-6 astra 怎么用出现频率很高说明大家对底层模型升级的实际效果很关心。我自己的体感是升级后在以下几类任务上提升明显长上下文任务以前处理超过一定长度的文件时模型会忘记前面的内容导致前后不一致。升级后这个问题改善很多我测试过一个约 8000 行的代码文件让它找出所有潜在的资源泄漏点结果基本没有遗漏。多步骤推理涉及多个文件联动修改的任务以前经常出现改了 A 忘了 B的情况。现在它会主动追踪依赖关系改完一个地方会提示这里还关联到另外两个文件需要一起改吗。代码生成质量生成的代码更符合项目现有风格不需要反复调整。我猜测是因为它对 AGENTS.md 里定义的规则理解得更到位了。4.2 接入配置的注意事项接入新模型的时候有几个配置项容易出问题。第一个是模型名称的准确性热搜词里出现了gpt-5.6-sol这种看起来像版本号的字符串实际配置时一定要用官方文档里给出的准确名称写错了会直接报model is not supported。第二个是endpoint 配置。热搜词里有一条cc switch local proxy failed while handling codex endpoint /responses这个报错我遇到过原因是本地代理配置和 Codex 的 endpoint 设置冲突了。排查方法是先确认 Codex 的 endpoint 配置再检查代理设置两者要匹配。如果不需要代理直接把相关配置清空反而更稳。第三个是认证 token 的问题。codex auth token is unavailable这个报错通常出现在 token 过期或者配置路径不对的情况下。我的处理流程是先检查配置文件里的 token 字段是否存在再确认 token 是否过期最后检查文件权限。这三步走完基本能定位问题。4.3 和 DeepSeek 等其他模型的配合使用热搜词里有codex 接入 deepseek这个需求说明大家不满足于只用单一模型。我的做法是按任务类型分流需要深度推理和长上下文的任务走 Astra简单的代码补全和格式化任务走更轻量的模型。这样既能保证效果又能控制成本。配置上如果工具支持多模型切换可以在 AGENTS.md 里定义什么任务用什么模型的规则。如果不支持自动切换那就手动在配置里改改之前记得备份原配置。5. 从安装到跑通一条完整的上手路径5.1 安装环节的版本选择Codex 的安装方式根据平台不同有差异。Windows 桌面版和命令行版的安装流程不一样热搜词里codex 安装 windows 桌面版和codex 安装教程的搜索量都不低说明这一步确实卡住了不少人。我的建议是如果你主要做前端开发或者需要图形界面辅助优先装桌面版如果你习惯命令行工作流装 CLI 版本。两个版本的核心能力是一致的区别主要在交互方式上。安装过程中最常见的两个问题一是下载源的问题如果官方源速度慢可以找镜像源但要注意镜像的更新及时性二是依赖缺失特别是 Windows 环境下可能需要额外的运行库安装前先看一遍系统要求。5.2 首次配置的关键步骤装好之后的首次配置按这个顺序来登录认证热搜词里codex 官网登录入口codex 登录出现多次说明这一步是必经之路。登录方式通常有几种选你顺手的那种就行。登录成功后记得确认 token 是否正确保存到了配置文件里。基础配置设置默认模型、工作目录、日志级别。日志级别建议先设成详细模式方便排查问题跑通之后再调回正常级别。验证安装跑一个最简单的任务比如让它读一个文件并输出内容。如果这一步能成功说明基础环境没问题。配置 AGENTS.md按第 2 节的骨架写一份放在项目根目录。安装常用 skill先装一两个最常用的跑通之后再逐步增加。5.3 跑通第一个完整工作流我建议的第一个工作流是读代码 → 提修改建议 → 生成 diff。这个流程覆盖了 Codex 最核心的几个能力跑通之后你对整个工具体系就有感觉了。具体操作选一个你熟悉的项目文件让 Codex 分析它提出改进建议然后根据建议生成修改后的代码。重点观察它是否遵守了 AGENTS.md 里的规则是否调用了正确的 skill输出格式是否符合预期。如果这一步有问题按这个顺序排查先看 AGENTS.md 是否被正确加载可以在对话里直接问它你读到了哪些项目规则再看 skill 是否被正确调用看日志里的调用记录最后看模型配置是否正确。6. 那些报错信息背后的真实原因6.1 codex 打不开的几种可能这个报错太笼统了实际原因可能有好几种。我的排查顺序是进程冲突检查是否有残留的 Codex 进程在运行特别是上次异常退出后。任务管理器里结束掉再重启。配置文件损坏配置文件被意外修改或截断会导致启动失败。备份后删除配置文件让它重新生成。端口占用如果 Codex 需要监听某个端口端口被占用会导致启动失败。换个端口或者结束占用进程。权限问题安装目录或配置目录没有读写权限。检查一下目录权限设置。6.2 代理相关报错的正确处理前面提到的cc switch local proxy failed这个报错核心原因是代理配置和 Codex 的网络请求路径不匹配。处理原则是要么让代理配置和 Codex 的 endpoint 完全对齐要么干脆不用代理直连。我个人的经验是如果网络环境本身没问题不要额外配置代理多一层配置就多一个出错点。如果确实需要配置完之后一定要用最简单的请求测试一下确认链路通畅再跑正式任务。6.3 模型不支持报错的排查the gpt-5.6-sol model is not supported这类报错99% 的情况是模型名称写错了。处理步骤查官方文档确认当前支持的模型列表检查配置文件里的模型名称是否和文档一致检查是否有拼写错误、多余空格、大小写问题如果用的是第三方接入确认第三方是否支持该模型这个问题看起来简单但我见过不少人在这上面耗了很久就是因为没仔细核对名称。7. 团队协作场景下的配置管理7.1 配置文件该不该进版本库我的答案是该进但要分层。AGENTS.md 和 skill 定义文件应该进版本库因为它们是项目规范的一部分团队成员需要保持一致。但个人偏好配置比如主题、快捷键不应该进这些放在本地配置里。具体做法是在项目根目录放一份AGENTS.md作为团队共享配置个人特有的配置放在~/.codex/或者项目里的.codex.local文件里后者加入.gitignore。7.2 skill 的共享和版本对齐团队里每个人可能都有自己的 skill 库共享的时候要注意版本对齐。我的做法是建一个团队级的 skill 仓库所有经过验证的 skill 都放在里面每个人从仓库同步。个人实验性的 skill 放在本地验证稳定后再提交到团队仓库。版本对齐的关键是在 skill 文件里写清楚依赖。比如某个 skill 依赖特定版本的模型或者特定的工具版本要在文件头部标注。这样别人用的时候如果环境不匹配能快速定位问题。7.3 新人上手的引导流程带新人上手的时候我发现最大的障碍不是工具本身而是不知道从哪里开始。我的做法是准备一份第一天清单装好 Codex 并完成登录跑通一个最简单的任务读一遍项目的 AGENTS.md试用一个团队常用的 skill遇到问题先查日志再问人这份清单看起来简单但能帮新人快速建立信心避免一上来就被复杂的配置劝退。8. 一些零散但有用的经验关于 skill 的调试我有个小技巧先在对话里手动跑一遍流程确认结果符合预期后再把提示词和步骤固化到 skill 文件里。这样比直接写 skill 再调试要快得多因为对话模式下的反馈更即时。关于 AGENTS.md 的维护我的习惯是每次项目规范有变化就同步更新不要攒着。攒着的结果就是文件越来越过时最后没人看。更新的时候在文件末尾加一行变更记录方便追溯。关于模型选择不要迷信最新最强。有些任务用轻量模型跑得更快效果也够用。我的原则是先用轻量模型试效果不达标再换重的这样整体效率更高。关于报错处理养成先看日志再动手的习惯。Codex 的日志里通常有足够的信息定位问题比盲目试错快得多。日志级别建议在排查问题时临时调高问题解决后调回。最后说一个我踩过的坑不要在生产环境直接跑未经测试的 skill。我有一次写了个批量修改文件的 skill没在小范围测试就直接跑结果改错了一批文件花了半天才恢复。现在的做法是任何涉及文件修改的 skill先在测试目录跑一遍确认无误再应用到正式环境。这个领域的更新速度很快今天好用的配置明天可能就有更好的替代方案。保持关注官方更新和社区讨论但不要盲目追新稳定可靠比时髦重要。
