1. 从“焚决”说起Codex 这次到底更新了什么“焚决”这个词一出来圈子里的人基本都懂——不是官方术语是社区里对那种“一次性把旧玩法烧干净、逼你重新学”的大版本更新的戏称。Codex 这次的动作核心就三件事AGENTS.md 的上下文约定被提到了前所未有的高度、Skills 机制从“可选插件”变成了“默认工作流”、模型侧开始对接 GPT-6 Astra 这一代能力。如果你还在用老一套的“打开对话框、贴代码、等回复”的方式那确实会感觉像被烧了一遍。先把话说在前面这篇不是官方文档的翻译也不是那种“三步教你用 AI 写代码”的泛泛之谈。我下面要拆的是一个真实从业者在面对 Codex 这次更新时会怎么重新组织自己的项目结构、怎么设计 Skills、怎么处理 AGENTS.md 和 CLAUDE.md 的共存问题以及那些热搜词里反复出现的报错——比如cc switch local proxy failed while handling codex endpoint /responses、codex auth token is unavailable、the gpt-5.6-sol model is not supported——到底是怎么来的、怎么绕过去。适合谁看三类人一是已经在用 Codex 但感觉“越用越乱”的开发者二是刚接触 Codex、被一堆 Skills 和 AGENTS.md 搞晕的新手三是团队里负责定规范、想让多人协作时 AI 输出保持一致性的技术负责人。不管你是哪一类下面这些内容都是可以直接抄作业的。2. AGENTS.md 与 CLAUDE.md上下文约定的双轨制怎么玩2.1 为什么这次 AGENTS.md 被推到了 C 位Codex 早期版本里上下文管理基本靠“你在对话里说清楚”。但实际用下来你会发现同一个项目、同一个需求今天说一遍、明天说一遍AI 给出的代码风格、目录结构、甚至变量命名都可能不一样。这不是模型笨是它没有“项目记忆”。AGENTS.md 就是来解决这个问题的。它本质上是一个放在项目根目录的 Markdown 文件里面写清楚这个项目是干什么的、技术栈是什么、目录怎么组织、命名规范是什么、哪些文件不要动、哪些命令不要跑。Codex 在每次会话开始时会自动读取这个文件把它作为“系统级上下文”注入。我实测下来一个写得好的 AGENTS.md 能把重复解释的时间砍掉七成以上。比如你写一句“所有 API 路由放在src/routes/下使用express.Router()错误统一走middleware/errorHandler.js”后面不管你是让 Codex 加接口、改逻辑还是写测试它都会自动遵循这个约定不需要你每次重复。2.2 CLAUDE.md 和 AGENTS.md 到底怎么共存热搜里agents.md context.md、CLAUDE.md这几个词经常一起出现很多人搞不清关系。简单说CLAUDE.md 是 Claude Code 那套工具链的约定文件AGENTS.md 是 Codex 这边的约定文件。如果你同时用两套工具最省事的做法不是二选一而是让它们指向同一份内容。我的做法是根目录放AGENTS.md作为唯一事实来源然后CLAUDE.md里只写一行AGENTS.md或者用软链接。这样不管哪套工具进来读到的都是同一份规范。实测下来Codex 对引用语法的支持是稳定的Claude Code 那边也能正常解析。注意不要在两份文件里写互相矛盾的内容。我见过一个团队AGENTS.md 里写“用 2 空格缩进”CLAUDE.md 里写“用 4 空格”结果两套工具生成的代码混在一起格式化工具直接报错。2.3 一份可直接抄的 AGENTS.md 模板下面这份是我在多个项目里迭代出来的你可以直接拿去改# 项目上下文 ## 技术栈 - 语言TypeScript 5.x - 框架Next.js 14 (App Router) - 数据库PostgreSQL Prisma - 测试Vitest Playwright ## 目录约定 - src/app/ — 页面与路由 - src/components/ — 可复用 UI 组件 - src/lib/ — 工具函数与业务逻辑 - prisma/ — schema 与迁移文件 ## 编码规范 - 所有导出使用具名导出禁止 default export页面文件除外 - 异步函数必须处理错误禁止裸 await 不接 catch - 组件文件使用 PascalCase工具文件使用 camelCase ## 禁止操作 - 不要修改 prisma/migrations/ 下的历史迁移文件 - 不要直接操作 process.env统一走 src/lib/env.ts - 不要引入新的 UI 库现有组件已覆盖需求 ## 常用命令 - 开发pnpm dev - 测试pnpm test - 迁移pnpm prisma migrate dev这份文件的关键在于“禁止操作”那一节。很多人只写“要做什么”不写“不要做什么”结果 AI 好心办坏事把你不想动的东西动了。把边界写清楚比写十句“请小心”都管用。3. Skills 机制深度拆解从“会用”到“会写”3.1 Skills 到底是什么为什么这次成了默认工作流热搜里codex skills、skills推荐、skills开发、ai skills怎么写这些词密度极高说明大家最关心的就是这个。Skills 你可以理解成“给 AI 预置的一套操作手册”。一个 Skill 就是一个文件夹里面有一个SKILL.md描述这个技能干什么、怎么触发、需要哪些参数可能还有配套的脚本或模板。Codex 这次把 Skills 从“你手动挂载”变成了“默认扫描项目下的.codex/skills/目录”。也就是说只要你把 Skill 放对位置Codex 在遇到相关任务时会自动调用不需要你每次说“请用 XX 技能”。这个变化的影响很大。以前你是“指挥 AI 干活”现在你是“给 AI 配好工具箱让它自己选工具”。对于重复性高的任务——比如生成 CRUD 接口、写单元测试、做数据迁移——配好 Skill 之后效率提升是数量级的。3.2 一个 Skill 的最小结构别被“开发 Skill”这个词吓到最小可用的 Skill 其实就一个文件.codex/skills/gen-api/ └── SKILL.mdSKILL.md内容示例--- name: gen-api description: 根据 Prisma model 生成 Express 路由、控制器和测试 trigger: 当用户要求“为 XX 模型生成接口”时 --- ## 步骤 1. 读取 prisma/schema.prisma找到目标 model 2. 在 src/routes/ 下生成 model.routes.ts 3. 在 src/controllers/ 下生成 model.controller.ts 4. 在 tests/ 下生成 model.test.ts 5. 所有路由挂载到 src/app.ts 的 /api/v1 前缀下 ## 约束 - 使用项目现有的 errorHandler 中间件 - 分页参数统一为 page 和 pageSize - 返回值统一为 { data, total, page, pageSize }就这么简单。trigger字段是给 AI 看的“什么时候用我”步骤是“怎么干”约束是“别干歪”。我实测下来只要这三块写清楚Codex 调用 Skill 的准确率非常高。3.3 前端开发 Skills 和 Superpower Skills 怎么选热搜里前端开发skills、superpower skills、superpower skills 安装这几个词放在一起说明很多人在纠结用哪套。我的建议是先搞清楚你的痛点是什么。如果你痛在“每次都要重新解释组件规范、样式方案、状态管理选型”那你要的是项目级 Skill自己写一个frontend-convention就够了。如果你痛在“想让 AI 具备某种通用能力比如生成图表、处理图片、做动画”那可以看看社区里的Superpower Skills这类通用技能包。Superpower Skills 的安装方式通常是把它克隆到.codex/skills/下或者通过包管理器安装。但我要提醒一句通用 Skill 往往带了很多你用不上的东西反而会干扰 AI 的判断。我自己的做法是通用 Skill 只装真正高频用到的两三个其余全部自己写项目专用的。实操心得Skill 不是越多越好。我试过一次性挂 15 个 Skill结果 Codex 在简单任务上反而变慢因为它要花时间判断“该用哪个”。后来砍到 5 个以内响应速度和准确率都回来了。3.4 图片生成 Skills 和 AI 漫剧 Skills 的落地场景热搜里图片生成skills安装包、ai漫剧常用skills这两个词挺有意思说明 Skills 的用法已经溢出到纯开发之外了。图片生成类 Skill 的核心逻辑是把“提示词模板 参数预设 后处理脚本”打包成一个可复用的单元。比如你做 AI 漫剧一个comic-panelSkill 可以固定“分镜描述格式、角色一致性提示词、输出尺寸、命名规则”这样每次生成新一集时只需要换剧情文本其余全部自动套用。这类 Skill 的写法跟开发类没有本质区别关键是把“可变部分”和“固定部分”分离清楚。可变的是剧情、角色动作固定的是画风、比例、文件组织方式。分离好了Skill 才真正省事。4. 实操全流程从安装到跑通第一个 Skill4.1 Codex 安装与登录的坑热搜里codex安装、codex安装教程、codex安装 windows桌面版、codex官网登录入口、codex打不开这些词说明安装环节就卡住了不少人。我按平台说清楚。Windows 桌面版官网下载安装包后不要直接双击运行。先右键“以管理员身份运行”否则某些情况下会因为权限问题导致配置文件写不进去。安装完成后第一次启动会要求登录如果浏览器回调失败可以手动复制终端里输出的 URL 到浏览器完成授权。macOS / Linux推荐用包管理器安装比手动下载省心。安装后先跑codex --version确认版本再跑codex login走授权流程。常见报错codex auth token is unavailable这个九成是授权过期或配置文件损坏。解决办法是删掉配置目录下的auth.jsonWindows 在%APPDATA%\codex\macOS/Linux 在~/.config/codex/然后重新codex login。我遇到过好几次都是这么解决的。codex打不开先看是不是端口被占用了。Codex 本地会起一个服务默认端口如果被别的程序占了就会静默失败。换个端口或者关掉冲突程序即可。4.2 接入 DeepSeek 和其他模型的配置方法热搜里codex接入deepseek、codex配置、vscode接入codex这几个词放在一起核心问题是Codex 能不能接第三方模型答案是能但要看你怎么配。Codex 的模型配置通常在config.toml或环境变量里。以接入 DeepSeek 为例你需要设置base_url指向 DeepSeek 的兼容接口然后填上对应的 API Key。配置大概长这样[model] provider openai-compatible base_url https://api.deepseek.com/v1 api_key 你的key model deepseek-chat配完之后跑一个简单任务测试如果报the gpt-5.6-sol model is not supported when using codex with a...说明你的配置文件里还残留着默认模型名把它改成你实际要用的模型名就行。这个报错我见过太多次本质就是“配置没覆盖干净”。注意接入第三方模型后Skills 和 AGENTS.md 的解析能力可能会打折扣因为不同模型对结构化上下文的遵循程度不一样。我的经验是DeepSeek 在代码生成上够用但在复杂 Skill 调用上不如原生模型稳。如果你重度依赖 Skills建议还是用原生模型。4.3 跑通第一个自定义 Skill 的完整记录我拿一个真实场景来演示给一个 Next.js 项目写一个“生成页面骨架”的 Skill。第一步建目录mkdir -p .codex/skills/gen-page第二步写 SKILL.md--- name: gen-page description: 生成 Next.js App Router 页面骨架包含 loading 和 error 状态 trigger: 当用户要求“新建 XX 页面”时 --- ## 步骤 1. 在 src/app/route/ 下创建 page.tsx 2. 同时创建 loading.tsx 和 error.tsx 3. page.tsx 使用服务端组件数据获取走 src/lib/api.ts 4. 页面标题通过 metadata 导出 ## 约束 - 不使用客户端组件除非用户明确要求 - 样式使用 Tailwind不写内联 style - 错误边界必须包含重试按钮第三步测试在 Codex 里输入“新建一个用户列表页面路由是/users”。观察它是否自动调用了这个 Skill。如果没调用检查trigger描述是否够明确或者手动说“用 gen-page 技能”。第四步迭代第一次生成后看哪里不符合预期把对应的约束补进 SKILL.md。我一般迭代两到三轮Skill 就稳定了。4.4 参数选择与计算以分页 Skill 为例Skills 里经常需要处理参数。拿分页来说很多人写 Skill 时不写清楚默认值结果 AI 每次生成的默认分页大小都不一样。我的做法是在 SKILL.md 里明确写默认page 1默认pageSize 20最大pageSize 100超过则截断总数查询和列表查询分开避免全表扫描这些不是随便定的。pageSize 20是经验值太小会导致请求频繁太大会拖慢首屏。max 100是防止有人传pageSize 10000把数据库打挂。把这些写进 SkillAI 生成的代码就自带这些保护不需要你每次 review。5. 常见报错与排查速查5.1cc switch local proxy failed while handling codex endpoint /responses这个报错在热搜里出现频率很高本质是本地代理在处理 Codex 的/responses端点时失败了。常见原因有三个现象可能原因解决办法启动即报错代理端口被占用换端口或关掉冲突程序间歇性报错网络请求超时增大超时时间检查网络稳定性特定任务报错请求体过大拆分任务减少单次上下文量我遇到最多的是第三种。当你让 Codex 一次性处理一个超大文件时请求体可能超过代理的限制。解决办法不是去改代理配置而是把任务拆小——先让它读文件、再让它改某一段、最后让它验证。这样既稳又方便你中途纠偏。5.2codex auth token is unavailable的三种触发场景这个报错我总结了三类触发场景首次安装后未登录直接跑codex login即可。长时间未使用导致 token 过期删掉auth.json重新登录。多设备同时登录导致 token 冲突Codex 的授权有时是单设备有效的如果你在另一台机器上登录过这台就可能失效。解决办法是重新登录或者检查是否有设备管理页面可以踢掉旧设备。实操心得我习惯在换机器之前先手动登出这样能避免很多莫名其妙的授权问题。虽然多一步操作但比事后排查省时间。5.3 Skills 不生效的排查清单Skills 配好了但 Codex 不调用按这个顺序查目录位置对不对必须是.codex/skills/skill-name/SKILL.md层级不能错。frontmatter 格式对不对---必须独占一行name和description不能少。trigger 描述够不够具体写“处理数据”太泛写“当用户要求生成 CSV 导出时”才明确。是否有冲突 Skill两个 Skill 的 trigger 重叠AI 可能选错或都不选。模型是否支持第三方模型对 Skill 的解析能力有限换原生模型测试。这张清单我贴在显示器边上每次 Skill 不生效就过一遍基本五分钟内能定位问题。5.4 华为杯建模比赛场景下的 Skills 使用建议热搜里华为杯建模比赛好用的codex skills这个词挺具体说明有参赛者在用。建模比赛的特点是时间紧、任务重、代码需要快速出结果。我的建议是配三个 Skill数据预处理 Skill固定缺失值处理、归一化、特征工程的标准流程。模型训练 Skill固定交叉验证、参数搜索、结果输出的模板。论文图表 Skill固定图表风格、尺寸、导出格式直接对接 LaTeX。这三个配好比赛时你只需要关注“用什么模型、调什么参数”其余全部自动化。我见过有队伍因为图表格式反复调最后没时间写论文很可惜。6. 工具选型与协作Codex、Claude Code 与 OpenCode 的取舍6.1 Codex 和 Claude Code 到底怎么选热搜里codex和claudecode这个词说明很多人在纠结。我的看法是不要二选一要看任务类型。Codex 强在 Skills 机制和 AGENTS.md 的深度集成适合需要高度定制化工作流的项目。Claude Code 强在对话理解和长上下文适合需要大量讨论、逐步澄清需求的场景。OpenCode 这类开源方案强在可定制和私有部署适合对数据流向有要求的团队。我自己的组合是日常开发用 Codex因为 Skills 配好了效率高遇到复杂架构设计或需要反复讨论的需求切到 Claude Code涉及敏感数据的项目用 OpenCode 本地跑。6.2 团队协作时 AGENTS.md 的维护策略多人协作时AGENTS.md 最容易变成“没人维护的垃圾文件”。我的策略是指定一个 owner通常是 tech lead负责合并 AGENTS.md 的修改。修改必须走 PR跟代码一样改 AGENTS.md 也要 review。每月清理一次把过时的约定删掉把新踩的坑补进去。新人入职第一件事读 AGENTS.md然后跑一遍项目看有没有对不上的地方。这套流程跑下来AGENTS.md 才能真正成为“活文档”而不是写完就忘的摆设。6.3 Skills 的版本管理与分发Skills 写多了之后版本管理就成了问题。我的做法是项目专用 Skill 放项目仓库跟代码一起版本控制。通用 Skill 单独建仓库通过 git submodule 或包管理器引入。每个 Skill 带 CHANGELOG记录改了什么、为什么改。这样当 Skill 出问题时你能快速定位是哪个版本引入的。我吃过亏一个 Skill 改了 trigger 描述后原本能触发的任务不触发了因为没有 CHANGELOG排查花了半小时。7. 我踩过的坑和最后分享的几个技巧先说几个我实际踩过的坑。第一个是AGENTS.md 写太长。我一开始恨不得把整个项目文档都塞进去结果 Codex 读取后反而抓不住重点。后来砍到一页以内只留最关键的约定效果立刻好了。第二个是Skill 的 trigger 写得太宽。我写过一个“处理文件”的 Skill结果 Codex 在任何涉及文件的任务上都调用它包括它不该管的场景。后来把 trigger 改成“当用户要求批量重命名文件时”就精准了。第三个坑是忽略模型差异。我在原生模型上配好的 Skill换到第三方模型后行为完全不一样。后来我养成了一个习惯换模型后先跑三个标准任务测试确认 Skill 调用正常再正式用。最后分享几个小技巧。技巧一在 AGENTS.md 里加一节“常见错误”把团队踩过的坑写进去比如“不要用any类型”“不要直接改node_modules”AI 会主动避开这些。技巧二Skill 的description里加上“适用场景”和“不适用场景”能显著降低误触发。技巧三定期用codex --list-skills查看当前生效的 Skill 列表把不用的删掉保持工具箱干净。这些经验没有什么高深的理论都是实际用出来的。Codex 这次更新确实把门槛抬高了一点但抬高的那部分恰恰是让 AI 真正融入工程流程的关键。把 AGENTS.md 和 Skills 这两件事做扎实后面不管模型怎么换、工具怎么变你的项目上下文和工作流都是可迁移的。