如果你想在Codex CLI上获得类似Claude Code Skills的体验Superpowers是目前生态里最值得装的一个扩展。它不改变Codex CLI本身的逻辑而是通过一套“技能目录”机制给Codex补齐了头脑风暴、制定计划、技术评审、系统重构等结构化工作流。这篇教程专门面向Windows用户从环境准备、源码获取、符号链接创建到AGENTS.md配置手把手带你跑通整套安装流程。文中涉及的命令我都基于Windows 10/11实测过该踩的坑一个没少踩最后附上了排查清单和实用技巧照着操作基本能一次成功。1. 安装前先搞清楚Superpowers的原理1.1 Codex CLI与Superpowers的关系Codex CLI是OpenAI推出的终端AI编程助手最核心的能力是读写代码库、执行Shell命令、创建和修改文件以及自动修复错误。但Codex CLI默认给的是一个“空泛”的Agent——它没有内置任何工作方法论。你说“帮我写个计划”它也能写但产出完全看模型心情上下文一长就容易散更别说涉及系统重构、技术评审这种需要严格流程的复杂任务。Superpowers的出现就是为了解决这个问题。作者Jesse Vincent网名obra把软件工程里反复验证过的工作方法论比如头脑风暴、制定执行计划、技术评审、代码审查、重构旧系统、调试疑难Bug全部整理成Markdown技能文件。每个技能文件都有一套明确的操作流程、注意事项和输出模板。当Codex读到这些文件之后它在处理对应场景时就等于有了一本“操作手册”产出明显更稳定也更可复现。小白可能会问这些Markdown文件是怎么被Codex读到的原理其实不复杂。Codex CLI在启动时会加载AGENTS.md里的内容作为系统指令的一部分而AGENTS.md里可以通过路径的方式引用其他Markdown文件。Superpowers就利用了这一点把技能库放到~/.codex/superpowers/目录下然后在~/.codex/AGENTS.md里用superpowers/skills/README.md去引用Codex启动时就会把技能文件的内容注入到对话上下文中。把这条链路理解清楚之后你后面遇到任何“技能不生效”的问题排查思路就会非常清晰要么是文件没被放到正确位置要么是AGENTS.md里的引用路径写错了就这两条主线。1.2 为什么必须用“符号链接”接入很多人会问既然原理是读取Markdown文件那我直接把整个superpowers文件夹复制到~/.codex/目录下不就行了我实测过复制当然能跑通但问题出在更新和维护上。Superpowers是一个Git仓库更新频率不低几乎每周都有新的技能文件加入、旧技能优化。如果你用复制的形式接入每次升级只能手动删掉旧文件再重新拷贝麻烦是其次最怕的是搞混版本。用符号链接symlink或者目录联接junction接入你在本地clone的仓库就是唯一的数据源升级时只需要在仓库目录里执行git pullCodex立刻就能读到最新版本不需要任何二次操作。再一个原因是引用路径。Codex在解析superpowers/...这种写法时是基于~/.codex/这个目录来定位的。如果你把仓库放在别的盘符或者别的目录下引用路径会变得又长又容易写错。先在~/.codex/下创建一个叫superpowers的链接指向你的克隆目录引用路径就永远是短的、稳定的。这里稍微展开一下符号链接和junction的区别。Windows下有两种非常相似的目录链接机制符号链接Symbolic Link可以指向目录也可以指向文件既支持绝对路径也支持相对路径但创建时通常需要管理员权限或者打开开发者模式目录联接Junction只能指向目录但创建时普通权限就能搞定兼容性也更好。因为我们这里要链接的就是整个目录所以用junction完全够用而且更不容易踩权限的坑。这是我个人在Windows上最推荐的方式后面4.1节会给出具体命令。2. Windows环境准备与前置检查2.1 开启开发者模式省掉一半权限问题Windows上很多命令行工具的坑追根溯源都是权限检查太严格。安装Superpowers要用的mklink /D命令默认要求以管理员身份运行否则会直接报“You do not have sufficient privilege to perform this operation”。你当然可以每次都右键管理员身份打开CMD来执行但更省事的做法是一次性开启开发者模式。Windows 11的入口是设置 - 隐私和安全性 - 开发者选项 - 打开“开发人员模式”。Windows 10在设置 - 更新和安全 - 开发者选项 - 打开“开发人员模式”。开启之后系统会提示确认然后自动放宽一些开发相关的限制其中就包括让当前用户不用管理员权限就能创建符号链接。不过要提醒一句如果你用的是企业统一管控的电脑组策略可能会锁死开发者模式这个选项这时也不用慌直接用mklink /J创建junction目录联接就行那个命令在普通权限下就能执行。所以严格来说开发者模式不是必需的它只是让你的选择更多一些。2.2 安装Node.js和GitCodex CLI是一个npm包所以Node.js是绕不开的第一道依赖。直接去nodejs.org下载LTS版本就行不用追新。安装时一路Next即可但有一个细节值得注意在安装向导的Custom Setup页面确认一下“Add to PATH”选项是被勾选的。Node.js官方安装包默认会勾上但某些精简版或者旧版本安装包会去掉它装完你会发现npm命令根本找不到。Git for Windows严格来说不是Codex CLI的硬依赖但我强烈建议装上理由有两个一是我们要用git clone获取Superpowers源码虽然也可以用浏览器下载压缩包但远不如git命令方便二是Codex CLI在处理仓库操作时会调用系统的git命令比如让Codex提交代码、查看diffWindows上不装git这些功能都会报错。去git-scm.com下载最新版安装时选默认配置就行不想折腾的可以把“Git Bash”顺手装上后面clone、执行命令都方便些。装完之后开一个新的终端窗口分别验证一下node --version npm --version git --version三条命令都能打印版本号说明基础环境没问题。这里特别强调“新开窗口”因为Windows上PATH的生效范围是进程级的旧窗口里可能还读到不到新装的工具路径。2.3 安装并验证Codex CLI基础环境就绪后安装Codex CLI其实就一条命令npm install -g openai/codex装完直接验证codex --version能看到类似0.x.x的版本号输出就说明安装成功。但这个环节在Windows上有一个非常常见的问题codex命令找不到或者提示“无法将codex识别为cmdlet、函数、脚本文件或可运行程序的名称”。原因通常是npm的全局bin目录没有加入系统PATH。这个目录一般在C:\Users\你的用户名\AppData\Roaming\npm。解决办法是手动把它加进PATH右键“此电脑” - 属性 - 高级系统设置 - 环境变量 - 在“用户变量”的Path里追加这个路径然后重启终端。另一个经典问题是codex命令在终端里能用但ChatGPT桌面版在调用Codex CLI时报错错误信息类似“ChatGPT failed to start. Unable to locate the Codex CLI binary or required runtime components.”。这个问题我会在5.1节专门展开先按下不表。到这里Codex CLI本身已经能用了。建议你先运行一次codex并完成登录随便聊两句确认它能正常回复再进入Superpowers的安装环节。分步验证永远比装完一堆东西再整体排错要省心。3. 获取Superpowers源码3.1 git clone还是下载ZIP获取Superpowers源码有两种方式我分别说下优缺点。第一种是git clone官方仓库是obra/superpowers命令git clone https://github.com/obra/superpowers.git建议直接在用户主目录下执行这样得到的是C:\Users\你的用户名\superpowers。好处很直接以后升级只要进入目录执行git pull所有新增或者优化过的技能文件会全部同步下来配合符号链接接入Codex端零配置无缝升级。坏处就是本地多一个Git仓库磁盘占用其实很小几十MB的量级基本可以忽略。第二种是去GitHub页面下载ZIP压缩包解压后把文件夹改名成superpowers。这种方式适合完全不想碰Git的用户一次部署完就不用管升级。但后续要更新技能库就得重新下载、重新解压、重新覆盖而且覆盖过程中很容易遇到文件被占用的问题我自己后来放弃了这条路线。默认情况下我更推荐git clone。哪怕你现在对Git还不太熟之前装的Git for Windows已经帮你把git命令备好了后面无非就是git pull这一条命令的事。3.2 理解Codex CLI的配置目录在Windows上Codex CLI会把配置放在用户主目录下的.codex文件夹里也就是C:\Users\你的用户名\.codex。这个目录非常重要里面有几个文件或子目录需要记住config.tomlCodex CLI的主配置文件模型选择、行为开关都在这里AGENTS.md全局指令文件Codex每次启动都会读取log/运行日志目录排查问题时非常有用sessions/会话记录目录以及我们马上要创建的superpowers链接。建议你现在就打开%USERPROFILE%\.codex确认一下这个目录存在。如果你之前已经用过一次codex这个目录肯定已经自动建好。如果还没用过就先去跑一次codex让它初始化。这个目录是Superpowers接入的目标位置后面所有操作都围绕它展开。还有一个认知很关键Codex CLI有两个层级的AGENTS.md一个是全局的~/.codex/AGENTS.md一个是项目目录下的AGENTS.md。两者可以共存项目级内容会追加到全局内容之后。Superpowers的技能引用放在全局AGENTS.md里意味着你在任意项目目录下启动Codex都能用到这些技能如果只想在某个特定项目里启用部分技能也可以写到项目AGENTS.md里。4.2节我会细讲配置写法。4. 把Superpowers接入Codex CLI4.1 创建符号链接的三种方式现在到了整个安装流程的核心环节让~/.codex/目录下存在一个superpowers入口指向你的克隆仓库目录。方式一使用cmd的mklink命令创建目录符号链接需要管理员权限或已开启开发者模式cd /d %USERPROFILE%\.codex mklink /D superpowers %USERPROFILE%\superpowers方式二使用cmd的mklink /J命令创建junction普通权限即可强烈推荐cd /d %USERPROFILE%\.codex mklink /J superpowers %USERPROFILE%\superpowers方式三使用PowerShell创建符号链接需要管理员权限或已开启开发者模式New-Item -ItemType SymbolicLink -Path $HOME\.codex\superpowers -Target $HOME\superpowers链接创建成功之后立刻验证dir %USERPROFILE%\.codex你会看到superpowers这一行目录符号链接会显示SYMLINKjunction会显示JUNCTION并且指向C:\Users\你的用户名\superpowers。看到这个就说明链接本身没问题了。如果想更彻底地确认直接读取里面的文件type %USERPROFILE%\.codex\superpowers\skills\README.md能输出内容就说明Codex能走通这条路径。4.2 编写AGENTS.md链接创建好之后下一步就是告诉Codex CLI启动时请加载Superpowers。这一步是在AGENTS.md里完成的。打开C:\Users\你的用户名\.codex\AGENTS.md如果文件不存在就新建然后把下面这一行写进去superpowers/skills/README.md保存后Codex启动时就会自动读取~/.codex/superpowers/skills/README.md。这份README本身会继续引用其他技能文件于是整套技能库像链式反应一样被一层层加载进来。如果你只想按需启用个别技能也可以不用README直接列出需要的技能文件。比如一位做后端维护的朋友他最需要的是新系统设计、旧系统重构、写计划这几类那就可以在AGENTS.md里这样写superpowers/skills/creating-plans/creating-plans.md superpowers/skills/planning-system-change/planning-system-change.md这里提醒一个关键点每多引用一个技能文件都会增加Codex对话上下文中的Token占用。Superpowers的技能文件动辄几千字如果一次性把所有技能全部塞进去会大幅压缩模型可用的上下文空间反而影响对话质量。我的建议是先用superpowers/skills/README.md确认整套机制跑通然后回头按实际工作内容精简AGENTS.md里的引用只保留常用的三五个技能。另外README里有一个技能索引里面是每个技能的一句话说明。当你不确定某个场景应该用哪个技能时让Codex看一眼README的索引就能知道相当于给Agent内置了一份“技能说明书”。实际体验中让Codex自己判断要不要调用技能往往比手动指定效果更好。4.3 首次联调验证配置完成接下来验证。这一步我强烈建议别跳过。如果是链接创建有问题或者AGENTS.md路径写错了越早发现越好定位。打开终端进入任意一个项目目录运行codexCodex启动后直接问一个直球问题看一下你有哪些superpowers技能简单列一下如果安装成功Codex会基于AGENTS.md加载到的内容告诉你它当前可用的技能有哪些比如头脑风暴、计划制定、技术评审、代码审查、调试、重构旧系统等。如果Codex回答“我不知道你在说什么”或者完全没有提到任何技能基本可以判定AGENTS.md引用没被正确加载。优先检查两件事第一~/.codex/superpowers链接是否存在并且目录下有没有skills子目录第二AGENTS.md的引用路径是否写对注意大小写。Windows文件系统不区分大小写但还是尽量和仓库实际目录结构保持一致减少歧义。确认技能加载成功后可以试一个真实场景感受变化。比如我现在有一个旧系统要重构用superpowers里的方法论帮我规划一下步骤你会发现和没装Superpowers时相比Codex的回答明显更有条理——它会先和你确认需求边界然后分阶段输出计划而不是直接甩一段泛泛而谈的方案。这个体验差异就是Superpowers最值回票价的地方。5. 常见问题排查与实战技巧5.1 ChatGPT报“unable to locate the codex cli binary”怎么办这个报错在Windows上出现频率很高完整信息是“ChatGPT failed to start. Unable to locate the Codex CLI binary or required runtime components.”。核心原因是ChatGPT桌面版在启动Codex CLI时找不到codex可执行文件或者找不到它依赖的Node.js运行时。排查步骤按顺序来排查步骤操作说明1终端执行codex --version确认命令行本身可用2执行where codex确认codex所在路径已加入PATH3重启ChatGPT桌面版确保环境变量被重新读取4检查Windows安全中心拦截记录必要时给codex添加信任第一步在终端跑codex --version。如果终端里都报错说明Codex CLI根本没装好回到2.3节重新走一遍。第二步如果终端里能跑大概率是PATH问题。ChatGPT桌面版启动时不一定继承你终端里手动设置过的环境变量。正确做法是把C:\Users\你的用户名\AppData\Roaming\npm永久写入用户PATH然后彻底退出并重启ChatGPT桌面版。第三步检查Node.js是否正常。ChatGPT桌面版调用Codex时实际上是在后台执行node去加载Codex的JS入口。如果你之前用过精简版Node或者装完又卸载换了新版本注册表里的路径可能已经乱了。稳妥方法是把系统PATH里Node相关路径清理一下只保留当前正在用的Node安装路径。还有个偏门的可能性杀毒软件拦截了Codex CLI的首次执行。Windows Defender有时候会把未签名的新二进制文件拦下来导致ChatGPT后台调用失败。你可以在Windows安全中心的“保护历史记录”里查一下有没有相关拦截记录如果确实被拦添加信任即可。5.2 符号链接创建失败怎么办符号链接创建失败是Windows经典问题常见报错是“You do not have sufficient privilege to perform this operation.”。这里给一套由易到难的解决方案第一优先用junction。直接在普通CMD里执行mklink /J %USERPROFILE%\.codex\superpowers %USERPROFILE%\superpowersjunction不需要管理员权限这是Windows上接入Superpowers最推荐的方式没有之一。如果前面的步骤都照做了基本不会失败。第二优先开启开发者模式。设置 - 隐私和安全性 - 开发者选项 - 开发人员模式打开。然后重新打开CMD执行mklink /D。第三优先以管理员身份运行CMD再执行mklink /D。注意管理员CMD的当前目录默认是C:\Windows\System32执行前先切到%USERPROFILE%\.codex或者直接写完整路径。还有一种容易被忽略的情况~/.codex下已经存在同名目录或文件。比如之前手动往这里复制过空的superpowers文件夹会导致链接创建失败。先删掉或改名再执行链接命令。5.3 更新Superpowers的正确姿势既然用git clone安装更新就很简单。进入superpowers仓库目录git pull完事。因为符号链接指向这个目录git pull之后Codex下次启动会自动加载新版本零额外操作。几个细节提醒一下。首先尽量别去改superpowers/skills/目录下的原始技能文件这些改动在git pull时会产生冲突。有定制需求的话复制一份放到自己的目录然后在AGENTS.md里改引用路径指向你自己的版本。其次如果是ZIP解压方式安装的更新只能手动删旧解压覆盖建议先删干净再覆盖别直接覆盖因为文件删减是覆盖不掉的。第三每次git pull之后顺手看一眼更新内容确认作者有没有重命名或删除技能文件这些变动会影响AGENTS.md里写好的引用路径。如果引用的文件不存在了Codex加载时会报错对话上下文里也会有明显异常。5.4 常用技能与实战建议Superpowers装完之后被问得最多的问题是“技能太多到底用哪些”。这里分享真实使用体会。刚上手的话从这三个开始brainstorming头脑风暴、creating-plans创建计划、technical-review技术评审。这三个技能覆盖了日常开发最常见的三类场景需求还不清晰时怎么发散、需求明确了怎么拆解执行、代码写完了怎么严格把关。在AGENTS.md里按需引用superpowers/skills/brainstorming/brainstorming.md superpowers/skills/creating-plans/creating-plans.md superpowers/skills/technical-review/technical-review.md这样不会把上下文撑得太大同时Codex在遇到对应场景时又能拿到完整方法论。另外一个使用技巧在对话开始时可以先明确告诉Codex“接下来我们一起用brainstorming技能来想清楚需求”强制它进入对应工作流。如果不指定它虽然能读到技能文件但不一定会主动用。复杂需求越早锁定方法论后面的产出越可控。尤其是老系统重构这种任务先让Codex走一遍planning-system-change流程把现状梳理、目标定义、风险清单全部拉出来再动代码整个过程的稳定性和可解释性都会好很多。我个人在实际操作中最大的体会是Superpowers不是一个“装完就完事”的工具它更像一套可定制的工作流框架。刚安装时可以先用全局AGENTS.md一把梭跑到后期你会发现真正高频使用的技能就那么几个按项目、按场景分别配置AGENTS.md里的引用效果会好很多。最后再分享一个小技巧如果团队统一使用Codex CLI可以把Superpowers的目录放到一个公共的内网Git仓库然后在每个人的开发机上创建指向公共目录的链接。这样团队的方法论沉淀只需要更新一份代码所有人的Codex就都能同步成长。这个方式我们团队内部跑了大半年效果很稳定。