如果你已经在Windows上装好了Codex CLI并且开始用它写代码、改Bug那么你大概率很快会遇到同一个问题单靠一句一句的对话Codex的发挥特别依赖你“提示得够不够具体”。一遇到稍微复杂一点的任务模型就容易东一榔头西一棒子忙着改代码却忘了写测试。Superpowers就是为解决这个问题出现的一套开源技能包它给Codex CLI装上了一整套标准工作流——启动时的引导、先做计划、调试、TDD、重构、代码审查全都有对应的技能文件让模型按项目规则干活而不是自由发挥。这篇是Codex CLI系列教程的第四篇专门讲Windows下的Superpowers安装。说句实话Superpowers在macOS和Linux上安装很顺一条命令就搞定但Windows从来不是这类脚本的一等公民。PowerShell的执行策略、curl别名、npm全局目录不在PATH里、安装脚本跑到一半被杀毒软件拦下……这些都是我实际踩过的坑。这篇我会把我认为Windows上最稳的一条路径完整写出来顺便把常见报错和排查方法整理成速查表给同样在Windows上折腾的人省点时间。1. 先搞懂Superpowers到底给Codex CLI带来了什么1.1 它解决的是“提示词质量”问题Codex CLI本身是个终端里的AI编码助手你给它一个任务它读取项目上下文然后生成代码、跑命令、改文件。它最大的优点是上手快缺点是如果你不告诉它“先写测试”“先做计划”“别改无关文件”它的行为就完全依赖于模型当时的状态。同一个任务今天问和明天问过程可能完全不一样。Superpowers的思路很朴素把这一类“优秀工程师的工作习惯”写成一个个Markdown技能文件放在Codex能读到的技能目录里。当Codex收到调试类任务它会主动加载debugging技能的指令按照“先复现、再定位根因、最后修复并用测试验证”的流程走收到重构类任务它会先要求你确认行为基线再做小步重构每一步都跑测试。它相当于给实习生发了一本《团队工作手册》而不是让实习生每次遇到问题都靠自己猜。我拿一个很直观的例子说明区别。没有Superpowers时你让Codex“帮我改一下登录接口的报错”它大概率上来就写代码改完说“好了”。有Superpowers时它会先问你现在的报错日志是什么、期望行为是什么、这个接口有哪些调用方然后给你一个计划等你确认了再动手。多出来的这一步在真实项目里能少很多次“改完反而弄坏了别的地方”的事故。1.2 为什么Windows安装值得单独写一篇官方仓库里给的安装命令基本是bash一行流默认的假设是你在macOS或Linux的终端里。Windows用户复制这条命令到PowerShell会遇到三个麻烦。第一PowerShell里的curl是Invoke-WebRequest的别名不是真正的curl参数行为完全不一样直接执行官方那条curl ... | bash大概率报错。第二Windows的脚本执行策略默认禁止运行未签名的.ps1脚本PowerShell安装脚本经常直接被杀。第三路径问题。Windows的用户目录是C:\Users\你的用户名npm全局安装目录是AppData\Roaming\npm很多工具对这种带空格的路径处理得并不好。除此之外新版的ChatGPT/Codex桌面应用在Windows上还有一个很典型的报错unable to locate the codex cli binary or required runtime components。这个问题十有八九不是因为Codex没装而是桌面应用在PATH里找不到codex.exe或者找不到Node运行时。这类和PATH、环境变量、脚本权限相关的坑在macOS上几乎不会出现所以确实值得专门开一篇来写。2. 安装前的环境检查与依赖准备2.1 先把终端、Node.js和Git这三样备齐我不建议在Windows上打开老旧的cmd窗口来做这件事至少用Windows Terminal加PowerShell 7或者干脆用Git Bash。Windows Terminal可以在微软商店安装PowerShell 7从官方发布页下载Git Bash随Git for Windows一起安装。这些工具本身不需要额外配置装好后把终端默认配置文件设置成pwsh或Git Bash就行。接下来是Node.js。Codex CLI本身是npm包所以Node.js是硬依赖。到nodejs.org下载LTS版本安装时保持默认选项即可。装完开一个新终端验证node -v npm -v如果你看到版本号明显偏旧或者提示找不到命令那大概率是安装时没把Node加入PATH。重装Node.js时选“Add to PATH”即可不要手动去改系统环境变量容易改坏。Git也很有必要Superpowers用git clone拉取最方便之后更新技能也只需要git pull。Git for Windows安装时如果问你PATH选项选第二项“Git from the command line and also from 3rd-party software”就好这样PowerShell里也能直接用git命令。2.2 安装Codex CLI本体并通过验证Superpowers是Codex CLI的插件必须先把Codex CLI装好。在终端执行npm install -g openai/codex装完后重新打开一个终端执行codex --version。如果能看到版本号说明安装成功。如果提示codex不是内部或外部命令最常见的两个原因一是npm全局目录没有加入PATH二是安装过程被安全软件打断。查看npm全局目录的位置用npm config get prefix通常输出的是C:\Users\你的用户名\AppData\Roaming\npm把这个目录加到用户环境变量PATH里重启终端再试。Windows上很多Codex相关报错的根源都是这里后面第5章还会再展开。首次运行Codex CLI还需要登录账号执行codex login按提示完成即可。这一步不做后面配置Superpowers也不会生效因为模型根本调用不起来。2.3 顺手确认用户目录和项目目录的路径Windows终端里~会被正确展开成用户目录但从脚本或配置文件的角度看它不认识~。Superpowers的技能目录通常会放在C:\Users\你的用户名\.codex\skills或C:\Users\你的用户名\.superpowers下我建议先执行一次echo $env:USERPROFILE把输出记下来后面所有路径都用这个前缀而不是手写C:\Users\你的用户名否则路径一旦打错排查起来特别费劲。这一步看起来无关紧要但我见过太多人在复制教程命令时把用户名写错结果所有路径都对不上。3. Superpowers在Windows上的完整安装流程3.1 拉取源码clone还是下载zip先到GitHub上找到obra/superpowers这个仓库把代码拉到本地。推荐clone方式git clone https://github.com/obra/superpowers.git $env:USERPROFILE\.superpowersclone的好处是后续更新技能只需要cd $env:USERPROFILE\.superpowers git pull不用重复下载。如果网络和GitHub之间有延迟或中断clone失败的话就换下载zip的方式打开仓库页面点Code按钮选择Download ZIP解压到C:\Users\你的用户名\.superpowers。这里有一个很容易踩的坑zip解压出来后通常会带一层外层文件夹比如superpowers-main直接把整个外层文件夹改成.superpowers用也行但要注意最后技能的路径必须是C:\Users\你的用户名\.superpowers\skills。如果你发现解压后里面还有一层superpowers-main就把里面的内容拷贝到.superpowers而不是保留双层目录。3.2 运行安装脚本Git Bash和PowerShell两条路在Windows上安装Superpowers建议优先用Git Bash因为官方安装脚本是bash写的。打开Git Bash执行cd ~/.superpowers bash install.sh脚本会做两件事把技能文件复制到Codex CLI的技能目录然后在Codex的配置文件里写入启用技能的相关设置。脚本执行过程中如果遇到权限问题在Git Bash里通常不会出现因为Git Bash对路径的处理方式更接近Linux。如果你坚持用PowerShell并且仓库里有PowerShell安装脚本可以执行Set-ExecutionPolicy -Scope CurrentUser RemoteSigned cd $env:USERPROFILE\.superpowers .\install.ps1第一行把当前用户的执行策略设为RemoteSigned意思是只运行有签名的远程脚本本地脚本不受限制。这是Windows上运行.ps1脚本的常规操作安全级别不算低。设置完再执行安装脚本就正常了。如果你发现仓库里根本没有install.ps1或者PowerShell脚本执行时各种报错不用硬扛还有最笨但最稳的一招——手动复制。在PowerShell里执行New-Item -ItemType Directory -Force -Path $env:USERPROFILE\.codex\skills Copy-Item -Recurse $env:USERPROFILE\.superpowers\skills\* $env:USERPROFILE\.codex\skills\这条命令的含义很简单先创建~/.codex/skills目录然后把Superpowers的skills目录里的所有文件复制过去。手动复制的缺点是后续更新技能时要重新复制但在Windows上它最不容易出错适合刚上手的时候。3.3 编辑config.toml让Codex CLI真正加载技能技能文件放到位只是第一步还要让Codex CLI知道去哪个目录读技能。你先执行codex config edit检查配置是否已经被安装脚本更新。如果里面还没有技能相关设置或者你觉得脚本写的位置不对就手动改。配置文件在C:\Users\你的用户名\.codex\config.toml直接用记事本打开notepad $env:USERPROFILE\.codex\config.toml如果文件不存在就新建一个然后加入类似下面的配置[experimental] skills C:/Users/你的用户名/.superpowers/skills这里有个Windows特有的坑TOML解析反斜杠转义所以如果你用Windows风格路径就要写双反斜杠[experimental] skills C:\\Users\\你的用户名\\.superpowers\\skills两种写法都能用正斜杠在Windows里完全合法而且不需要转义我自己一般用正斜杠也建议你直接用正斜杠省事。需要提醒的一点是不同版本的Codex CLI对技能配置的写法可能不太一样有的版本用experimental.skills有的版本可能换成了别的键名。如果你按上面的写法配置后技能没生效去Superpowers仓库的README里搜一下当前推荐的配置写法以仓库文档为准。我写这篇的时候用的是当前主流版本的写法但工具链更新很快版本差异永远优先听官方文档的。3.4 验证安装结果跑一个最小任务配置改完后最重要的环节到了——验证它真的生效了。重新打开一个终端执行codex进入交互会话先问一句你现在加载了哪些技能如果Superpowers生效了Codex的回复里会提到它的引导技能并且主动列出计划、调试、TDD、重构、代码审查等技能清单还会询问你这次会话用哪个技能。如果你的版本没有这种直接列清单的行为就用一个小任务来验证。找个测试项目输入请使用TDD技能为这个项目新增一个简单的数学工具函数。然后观察Codex的行为它应该先写计划再写失败的测试实现函数最后跑测试确认通过。如果它上来就直接写函数、完全不提测试那说明技能没被加载技能目录或配置大概率有问题。这个验证步骤特别重要因为Superpowers安装完不会弹窗告诉你“安装成功”它的一切效果都体现在模型的对话行为里。我见过好几个人装完以为失败了其实只是没有用对验证方式。4. 实际使用Superpowers的典型流程4.1 技能是怎么被“触发”的Superpowers的技能不是常驻内存的巨型提示词而是按需加载的一组文档。模型在对话中感知到任务类型后会找到对应技能的SKILL.md文件读取指令再按步骤执行。我第一次用的时候觉得它很神奇理解机制之后觉得设计确实聪明省上下文窗口精准触发而且任何人都能用Markdown新增技能。你可以把技能文件想象成菜谱。模型不是把整本菜谱都背下来才进厨房而是接到订单后翻到对应那页按上面的步骤做。所以技能的质量决定了Codex执行任务时的专业程度。Superpowers里做得比较完善的是debugging和TDD技能这两个也是我日常用得最多的。4.2 一次TDD流程的完整演示拿最常见的需求举例。我在一个Python项目里对Codex说请用TDD技能为这个项目新增一个函数功能是把字符串反转。收到指令后Codex先加载TDD技能的说明然后在对话里输出计划大致是先建测试文件写三个用例——空字符串、单个字符、多个字符运行测试看到失败实现反转函数再次运行看到测试通过最后做一次小重构并确认测试仍然通过。对这就是我们平时说的红灯-绿灯-重构。没有Superpowers的时候你大概率要手动把这一段流程一点一点喂给Codex。现在你只需要说一句“用TDD技能”它就会自动按这个流程走。如果你觉得它的测试用例覆盖不够还可以补充一句“再加一个Unicode用例”它会在技能框架内调整。4.3 技能不是银弹但能把烂摊子变得可收拾Superpowers最值钱的地方不是让Codex一次写出完美代码而是把“怎么干活”的流程固定下来了。上了年纪的老系统重构重构技能会强制它先建立行为基线再要求你确认改动范围最后才动手。这种“先把规则讲清楚再执行”的做法对单人小项目可能显得繁琐但放在多人协作或老项目里能避免非常多安全事故。我建议刚上手的人哪怕只是个人项目也先适应一下它这个节奏。一开始可能会觉得麻烦但当你被自己项目的测试坑过几次之后你会感谢自己养成了这个习惯。5. Windows常见问题与排查技巧实录5.1 桌面端报“unable to locate the codex cli binary”怎么修这个报错在Windows上出现频率极高尤其是在新版的ChatGPT桌面应用或某些IDE扩展里。它的大意是应用启动时想调用codex CLI的可执行文件但找不到。注意这不代表你的Codex CLI没装好而是那个应用查找codex可执行文件的路径时失败了。排查顺序很简单。先打开PowerShell执行where codex看能不能输出路径。能输出说明codex在PATH里不能输出说明PATH里没有codex。接着执行npm config get prefix确认npm全局目录然后把这个目录加到用户PATH。再确认Node.js本身正常node -v能输出版本。改完PATH后要重启终端、重启桌面应用因为应用启动时读取的环境变量不会自动刷新。如果上述都正常还报错重装一次npm install -g openai/codex。这个报错还有一个变体就是新版应用要求更高版本的Node运行时或者要求系统里装某个运行时组件。检查Node版本是否符合Codex CLI的要求太旧就升级到LTS。5.2 PowerShell执行策略禁止运行install.ps1脚本症状运行install.ps1时报“系统禁止运行脚本”或“未授权”。解决Set-ExecutionPolicy -Scope CurrentUser RemoteSigned只对当前用户生效不改系统级策略。开新终端执行脚本前再次确认一下有些安全软件会帮你把执行策略改回去。注意这个命令只需要在安装时执行一次日常使用Codex CLI不受影响。5.3 PowerShell里的curl被别名坑了怎么办症状照抄官方文档的curl -sSL https://... | bash报参数错误或者下载出来一堆乱码。原因PowerShell把curl解析成了Invoke-WebRequest的别名。解决先看提示里的完整参数名如果能接受就改用curl.exePowerShell会直接调用真正的curl程序。最省心的方式还是换到Git Bash里执行bash命令别在PowerShell里硬刚。Git Bash自带的curl就是大家熟悉的那个curl行为一致。5.4 安装脚本跑到一半卡住或被杀毒软件拦下Windows Defender和一些第三方安全软件会把安装脚本检测为“可疑行为”尤其是脚本里有大量的文件创建和进程调用。解决思路把.superpowers和.codex目录加入安全软件的白名单如果网络不好导致git clone反复失败检查网络连接是否正常没有异常就重试。如果多次失败就改用下载zip的方式。这里不建议关掉实时防护——没必要为了装一个工具把自己的电脑暴露在风险里。多数安装脚本卡住问题重试一次基本能过反复失败才需要往权限和磁盘方向排查。5.5 技能文件都复制了但Codex就是不加载最常见的原因有三个一是技能目录路径和配置里的路径对不上比如配置写的是~/.superpowers/skills但你的技能实际在C:\Users\xxx\.codex\skills二是配置键名不对不同版本写法不同三是改了配置后没有重启codex会话。检查顺序很固定先确认配置指向的目录真实存在再确认目录下确实有SKILL.md文件最后重启会话再试。也可以直接在对话里问它“你现在加载了哪些技能”能答出来就说明通了。5.6 提示“codex windows安装未完成”怎么办这个报错我遇到过几次最容易出现在新版桌面应用安装Codex组件或者npm安装中断的场景。你可以先清理npm缓存npm cache clean --force再删除%APPDATA%\npm\node_modules\openai\codex目录重新执行npm install -g openai/codex。如果是桌面应用安装组件失败检查磁盘剩余空间并确认安装目录有写入权限。安装类问题大多数重试一次就能过反复失败才需要往权限和磁盘方向排查。下面把这一章的典型问题整理成速查表症状常见原因处理方式codex不是内部或外部命令npm全局目录不在PATH把npm config get prefix返回的目录加入用户PATH重启终端unable to locate the codex cli binary桌面应用找不到codex可执行文件或Node运行时检查PATH、检查Node版本、重装codex重启应用install.ps1提示禁止运行脚本执行策略限制Set-ExecutionPolicy -Scope CurrentUser RemoteSignedPowerShell里curl命令报参数错误curl是Invoke-WebRequest别名用curl.exe或改用Git Bash技能加载不出来路径不一致或配置键名不对核对配置路径和配置键参考仓库README重启会话6. 收尾Windows上装Superpowers的一点体会我个人的建议如果用Windows原生环境第一次安装Superpowers时别追求“一条命令跑完”老老实实走手动流程把clone、复制技能、改配置这三步每一步都看清楚结果反而最快。我一开始图省事复制官方bash命令结果在PowerShell里翻了车后来换成Git Bash一条命令过再后来为了给同事写文档又专门用PowerShell手动跑了一遍从此再也没踩过坑。另外装好之后多花十分钟把Superpowers自带的几个技能说明翻一遍特别是debugging和refactoring理解它要求Codex遵守哪些流程。这不是浪费时间因为真正影响你日常体验的不是“装没装”这个动作而是你能不能把它变成自己的习惯并在自己项目里针对性地调整或新增技能。后续我可能会再写一篇“自定义Superpowers技能”的内容如果大家在实际使用中遇到其他Windows专属问题也欢迎在评论区交流我再补充进去。