1. 从焚决这个说法聊起Codex 这次到底更新了什么第一次看到焚决这个词我愣了一下。后来在几个开发者群里刷了一圈才反应过来这是圈子里对 Codex 某次重大能力升级的戏称——焚是烧掉旧工作流的意思决是决断、定调。说白了就是这次更新之后很多人原来那套用法直接过时了。Codex 是 OpenAI 推出的代码智能体产品支持在终端、IDE 和云端运行能读写代码库、执行命令、跑测试、提 PR。而这次被讨论最多的是围绕AGENTS.md、Skills、GPT-6 Astra这一整套东西的组合拳。如果你最近在搜codex 安装教程codex 使用教程codex skillsagents.md这些词说明你已经踩在门槛上了。这篇东西我打算按一个真实使用者的视角来写Codex 现在这套体系里哪些是必须搞懂的哪些是容易踩坑的哪些是网上教程没讲清楚的。适合三类人看——刚听说 Codex 想上手的、已经在用但总觉得没发挥出全部能力的、以及想搞清楚 AGENTS.md 和 Skills 到底该怎么配合的。先把结论摆前面Codex 的能力上限很大程度上不取决于模型本身而取决于你给它的上下文和技能配置。这句话是整篇的核心后面所有内容都在展开它。2. AGENTS.md 不是 README 的替代品它是给智能体的作业说明书很多人第一次接触 AGENTS.md会下意识觉得这不就是个项目说明文件吗跟 README 差不多。这个理解偏差会直接导致你写出来的 AGENTS.md 毫无作用。2.1 AGENTS.md 和 README 的本质区别README 是写给人看的读者是有背景知识的开发者很多约定俗成的东西可以省略。AGENTS.md 是写给智能体看的它没有你脑子里的隐性知识你项目里那些大家都知道的规矩对它来说完全不存在。举个具体的例子。你项目里可能有个约定所有数据库操作必须走db/目录下的封装层不允许在业务代码里直接写 SQL。这个规矩在老员工脑子里新人来了口头带一句就懂了。但智能体不知道它看到你在写一个查询功能很可能直接在 service 层拼了个 SQL 字符串出来。AGENTS.md 要解决的就是这类问题。它应该包含项目结构说明哪个目录放什么模块之间怎么依赖编码规范命名习惯、错误处理方式、日志规范禁止事项哪些写法绝对不允许出现常用命令怎么跑测试、怎么构建、怎么启动本地环境验证方式改完代码后怎么确认没改坏2.2 一份能真正生效的 AGENTS.md 长什么样我见过太多 AGENTS.md 写成了一篇散文读起来很流畅但对智能体毫无约束力。有效的写法是命令式、具体化、可验证。对比一下两种写法差的写法好的写法注意代码风格使用 2 空格缩进字符串统一用单引号函数名用 camelCase测试要写好每个新增函数必须在tests/下对应文件添加单元测试覆盖率不低于 80%不要乱改依赖禁止修改package.json中的依赖版本如需新增依赖必须先说明理由注意性能列表渲染超过 100 条时必须使用虚拟滚动看出区别了吗差的写法是态度好的写法是规则。智能体需要的是规则不是态度。2.3 AGENTS.md 的层级与作用范围Codex 支持多层级的 AGENTS.md这一点很多人不知道。你可以在项目根目录放一份在子目录再放一份子目录的会覆盖或补充根目录的规则。这个机制非常有用。比如你有个 monorepo前端和后端的规范完全不同就可以在frontend/AGENTS.md和backend/AGENTS.md里分别写各自的规则根目录那份只放全局通用的部分。提示子目录的 AGENTS.md 不是简单叠加而是就近优先。如果你在子目录里写了和根目录冲突的规则以子目录为准。这个行为要心里有数否则容易出现明明根目录写了禁止怎么还是这么干了的困惑。2.4 我踩过的坑AGENTS.md 写太长的反效果刚开始我很兴奋把能想到的规则全塞进去了写了两千多行。结果发现智能体反而不听话了——因为上下文被稀释了真正重要的规则淹没在大量次要信息里。后来我做了减法把 AGENTS.md 控制在 200 行以内只保留高频、关键、容易出错的规则。那些偶尔才用到的细节放到具体的 Skills 里或者临时在对话里说明。这个经验值得记一下AGENTS.md 是常驻上下文写得越长每条规则的权重越低。它不是文档是约束。3. Skills 体系把重复劳动打包成可复用的能力单元如果说 AGENTS.md 是规矩那 Skills 就是手艺。这是 Codex 这套体系里我觉得最有价值、也最容易被低估的部分。3.1 Skills 到底是什么为什么需要它Skills 可以理解为一组预定义的操作流程或知识包。当你需要智能体做某件有固定套路的事情时不用每次从头解释直接调用对应的 Skill 就行。举个最典型的场景LaTeX 排版。热词里有人搜怎么做一个 latex 排版 skills这个需求很真实。学术论文的 LaTeX 排版有一套固定流程——模板选择、公式规范、参考文献格式、图表编号规则。如果你每次都跟智能体口头描述一遍效率极低且容易遗漏。做成 Skill 之后一句话就能触发整套流程。Skills 的价值在于三个字可复用。它把一次性的经验沉淀成资产下次直接调用。3.2 Skills 的几种常见类型根据我自己的使用和观察Skills 大致可以分成几类流程型 Skills封装一套固定的操作步骤。比如发布流程 Skill包含跑测试、更新版本号、生成 changelog、打 tag、推送。触发一次全流程自动走完。知识型 Skills封装特定领域的知识。比如公司 API 规范 Skill里面写清楚内部接口的命名规则、鉴权方式、错误码约定。智能体写接口时会自动遵循。工具型 Skills封装对特定工具的使用方式。比如图片生成 Skill把调用图像生成接口的参数、格式、后处理流程都定义好。模板型 Skills封装代码或文档模板。比如React 组件模板 Skill新建组件时自动套用团队约定的结构。3.3 怎么写一个真正好用的 Skill写 Skill 和写 AGENTS.md 有相似之处但更强调可执行性。一个好的 Skill 应该包含触发条件什么情况下该用这个 Skill前置检查执行前需要确认什么执行步骤具体做什么按什么顺序输出格式结果应该长什么样异常处理出错了怎么办我拿清理 Skills这个场景举例因为热词里有人搜tibo 关于清理 skills 的方法推荐。Skill 用久了会积累一堆不再需要的定期清理是必要的。一个清理 Skill 可以这样设计## 触发条件 当用户说清理 skills或整理技能库时触发 ## 前置检查 - 列出当前所有已安装 Skills - 标记最近 30 天未使用的 ## 执行步骤 1. 按使用频率排序输出 2. 对每个低频 Skill 询问是否保留 3. 确认后移入归档目录而非直接删除 ## 输出格式 表格形式包含 Skill 名称、最后使用时间、建议操作注意最后一步——归档而非删除。这是我踩过坑之后的经验有些 Skill 你当时觉得用不上过两个月突然又需要了。直接删掉就得重写归档的话随时能捞回来。3.4 Skills 的安装与来源Skills 可以从多个渠道获取。官方市场、社区分享、自己编写各有各的适用场景。官方和社区来源的 Skills 胜在开箱即用但要注意版本兼容性。热词里有人搜superpower skills 安装常用 skills 源网站说明这块确实有需求。我的建议是优先用官方维护的社区的要看清更新时间和适用版本。自己编写的 Skills 最贴合实际需求但需要投入时间。我的做法是先手动做几遍某件事确认这个流程确实会反复用到再把它固化成 Skill。不要为了写 Skill 而写 Skill。注意安装第三方 Skills 前务必检查它会不会执行危险操作。Skills 本质上是可以让智能体执行命令的来源不明的 Skill 可能包含你不希望执行的操作。这个安全意识必须有。3.5 Skills 与 AGENTS.md 的配合关系这两者不是替代关系是互补关系。AGENTS.md 管的是始终生效的底线规则Skills 管的是特定场景下的操作流程。打个比方AGENTS.md 是公司的员工手册Skills 是各个岗位的操作手册。一个实际例子AGENTS.md 里写所有提交必须通过 lint 检查这是底线。而发布 Skill里写发布前依次执行 lint、test、build、changelog 生成这是流程。两者配合才能既保证质量又提升效率。4. 模型选择与接入GPT-6 Astra 和其他选项怎么选热词里gpt-6 astragpt-6 astra 怎么用codex 接入 deepseek这几个词出现频率很高说明大家对模型选择这件事很关心。4.1 不同模型在 Codex 场景下的定位Codex 本身是一个智能体框架底层可以接不同的模型。不同模型在代码任务上的表现差异是实实在在的。GPT-6 Astra是当前讨论度最高的选项。从实际使用反馈看它在长上下文理解、复杂重构、多文件协同修改这几类任务上表现突出。如果你的项目结构复杂、需要跨多个文件改动Astra 的优势会很明显。其他模型在特定场景下也有价值。比如有些模型在特定编程语言的代码生成上更稳有些在响应速度上更快。选择的核心逻辑是看你的主要任务类型。任务类型推荐考虑大型重构、跨文件修改长上下文能力强的模型快速补全、小改动响应速度快的模型特定语言深度开发该语言表现好的模型成本敏感场景性价比高的模型4.2 接入第三方模型的注意事项热词里codex 接入 deepseek这个搜索反映了一个真实需求不是所有人都想用同一个模型。接入第三方模型时有几个点必须注意。接口兼容性是第一个坎。不同模型的 API 格式不完全一样Codex 对接口有特定要求。如果格式对不上就会出现热词里提到的cc switch local proxy failed while handling codex endpoint /responses这类报错。认证配置是第二个坎。codex auth token is unavailable这个报错很多人遇到过。通常是 token 没配、配错了位置、或者过期了。排查顺序是先确认 token 存在再确认读取路径正确最后确认 token 本身有效。模型名称匹配是第三个坎。热词里有个很典型的报错the gpt-5.6-sol model is not supported when using codex with a...。这类问题的根源是模型名称写错了或者该模型在当前接入方式下不被支持。解决办法是查官方文档确认支持的模型列表别想当然。4.3 配置文件的正确写法Codex 的配置通常放在用户目录下的配置文件中。一个常见的配置结构大概是这样# 模型配置 model your-model-name model_provider your-provider # 认证配置 [model_providers.your-provider] name Your Provider base_url https://your-endpoint/v1 env_key YOUR_API_KEY几个容易出错的点base_url结尾的/v1不能少少了会 404env_key是环境变量的名字不是 key 本身模型名称必须和 provider 支持的完全一致大小写敏感提示改完配置后先用一个最简单的任务测试比如列出当前目录文件。如果这个都跑不通说明配置有问题别急着上复杂任务。4.4 切换模型时的状态管理热词里codex ccswitch这个词值得单独说。切换模型或 provider 时最容易出问题的是状态不一致——配置文件改了但缓存没清导致行为诡异。我的做法是切换后先重启 Codex 会话再跑一个验证任务。如果行为不对检查三个地方配置文件、环境变量、缓存目录。这三个地方任何一个没同步都会出问题。5. 从安装到跑通一条少踩坑的路径热词里codex 安装codex 安装教程codex 安装 windows 桌面版codex 下载codex 官网登录入口这些词密集出现说明安装环节是很多人的第一道坎。5.1 安装前的环境确认在动手之前先确认几件事操作系统版本Windows、macOS、Linux 各有不同的安装方式Node.js 版本很多安装方式依赖 Node 环境版本太低会失败网络环境安装过程需要访问包管理源网络不通会卡住磁盘空间留出足够空间别装到一半满了这几项看起来是废话但我见过太多人卡在装不上上最后发现是 Node 版本太老。5.2 不同平台的安装方式命令行安装是最通用的方式适合 macOS 和 Linux。通过包管理器一条命令搞定升级也方便。Windows 桌面版是热词里明确提到的需求。Windows 用户的体验确实和类 Unix 系统有差异路径分隔符、权限模型、终端环境都不一样。装的时候注意用管理员权限否则可能写不进系统目录。IDE 集成是另一种方式热词里vscode 接入 codex就是这个。好处是直接在编辑器里用不用切终端。配置时注意 IDE 的版本要支持对应的扩展。5.3 登录与认证codex 官网登录入口codex 登录这些搜索说明登录环节也有坑。登录方式通常有两种账号密码登录和 API Key 认证。账号登录适合个人使用API Key 适合自动化和团队场景。如果遇到codex 打不开的情况排查顺序是确认网络能访问服务端点确认登录状态没过期确认本地配置没被改坏查看日志找具体报错大部分打不开的问题最后都定位到认证失效或配置错误上。5.4 跑通第一个任务装完之后别急着上复杂项目先跑一个最小验证# 进入一个测试目录 cd ~/test-codex # 启动 codex codex # 输入一个简单任务 创建一个 hello.txt 文件内容写 hello codex如果这个能跑通说明基础环境没问题。跑不通的话问题一定在安装或认证环节别往复杂方向想。6. 实战场景几个高频需求的落地方法光讲概念没意思这一节我挑几个热词里反复出现的实际需求讲讲具体怎么落地。6.1 前端开发场景下的 Skills 配置前端开发 skills是个高频搜索。前端开发的痛点在于框架多、规范杂、重复劳动多。我自己的前端 Skills 配置包含这几块组件生成 Skill定义好组件的目录结构、文件命名、样式方案、测试文件。新建组件时一句话触发生成的文件直接符合团队规范。样式规范 Skill把设计系统的颜色、间距、字号、圆角等变量固化进去。智能体写样式时自动引用变量不会出现硬编码的魔法数字。接口对接 Skill封装请求库的使用方式、错误处理、loading 状态管理。避免每个页面各写一套。这套配置下来前端开发的重复劳动能砍掉一大半。6.2 学术场景LaTeX 排版 Skill 的构建前面提到过 LaTeX 排版 Skill这里展开讲讲怎么建。学术排版的核心需求是格式一致性。公式编号、图表标题、参考文献、页眉页脚每一项都有严格规范。构建步骤确定模板选定期刊或会议的官方模板把模板文件放进 Skill 目录定义规则把格式要求写成明确的规则比如公式编号用 (1) 格式右对齐封装命令把常用的排版操作封装成命令比如插入带编号的公式验证机制加一个检查步骤排版完成后自动检查格式合规性这样一套下来写论文时就不用反复查格式手册了。6.3 建模比赛场景华为杯这类竞赛的 Skills 用法热词里华为杯建模比赛好用的 codex skills这个搜索很具体。数学建模比赛的特点是时间紧、任务重、需要快速产出代码和论文。针对这个场景Skills 应该覆盖数据预处理 Skill常见的数据清洗、缺失值处理、归一化流程模型训练 Skill常用模型的训练模板参数配置可视化 Skill符合论文要求的图表生成论文排版 Skill建模论文的固定结构比赛时时间就是分数这些 Skill 能帮你把机械劳动压缩到最低把时间留给真正的建模思考。6.4 AI 漫剧场景图片生成 Skills 的配置ai 漫剧常用 skills图片生成 skills 安装包这两个搜索指向一个具体场景用 AI 生成漫画或短剧素材。这个场景的 Skills 配置重点是一致性。角色形象要统一、画风要稳定、分镜要连贯。配置要点角色定义把主要角色的外观特征固化成描述模板画风锁定确定统一的画风关键词每次生成都带上分镜规范定义镜头语言比如远景、中景、特写的描述方式后处理流程生成后的裁剪、拼接、字幕添加这套配置能显著提升出图的一致性和可用率。7. 那些教程不会告诉你的坑这一节是我自己踩过的坑以及从社区里看到的高频问题。这些东西官方文档不会写但实际用起来一定会遇到。7.1 上下文窗口不是越大越好很多人以为上下文窗口越大越好恨不得把所有文件都塞进去。实际用下来塞得越多智能体越容易迷失。原因是注意力机制的特性上下文越长每个 token 的权重越分散。关键信息淹没在大量无关内容里智能体反而抓不住重点。我的做法是精准投喂。只给当前任务相关的文件用 AGENTS.md 和 Skills 提供必要的背景而不是把整个代码库倒进去。7.2 Skills 冲突的处理装多了 Skills 之后冲突是必然的。两个 Skill 对同一件事有不同规定智能体就懵了。处理原则优先级明确在配置里定义 Skill 的优先级顺序职责单一每个 Skill 只管一件事别搞大杂烩定期清理不用的 Skill 及时归档减少冲突面我遇到过两个 Skill 都定义了代码格式化规则结果智能体每次格式化结果都不一样。后来把其中一个归档了问题解决。7.3 模型切换后的行为漂移换模型之后同样的 AGENTS.md 和 Skills输出质量可能明显变化。这不是配置问题是模型特性差异。应对方法换模型后用一组标准任务测试对比输出。如果差异太大可能需要针对新模型调整 AGENTS.md 的写法。有些模型对指令的遵循更严格有些更宽松写法要相应调整。7.4 认证失效的隐蔽性codex auth token is unavailable这个报错有时候不是 token 本身的问题而是读取路径的问题。我遇到过一次token 明明配了但 Codex 就是读不到。排查半天发现是环境变量在某个 shell 配置里被覆盖了。这种问题很隐蔽因为表面上看配置都对。排查这类问题的技巧用最干净的环境测试。开一个新的终端会话不加载任何自定义配置看能不能跑通。如果能说明问题在你的 shell 配置里。7.5 网络问题的伪装有些报错看起来是代码问题实际是网络问题。比如请求超时、响应格式错误可能是网络中间环节出了问题。判断方法看错误发生的时机。如果是稳定复现的大概率是配置或代码问题如果是偶发的网络因素的可能性更大。8. 把 Codex 用出复利一些长期实践的心得用了这段时间我最大的感受是Codex 的价值不是线性的是复利的。你投入在 AGENTS.md 和 Skills 上的每一分精力都会在后续的每一次使用中产生回报。8.1 从用工具到养工具刚开始大家都是把 Codex 当工具用用完就走。但真正用得好的人是在养它——持续优化 AGENTS.md不断沉淀 Skills让这套配置越来越贴合自己的实际需求。这个过程有点像养一个助手。刚开始它什么都不懂你得手把手教。教得越多它越懂你后面就越省心。8.2 建立自己的 Skills 库我建议每个人都建立自己的 Skills 库哪怕一开始只有几个。关键是养成习惯每次发现一个重复劳动就想想能不能做成 Skill。积累半年下来你会发现自己的 Skills 库成了最宝贵的资产。换项目、换公司这套东西都能带走直接复用。8.3 保持对模型更新的关注这个领域变化很快。新模型、新能力、新用法层出不穷。保持关注及时把新东西纳入自己的工作流才能持续保持效率优势。但也别盲目追新。新东西出来先小范围试确认确实有提升再全面切换。我见过太多人追新追出问题反而耽误了正事。8.4 最后分享一个实用技巧如果你刚开始用 Codex不知道从哪下手我的建议是先找一个你每天都在做的重复任务把它做成第一个 Skill。不要贪多就一个。做出来之后用一周感受一下效率变化。有了正反馈你自然知道下一步该做什么。这个技巧帮我度过了最开始那段不知道用来干嘛的迷茫期。希望对你有用。