1. 从“焚决”说起这套东西到底在解决什么问题“焚决”这个词最近在开发者圈子里传得挺开乍一听像是某种玄幻设定实际上它指的是围绕 Codex 这套 AI 编程助手体系把AGENTS.md、Skills、模型接入、本地代理配置这几块拼成一套能真正跑起来的工作流。很多人第一次接触 Codex 的时候以为装完就完事了结果卡在登录、卡在模型不支持、卡在 Skills 装不上、卡在代理转发失败折腾一整天连个像样的代码补全都没跑通。这篇内容就是把这些坑一次性讲清楚从安装到配置到 Skills 开发再到常见报错排查全部按实操顺序拆开讲。先说清楚这套东西适合谁看。如果你是完全没碰过 Codex 的新手这篇能让你少走至少两小时的弯路如果你已经在用 Claude Code 或者类似工具想搞清楚 Codex 的 Skills 机制和 AGENTS.md 到底怎么配合这篇也能给你一套可复用的模板如果你是想自己写 Skills 的进阶用户后面关于 Skills 结构设计和调试的部分会更有价值。核心关键词就几个Codex、AGENTS.md、Skills、模型接入、本地代理这几个词贯穿全文每一个都会展开讲透。我自己的使用场景比较典型日常写代码、做技术方案、处理一些重复性的文档整理工作。Codex 在这几个场景里表现差异很大配置对了效率翻倍配置错了还不如手动干。所以下面不会只讲“怎么装”而是把“为什么这么配”“什么情况下会出问题”“出了问题怎么定位”一起讲清楚。2. 安装与初始配置别急着登录先把环境理清楚2.1 安装渠道选择与版本差异Codex 的安装渠道主要有几种官网直接下载安装包、通过包管理器安装、以及在编辑器里装插件。这几种方式各有适用场景选错了后面会多出很多麻烦。官网下载的安装包适合 Windows 桌面用户双击安装、图形化界面、登录流程也比较直观。包管理器安装适合习惯命令行的用户升级方便但需要自己处理环境变量。编辑器插件适合已经重度依赖 VS Code 的人装完直接在编辑器里调用不用来回切窗口。我实测下来如果你是第一次用优先走官网安装包因为登录和授权流程最顺出问题也最容易排查。等用熟了再考虑包管理器或者插件方式。安装过程中有几个细节要注意安装路径尽量不要带中文和空格虽然现在大部分工具都支持了但少数依赖库在处理路径时仍然会出问题。安装完成后先别急着登录先确认版本号不同版本对模型的支持范围不一样。Windows 用户如果遇到打不开的情况先检查是不是被杀毒软件拦截了这个很常见。2.2 登录与授权auth token 问题的根源登录环节是新手最容易卡住的地方。常见的报错是codex auth token is unavailable这个报错看起来吓人实际上原因就那么几种。第一种情况是网络环境导致授权回调失败。授权流程通常需要浏览器跳转回本地如果本地端口被占用或者防火墙拦截回调就收不到token 自然拿不到。解决办法是换个端口或者临时关闭防火墙再试一次。第二种情况是之前登录过的残留凭证冲突。这时候需要把本地的凭证文件清掉重新登录。凭证文件的位置一般在用户目录下的配置文件夹里具体路径不同系统不一样但思路是一样的找到旧的、删掉、重新走一遍登录。第三种情况是账号本身的状态问题。这个就不展开了按提示操作即可。提示登录成功后建议把凭证文件备份一份后面如果换机器或者重装直接恢复能省很多事。2.3 模型接入为什么会出现“model is not supported”很多人配置完之后调用时报错the gpt-5.6-sol model is not supported when using codex with a...这个报错的核心原因是模型名称和当前 Codex 版本不匹配。Codex 在不同版本里支持的模型列表是变化的你配置里写的模型名如果不在当前版本的支持列表里就会直接报这个错。解决办法有两个方向一是升级 Codex 到支持该模型的版本二是把配置里的模型名改成当前版本支持的模型。我一般建议先查当前版本的支持列表再决定是升级还是改配置。盲目升级有时候会引入新的兼容问题改配置反而更快。另外如果你是通过第三方接口接入的还要注意接口本身是否支持你指定的模型。有些接口只转发特定几个模型你写别的名字过去它要么报错要么静默降级后者更麻烦因为你不看日志根本发现不了。3. AGENTS.md 与 Skills这套体系的核心逻辑3.1 AGENTS.md 到底是什么为什么需要它AGENTS.md 可以理解成给 AI 助手看的“项目说明书”。你在里面写清楚这个项目是干什么的、目录结构什么样、有哪些约定、哪些文件不要动、代码风格是什么AI 在干活的时候就会参考这些信息。为什么需要这个东西因为 AI 助手默认对你的项目一无所知。你不告诉它它就只能靠猜猜出来的结果往往不符合你的预期。有了 AGENTS.md相当于每次对话前都给它做了一次项目背景同步输出的质量会稳定很多。写 AGENTS.md 有几个要点项目概述要短两三句话说清楚就行别写成论文。目录结构列关键目录即可不用把每个文件都写上。约定和禁忌要明确比如“不要修改 config 目录下的文件”“所有新文件放在 src 下”。代码风格如果有特殊要求就写没有就省略。我见过有人把 AGENTS.md 写成几千字的大文档结果 AI 反而不看了因为信息密度太低。精简、准确、可执行这三点比篇幅重要得多。3.2 Skills 机制把重复工作封装成可复用能力Skills 是这套体系里最有价值的部分。简单说Skill 就是一段封装好的能力描述AI 在需要的时候可以调用它来完成特定任务。比如你经常要做 LaTeX 排版就可以写一个 LaTeX 排版 Skill以后每次需要排版的时候直接调用不用重新描述一遍需求。Skills 的典型结构包括名称和描述让 AI 知道这个 Skill 是干什么的。触发条件什么情况下应该用这个 Skill。执行步骤具体怎么做分几步每步做什么。输入输出需要什么参数产出什么结果。写 Skill 的关键是步骤要具体到可执行。你不能写“整理文档”要写“读取指定目录下的 markdown 文件按标题层级合并输出为单个文件”。越具体AI 执行起来越稳定。3.3 Skills 的安装与管理Skills 的安装方式取决于你用的具体工具链。常见的方式有几种手动放到指定目录、通过命令行工具安装、从 Skills 市场或仓库拉取。手动安装最直接把 Skill 文件夹放到工具的 Skills 目录下就行。命令行安装适合批量管理但需要工具本身支持。从仓库拉取适合获取社区分享的 Skill但要注意版本兼容性。管理 Skills 有几个经验定期清理不用的 Skill太多会拖慢加载速度也会干扰 AI 的选择。给 Skill 起名要规范一眼能看出用途别用skill1skill2这种。修改 Skill 后要重新加载很多工具不会自动热更新。注意从外部获取的 Skill 在正式使用前建议先看一遍内容确认没有奇怪的指令或者不安全的操作。4. 实操流程从零到跑通一条完整链路4.1 环境准备清单在开始之前先把这些东西准备好项目说明是否必须Codex 安装包官网下载对应系统版本必须可用账号用于登录授权必须网络环境能正常访问授权服务必须编辑器VS Code 或其他可选Skills 目录存放自定义 Skill可选环境准备阶段最容易忽略的是网络环境。授权流程对网络稳定性有要求网络不稳的时候登录会反复失败这时候别急着怀疑工具本身先换个网络试试。4.2 安装与首次登录的完整步骤第一步下载安装包。去官网找对应系统的版本Windows 选桌面版Mac 选对应架构的版本。下载完成后先校验一下文件完整性虽然概率低但下载损坏的情况确实存在。第二步安装。一路下一步即可注意安装路径不要有中文和空格。第三步首次启动。启动后不要急着登录先看一眼版本号和界面语言确认没问题再继续。第四步登录。点击登录后会跳转浏览器完成授权后会自动回调。如果回调失败检查端口占用和防火墙。第五步验证。登录成功后随便问一个问题确认能正常响应说明基础链路通了。4.3 配置 AGENTS.md 和第一个 Skill基础链路通了之后接下来配置项目级的 AGENTS.md。在项目根目录创建AGENTS.md写入项目概述、目录结构、约定禁忌。内容不用多控制在 500 字以内。然后创建第一个 Skill。在 Skills 目录下新建文件夹比如latex-format在里面写 Skill 描述文件。描述文件里写清楚触发条件、执行步骤、输入输出。写完之后重新加载然后在对话里测试。测试的时候给一个具体的任务看 AI 会不会调用这个 Skill调用后的输出是否符合预期。4.4 本地代理配置与常见转发问题如果你需要通过本地代理来转发请求配置的时候要注意几点。代理配置的核心是地址和端口的正确性。地址写错、端口写错、协议写错都会导致转发失败。常见的报错cc switch local proxy failed while handling codex endpoint /responses基本都出在这几个地方。排查思路确认代理服务本身在运行。确认配置里的地址和端口和代理服务一致。确认协议类型匹配。看代理服务的日志日志里通常有更具体的错误信息。代理配置这块我踩过的坑是配置改了但没重启。很多工具读取配置是在启动时改了配置不重启不生效然后你以为配置错了其实是没生效。5. 常见问题与排查技巧实录5.1 登录类问题速查报错信息可能原因解决方向auth token is unavailable回调失败/凭证冲突清凭证重登、换端口登录后无响应网络问题换网络环境反复跳转登录页凭证未保存检查目录权限5.2 模型与接口类问题模型不支持的问题前面讲过了核心就是版本和模型名匹配。接口类问题还有一个常见情况是接口限流表现是偶尔成功偶尔失败这种要看接口的返回头里有没有限流信息。5.3 Skills 加载与调用问题Skills 不生效的原因通常有几个目录放错了、格式不对、没重新加载、触发条件写得太模糊。排查的时候先确认目录和格式再确认加载状态最后看触发条件。5.4 代理转发类问题代理转发失败优先看日志日志里一般会写清楚是连接失败、超时还是协议错误。连接失败查地址端口超时查网络协议错误查配置格式。6. 进阶Skills 开发与工作流优化6.1 写一个好 Skill 的四个原则第一单一职责。一个 Skill 只做一件事别把排版和翻译塞进同一个 Skill。第二步骤可执行。每一步都要具体到能直接操作不能有模糊描述。第三输入输出明确。需要什么、产出什么写清楚。第四有边界。什么情况下不该用这个 Skill也要写。6.2 工作流组合把多个 Skill 串起来单个 Skill 解决单点问题多个 Skill 组合起来能解决流程问题。比如“读取文档 → 整理格式 → 输出排版结果”就是三个 Skill 串起来的工作流。组合的时候要注意 Skill 之间的衔接前一个的输出要能作为后一个的输入格式要对得上。6.3 持续优化根据使用反馈迭代Skill 不是写完就完了用一段时间之后要根据实际效果调整。触发太频繁就收紧条件触发太少就放宽条件输出不稳定就细化步骤。我自己的习惯是每两周回顾一次常用的 Skill看看有没有需要调整的地方。这个习惯坚持下来Skill 的可用性会明显提升。7. 一些实际使用中的体会Codex 这套东西的上手门槛不算低但一旦跑通日常效率的提升是实打实的。我自己的感受是配置阶段花的时间越多后面用起来越省心。很多人急着用配置随便弄弄结果后面天天排查问题反而更费时间。另外Skills 的价值在于积累。一开始可能只有一两个用着用着慢慢攒起来形成自己的技能库这时候才真正体现出这套体系的优势。别指望一开始就写出完美的 Skill先写出来能用再慢慢优化。最后分享一个小技巧把常用的配置和 Skill 做版本管理换机器或者重装的时候直接拉下来能省掉大量重复配置的时间。这个习惯我从第一次重装之后就开始坚持了确实管用。