1. 这次 Codex 更新到底改了什么1.1 从热搜词里读出的真实信号先把话说在前头所谓“焚决”这种叫法是社区里对一次大版本能力跃迁的戏称不是什么官方术语。但这次围绕 Codex 的讨论密度确实反常热搜词里同时出现了AGENTS.md、Skills、GPT-6 Astra、CLAUDE.md这几个关键词这本身就说明问题——大家关心的已经不是“Codex 能不能写代码”而是“怎么把 Codex 从单次对话工具变成一个可配置、可复用、可协作的工程化助手”。我先把这几个词的关系理一遍不然后面全是雾水Codex这里指的是具备代码理解与执行能力的 AI 编程助手形态核心能力是读代码、改代码、跑命令、按指令完成多步任务。AGENTS.md放在项目根目录的一份“给 AI 看的说明书”告诉它这个项目怎么构建、怎么测试、有哪些约定。CLAUDE.md同类思路的另一套约定文件很多团队两个都放让不同助手都能读到项目上下文。Skills可插拔的能力包把某类重复任务比如排版、图片生成、建模辅助封装成可调用的技能。GPT-6 Astra新一代底层模型代号社区讨论集中在它的长上下文和指令遵循上。这五样东西凑在一起指向一个很明确的方向AI 编程助手正在从“聊天框”进化为“带配置文件的工程组件”。你不再只是问它问题而是给它一套环境、一套规则、一套技能库让它稳定地按你的方式干活。1.2 为什么这次值得单独写一篇我接触过不少团队用 AI 写代码的痛点高度一致第一次用惊艳用一周就烦。原因不复杂——每次都要重新解释项目结构每次生成的代码风格都不一样每次都要手动纠正同样的错误。这不是模型不行是缺少一层“项目级配置”。AGENTS.md和Skills这套组合本质就是补上这层配置。它解决的不是“AI 会不会写代码”而是“AI 能不能按我的规矩、在我的项目里、稳定地写代码”。这个区别很大。前者是玩具后者是工具。所以这篇不打算复述官方文档而是按我自己的实操顺序把配置怎么写、Skills 怎么装、常见报错怎么排、哪些坑必须提前避开讲清楚。适合两类人一是刚上手 Codex 想少走弯路的二是已经在用但觉得“不够顺手”想系统化改造的。2. 核心思路把 AI 助手当成项目成员来配置2.1 为什么是“配置文件”而不是“更长的提示词”很多人第一反应是我把要求写进提示词不就行了我试过短期可以长期不行。原因有三个都是实操里踩出来的。第一提示词是会话级的配置文件是项目级的。你这次写了一大段“用 pnpm 不用 npm、测试用 vitest、提交信息用中文”下次开新会话又得重写。而AGENTS.md放在仓库里任何一次会话、任何一个协作者包括 AI都能读到一次写好长期生效。第二提示词会挤占上下文。你把项目说明塞进对话模型每轮都要重新读一遍既浪费 token 又容易在长对话里被冲淡。配置文件是“按需读取”的模型需要时才加载效率高得多。第三配置文件可以被版本管理。AGENTS.md提交进 Git改了什么都留痕团队能 review、能回滚。提示词做不到这一点它是“口口相传”的人一换就断了。提示不要把AGENTS.md写成百科全书。它的定位是“新成员入职第一天需要知道的东西”不是完整技术文档。写太长反而会让模型抓不住重点。2.2 AGENTS.md 和 CLAUDE.md 到底放哪个这是被问得最多的问题之一。我的建议很直接两个都放内容保持同步。原因在于不同助手读取的约定文件名不一样。有的认AGENTS.md有的认CLAUDE.md。你只放一个换工具时就抓瞎。两个都放成本几乎为零内容一样复制一份即可但兼容性直接拉满。具体做法有两种软链接方案ln -s AGENTS.md CLAUDE.md改一处两处都变。适合本地开发但要注意有些系统对软链接支持不一致提交到仓库可能出问题。复制同步方案两份独立文件靠脚本或 CI 检查内容是否一致。稳妥推荐团队用。我个人的习惯是复制同步然后在AGENTS.md顶部加一行注释说明“本文件与 CLAUDE.md 保持同步修改请同时更新”。简单粗暴但有效。2.3 Skills 的定位把重复劳动封装成“技能”如果说AGENTS.md解决的是“AI 懂不懂我的项目”那Skills解决的是“AI 会不会干某类活”。举个具体例子。你团队每周都要写一份 LaTeX 格式的实验报告格式固定、结构固定只是数据在变。每次让 AI 从头写它每次的排版风格都可能不同。但如果你做一个latex-reportskill把模板、字体、章节结构、引用格式全封装进去之后只要说“用 latex-report 生成这周的报告”出来的东西就是一致的。这就是 Skills 的价值把“每次都要交代一遍的事”变成“一次封装、反复调用”。热搜里出现的“前端开发 skills”“图片生成 skills”“AI 漫剧常用 skills”“华为杯建模比赛好用的 codex skills”本质上都是这个逻辑——针对特定场景把最佳实践固化下来。3. 实操从零配置一个可用的 Codex 环境3.1 安装与登录先把基础打通安装这一步本身不难但热搜里codex安装 windows桌面版、codex打不开、codex auth token is unavailable这些词说明卡住的人不少。我按平台分开说。通用前提确认你的 Node.js 版本不要太老建议 18 以上。版本太低会出现各种莫名其妙的依赖报错这是最常见的“打不开”原因之一。Windows 桌面版下载安装包后如果双击没反应先别急着重装。八成是杀毒软件拦截了或者安装路径里有中文和空格。把安装目录换成纯英文路径比如C:\tools\codex再试一次成功率大幅提升。登录问题auth token is unavailable这个报错通常不是账号问题而是本地凭证文件损坏或过期。处理顺序是先退出登录清掉本地配置目录下的凭证缓存再重新登录。不要反复点登录按钮那样只会让状态更乱。# 查看配置目录不同系统路径不同以实际为准 # 清理前先备份避免误删其他配置 ls ~/.config/codex注意清理凭证前一定先备份整个配置目录。我见过有人直接rm -rf把配置全删了结果连自定义的 Skills 一起没了只能重装。3.2 写一份真正有用的 AGENTS.md这是整篇的核心。我见过太多AGENTS.md写得像 README 的翻版那没用。它应该回答的是“AI 动手前必须知道的事”。我自己的模板结构是这样的你可以直接抄# 项目约定 ## 技术栈 - 语言TypeScript 5.x - 包管理pnpm禁止使用 npm/yarn - 测试vitest - 构建vite ## 常用命令 - 安装依赖pnpm install - 跑测试pnpm test - 类型检查pnpm typecheck - 本地启动pnpm dev ## 代码规范 - 组件用函数式不用 class - 所有导出必须有类型标注 - 提交信息用中文格式类型(范围): 描述 ## 禁止事项 - 不要修改 lock 文件 - 不要引入新的全局状态库 - 不要删除现有测试用例这份模板的关键在于具体、可执行、有边界。不是“请写高质量代码”这种废话而是“用 pnpm 不用 npm”这种明确指令。模型对明确指令的遵循度远高于模糊要求。写的时候有几个经验命令要写全。别写“跑测试”写“pnpm test”。模型不需要猜。禁止事项比鼓励事项更重要。告诉它不能做什么比告诉它要做什么更能避免翻车。保持更新。项目换了构建工具记得回来改。过期的AGENTS.md比没有更糟因为它会误导模型。3.3 Skills 的安装与开发Skills 的安装方式取决于你用的具体工具链但思路是通用的找到技能源放进指定目录让助手能发现它。热搜里常用 skills 源网站、skills技能库网址、人工智能skills市场这些词说明大家最缺的是“去哪找”。我的建议是优先用官方或社区维护的成熟技能库别一上来就自己写。自己写适合两种情况——要么市面没有要么你有非常特殊的团队规范。安装一个 skill 的典型流程从技能源获取技能包通常是一个目录里面有描述文件和实现。放进助手的 skills 目录具体路径看工具文档。重启或刷新让助手重新扫描。用一句测试指令验证它是否被正确加载。# 假设 skills 目录在配置目录下 # 把下载的技能包解压进去 unzip my-skill.zip -d ~/.config/codex/skills/ # 确认目录结构正确 ls ~/.config/codex/skills/my-skill自己写 skill 的要点一个 skill 通常包含两部分——一份描述告诉助手这个技能是干什么的、什么时候用和一份实现具体步骤或脚本。描述部分要写得像“使用说明书”把触发条件、输入、输出、注意事项都讲清楚。热搜里ai skills怎么写、skills开发问的就是这个。我写 skill 的一个心得先手动做三遍再封装。如果你自己都没手动跑通过这个流程封装出来的 skill 大概率是错的。先手动做记录每一步确认稳定了再写成 skill。4. 常见报错与排查实录4.1 那些热搜里的报错逐个拆热搜词里有一串报错信息我挑几个高频的讲。cc switch local proxy failed while handling codex endpoint /responses这个报错通常出现在切换配置或代理设置时。核心原因是本地转发配置和当前端点不匹配。排查顺序先确认当前用的是哪套配置再检查端点地址是否和配置一致最后看本地转发服务是否正常启动。多数情况下重置配置再重新选一次就能解决。the gpt-5.6-sol model is not supported when using codex with a...模型不支持。这类报错很直白——你选的模型和当前工具版本不兼容。解决办法是换一个受支持的模型或者升级工具版本。别硬刚换模型最快。codex auth token is unavailable前面提过凭证问题。退出重登清理缓存基本能解决。codex打不开分两种情况。如果是启动就崩看安装路径和杀毒软件如果是启动后白屏或卡住看网络和配置目录权限。我把这些整理成一张速查表方便你对号入座报错关键词最可能原因首选处理local proxy failed配置与端点不匹配重置配置重新选择model is not supported模型与版本不兼容换模型或升级版本auth token unavailable凭证过期或损坏退出重登并清缓存打不开/白屏路径含中文或权限问题换纯英文路径重装依赖报错Node 版本过低升级到 18 以上4.2 排查的通用心法报错排查这件事我总结了一个顺序几乎适用于所有 AI 工具问题先看版本再看配置最后看环境。版本工具版本、模型版本、依赖版本三者是否匹配。不匹配是万恶之源。配置配置文件有没有语法错误路径对不对内容是不是过期了。环境操作系统、权限、网络、杀毒软件。这些是“玄学问题”的真正来源。按这个顺序走能解决八成问题。剩下两成去社区搜报错原文通常已经有人踩过了。提示遇到报错先别改代码先复制报错原文去搜。很多问题别人已经解决过你只需要找到那个答案而不是从零推理。5. 进阶把 Codex 接入你的工作流5.1 和编辑器结合热搜里vscode接入codex说明很多人想在编辑器里直接用。这个方向是对的因为在编辑器里用AI 能直接看到你正在编辑的文件上下文更准。接入的核心是让编辑器插件和 Codex 服务打通。配置时注意两点一是插件版本要和工具版本匹配二是项目根目录要有AGENTS.md这样插件才能读到项目约定。配好之后你在编辑器里选中一段代码让它改它会自动带上项目上下文比在网页里复制粘贴强太多。5.2 多工具协作的现实做法热搜里codex和claudecode、codex ccswich这些词反映的是大家同时用多个 AI 编程工具的现实。我的建议是别追求统一追求互补。不同工具擅长的东西不一样。有的长于长上下文理解有的长于快速生成有的生态里 Skills 更丰富。与其纠结用哪个不如让它们各干各的然后用AGENTS.md和CLAUDE.md把项目约定统一起来保证不管用哪个出来的东西风格一致。具体做法项目根目录同时放两份约定文件内容同步。这样你换工具时不用重新交代项目背景直接开工。5.3 Skills 的长期维护Skills 装多了会乱这是必然的。热搜里tibo关于清理skills的方法推荐问的就是这个。我的清理原则是三个月没用过的删。留着只会拖慢扫描。功能重叠的合并。两个 skill 干同一件事留好的那个。描述不清的重写或删。描述不清的 skill模型根本不知道什么时候该用等于没有。定期清理比一次性装一堆更重要。我一般每个月花十分钟过一遍 skills 目录删掉不用的更新过期的。这个习惯让我的环境一直保持清爽。6. 我踩过的坑和给你的建议6.1 三个必须避开的坑坑一AGENTS.md 写太满。我一开始恨不得把整个架构文档塞进去结果模型反而抓不住重点经常忽略关键指令。后来精简到一页以内遵循度明显提升。记住它是“入职须知”不是“技术白皮书”。坑二Skills 装太多。有段时间我见一个装一个结果启动变慢而且模型经常选错 skill。后来砍到只留常用的五六个效率和准确率都上来了。少即是多。坑三忽略版本匹配。工具、模型、依赖三者版本不匹配是绝大多数诡异报错的根源。我现在养成习惯升级任何一个之前先查兼容性。这一步花两分钟能省两小时排查。6.2 给不同阶段的人的建议如果你是刚上手先把安装和登录打通写一份最简单的AGENTS.md技术栈加常用命令就够跑通一次完整任务。别急着装 Skills先感受基础流程。如果你是已经在用但不顺手重点检查AGENTS.md是不是过期了Skills 是不是装太多。这两个问题解决体验会立刻改善。如果你是团队协作把AGENTS.md和CLAUDE.md纳入代码评审改项目规范时同步更新。让 AI 配置成为团队资产而不是个人习惯。最后分享一个我一直在用的小技巧每次 AI 生成的代码让你不满意时别急着改代码先想想“是不是我的AGENTS.md没写清楚”。十次里有七次问题出在配置不在模型。把配置写明白AI 的表现会稳定得多。这个思路转变是我从“用 AI”到“用好 AI”的关键一步。
