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/services：API 调用层 - 不要修改 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，先在测试目录跑一遍，确认无误再应用到正式环境。
这个领域的更新速度很快，今天好用的配置明天可能就有更好的替代方案。保持关注官方更新和社区讨论，但不要盲目追新，稳定可靠比时髦重要。
