如果你已经跟我把 Codex CLI 跑起来并且在 Windows 终端里敲过几次codex你可能会有这种感觉这工具能用但用起来多少有点“没头没脑”。你跟它说写一个登录页它真的会唰唰给你写一个登录页但你要是让它改一个三个月前的老模块它能把自己的思路绕进去写了又改、改了又删最后给你留下一个没有测试、没有提交记录、也没人敢合的分支。出现这个问题的原因并不是 Codex 的模型不够聪明而是你在用它的时候没有给它一套“干活的方法论”。这也是我想在这个系列第四篇里聊 Superpowers 的原因它给 Codex CLI 补上的正是这一层——用一批预设好的技能让代理先规划、再动手、边写边验证而不是让模型自由发挥。这篇教程面向的是 Windows 用户。网上关于 Superpowers 的讨论不少但很多默认你是 Mac 或 WSL 环境真正把 Windows 上那些坑讲清楚的并不多。如果你已经装好了 Codex CLI想让它从“偶尔惊艳的工具”变成“稳定靠谱的同事”这一篇应该能帮上忙。1. 先别急着复制命令搞清楚 Superpowers 到底替你做了什么事很多人安装这类东西习惯性git clone一把梭看到进度条走完就觉得自己装好了。但 Superpowers 不是那种装完就完事的工具它的用法决定了你是不是真的装对了。所以我先把原理讲明白这样你在排错时也能知道问题出在哪个环节。1.1 裸 Codex 和带技能的 Codex差别在“有没有章法”裸的 Codex CLI 本身是个很纯粹的助手你给它一句话它给你一段代码。它背后的大模型很强强到让很多人误以为“只要我描述得够清楚它就能输出好结果”。但实际用上一周你就会发现真正拖后腿的往往不是生成能力而是任务处理路径太随意。举个例子你让它修一个 bug。裸 Codex 的做法通常是扫一眼相关代码命中某个可疑点直接改给你顺利的话你还能收到一句“问题应该解决了”。问题在于它没有“先复现问题再动手”的纪律也没有“改完以后跑一遍相关测试”的自觉更不会主动确认这个改动会不会连带影响其他模块。模型本身其实知道这些步骤只是你给的提示没有强制它按这个路径走它就选了最省事的生成路径。Superpowers 做的就是这件事把一套成熟的工程方法论拆成一堆 Markdown 格式的技能文件注入到 Codex 的工作上下文里。每个技能都有明确的触发条件和执行步骤。比如它可以让 Codex 在动手写代码前先输出一份任务拆解清单或者在改完代码后把边界条件、验收标准、测试计划单独列出来。1.2 技能的本质是“给模型的剧本”不是“给程序的插件”对于第一次接触这个概念的人我建议你把它理解为“剧本”。Superpowers 里的技能文件只是文本里面写了“当你接到这类任务时请按以下顺序执行第一步做什么第二步做什么每一步的输出格式是什么”。Codex 读取这些文本后就会照着剧本来表演而不是即兴发挥。这样设计的最大好处是你不需要懂插件开发也能自定义技能。你打开技能文件看到里面就是普通的人类语言指令你想让 Codex 在输出前多问一个问题直接改文字就行。这可比写代码、调接口友好太多了。所以安装 Superpowers本质上做的是三件事把技能文件放到 Codex 能读到的目录里让 Codex 在启动时知道这些文件的存在通过一条提示语触发具体技能。后面安装流程里所有命令都是围绕这三件事展开的。为了让你更直观地感受到差别我把裸 Codex 和加上 Superpowers 之后的 Codex 做个对比维度裸 CodexCodex Superpowers任务启动方式直接给一段话就开干先调用技能再按流程执行复杂任务处理自由发挥容易反复横跳先拆解成步骤再逐步推进代码审查偶尔做做得不彻底有明确审查流程甚至可触发子代理出错恢复改来改去可能越改越糟按步骤回退有验收标准上下文控制全部压在一次提示里按技能按需加载上下文更聚焦熟悉这套玩法后你就知道 Superpowers 解决的不是“Codex 不够强”的问题而是“Codex 太自由”的问题。2. 装之前先把 Windows 环境收拾利落不然命令一样会翻车我见过太多人卡在这一步明明教程里的命令是照着敲的结果报错报得莫名其妙。其实多半不是 Superpowers 的问题而是 Windows 环境本身埋了雷。这里列几个最常见的检查项每一步都有必要亲自确认一遍不要跳过。2.1 Node.js 版本别太老也别太新Superpowers 依赖 Node.js 来跑安装脚本和部分辅助命令。Windows 上安装 Node.js 本身就很简单官网下载 LTS 版本一路 Next 就行。但这里有个隐藏陷阱很多 Windows 用户电脑里可能同时存在多个 Node 版本或者装了某个软件自带的旧版 Node命令行里node -v显示出来的版本和你想的根本不是同一个。建议你在 PowerShell 里执行两个命令确认node -v npm -v我实测下来Node.js 18 LTS 往上都问题不大20 和 22 更稳。如果你用的是 16 甚至更老的版本建议先升级。这不是我在制造焦虑而是 Superpowers 里有些脚本用到了比较新的语法Node 版本老了会直接报语法错误那种报错很容易让人误以为是安装步骤出了问题。再说一个细节确认 npm 全局包安装路径。Codex CLI 本身很可能是通过 npm 全局安装的运行npm root -g可以看到全局目录。把路径记下来后面排错时可能会用到。如果这个目录在C:\Program Files\nodejs等带空格的路径下部分命令行工具在解析时也可能出问题到时候记得优先怀疑路径空格。2.2 Git for Windows 必须装但别忽略了执行策略Superpowers 是从 GitHub 仓库克隆下来的所以 Git 是硬性依赖。Windows 上装 Git 之前先检查一下git --version如果提示没有这个命令去 Git 官网下载 Windows 版安装包。安装时我建议保持默认选项尤其是“Git from the command line and also from 3rd-party software”这个选项这样才能在 PowerShell 里直接调用 git。但光装了 Git 还不够。Windows 的 PowerShell 默认执行策略大概率是Restricted这就意味着你下载或克隆下来的.ps1脚本、甚至某些.js文件在调用时都可能被系统拦下来。运行时你会看到类似“因为在此系统上禁止运行脚本”的报错看起来很不讲道理。解决办法是调整当前用户的执行策略Set-ExecutionPolicy -Scope CurrentUser RemoteSigned参数RemoteSigned的意思是本机创建的脚本可以运行从网络上下载的脚本必须经过签名。这个设置比Unrestricted安全得多也足够日常使用。如果你不敢随意改可以先用Get-ExecutionPolicy看一下当前值再决定要不要动。2.3 路径里面出现空格或中文用户名是你的第一号敌人Windows 用户目录默认是C:\Users\你的用户名如果你的 Windows 登录名是中文或者姓名字段里带了空格那安装 Superpowers 时很容易踩坑。原因不复杂很多 Node 脚本在解析路径时会用空格来拆分参数。路径一有空格脚本就把一个完整路径硬生生拆成了两段然后对着不存在的文件报错。你说它离谱吧它在 Windows 上就是这么真实。解决方案有两个。一个是把仓库克隆到一个全英文、无空格的纯路径下比如C:\tools\superpowers然后在配置里用这个绝对路径。另一个是通过环境变量指定技能目录具体在下一节安装流程里会说到。为了让你提前有个概念我列一个路径规划表项目推荐路径不推荐路径Superpowers 仓库C:\tools\superpowersC:\Users\张三\Downloads\superpowersCodex 技能目录C:\Users\你的用户名\.codex\skillsC:\Users\My Name\.codex\skills临时下载目录C:\tempDesktop\新建文件夹如果你已经装了 Codex CLI应该知道.codex目录就在用户主目录下。Windows 下创建这个目录本身没问题问题只在于里面的技能文件能不能被正确加载。路径长得越规矩后面省的事越多。3. 正式安装流程克隆、装依赖、注册技能一件件来这节进入正题。我会用最标准的 PowerShell 操作演示一遍完整流程并且把每一步背后做的事情说清楚这样你不管是按步骤执行还是想自己微调心里都有底。3.1 把 Superpowers 仓库放到一个稳定位置先打开 PowerShell切到你准备好的干净路径下。我这里按C:\tools举例cd C:\tools然后克隆仓库git clone https://github.com/obra/superpowers.git superpowers克隆期间如果网络不稳定可能会中断。Windows 上遇到这种情况最常见的原因是安全软件实时扫描拖慢了 Git 的写入速度并不一定是你的网络有问题。真遇到克隆到一半卡住先等一会儿再不行就删掉半成品目录重新克隆一次。克隆完成后进入仓库目录cd superpowers这时候你可以先看一眼目录结构确认skills文件夹确实存在。ism那里面装的就是技能文件。3.2 安装依赖并执行注册脚本Superpowers 本身带了一些辅助脚本需要先安装依赖npm install这一步会生成node_modules目录安装过程可能需要一两分钟。如果网络不出问题你看到类似added 100 packages的输出就说明依赖装好了。接下来是注册。Superpowers 有配套的安装命令不同版本命令可能略有差异以我目前常用的版本为例npx superpowers install codex如果这个命令在你当前版本里不存在不要慌。你可以先运行npm run看一下仓库里有哪些可执行脚本通常会发现类型install:codex或者setup这样的选项挑名称带 codex 的那个执行即可。这条命令做的事情说穿了也不神秘它会把skills文件夹里的技能文件复制或者链接到 Codex CLI 的技能目录里也就是C:\Users\你的用户名\.codex\skills。如果你的机器上还没有.codex目录脚本会顺手创建一个。3.3 手动绑定技能目录备用方案有时候受限于权限或者版本问题自动注册命令就是跑不起来。这时候也别折腾了用手动方案一样能成而且原理更透明。如果你只是想让 Codex 能用上技能最简单的方法是把技能目录复制过去$codexSkills $HOME\.codex\skills New-Item -ItemType Directory -Path $codexSkills -Force Copy-Item -Path C:\tools\superpowers\skills\* -Destination $codexSkills -Recurse如果你想用链接方式让技能目录始终跟随仓库更新那可以用符号链接。注意Windows 上创建符号链接需要开发者模式或管理员权限。PowerShell 里执行New-Item -ItemType SymbolicLink -Path $HOME\.codex\skills -Target C:\tools\superpowers\skills如果提示没有权限可以改用传统方式在管理员权限的命令提示符或者 PowerShell 里执行cmd /c mklink /D %USERPROFILE%\.codex\skills C:\tools\superpowers\skills无论哪种方式最后你打开资源管理器看到C:\Users\你的用户名\.codex\skills目录里躺着todos、brainstorming、subagents这些子文件夹就说明技能文件已经就位。3.4 让 Codex 每次启动时都能感知技能文件就位之后还差一步让 Codex 知道该去哪里找技能。Codex CLI 启动时会读取当前用户目录下的AGENTS.md文件Windows 下就是C:\Users\你的用户名\.codex\AGENTS.md如果这个文件里写明了技能目录的路径和用法Codex 在会话开始后就会自动把技能拉入视野。你可以在.codex目录下手动创建或编辑AGENTS.md加入类似下面的内容# Codex 全局指令 - 技能目录位于 ~/.codex/skills - 当用户要求使用某项技能时先读取对应技能目录下的技能说明文件再按技能说明执行 - 常见技能包括todos任务拆解、brainstorming方案讨论、subagents子代理执行这里有个很容易被忽略的 Windows 细节Codex CLI 对~的处理在绝大多数情况下是正常的但如果你是在自定义配置里写路径我建议直接把~展开成完整路径减少解析问题的概率。改完配置文件后最好重新打开一个终端窗口让 Codex 重新加载环境。这一步经常被忽略很多人改完配置发现没生效其实只是没有重启终端。4. Windows 上最常见的四个安装报错我一个个帮你拆掉了安装这件事照着流程做一般不会出大问题。真正让人崩溃的是报错。我把 Windows 环境下最常遇到的几个坑整理出来每个都会说清楚现象、原因和解决路径。你照着这个思路排查能省下大量在搜索引擎里翻答案的时间。4.1 现象一PowerShell 死活不让你跑脚本报错提示可能是这样的无法加载文件 C:\tools\superpowers\scripts\setup.ps1因为在此系统上禁止运行脚本看见这个报错先别怀疑人生它跟你的脚本一点关系都没有。这就是 PowerShell 默认执行策略Restricted在起作用。解决方式我在前面提过直接运行Set-ExecutionPolicy -Scope CurrentUser RemoteSigned执行完以后再跑一次之前的命令。如果还报错确认一下你是否把作用域写对了。只写在CurrentUser范围就够了可以不动系统级策略。4.2 现象二git clone 到一半提示文件名过长Windows 的老牌毛病。Superpowers 技能文件里有一些嵌套层级比较深的路径Windows 默认的MAX_PATH限制是 260 个字符一旦路径超过这个长度Git 就会报错。解决办法是在 Git 里开启长路径支持git config --global core.longpaths true设置完后删掉克隆了一半的目录重新克隆一次。如果还是不行那就是 Windows 系统级的长路径支持没打开。进“设置—系统—系统信息—高级系统设置—环境变量”新增一个系统变量变量名LongPathsEnabled 变量值1改完重启终端再试。这一步在程序员群体里其实很常见解决后几乎一劳永逸。4.3 现象三安装脚本执行时报错看起来和换行符有关这类报错很隐蔽。Windows 上 Git 默认会把代码仓库里的LF换行符自动转成CRLF而 Superpowers 的脚本大多是在 macOS/Linux 环境下写的两者换行符不一致轻则脚本行为异常重则直接报错。解决方法是关闭 Git 的自动换行转换。你可以在克隆仓库前设置git config --global core.autocrlf false如果你已经克隆完了仓库可以进入仓库目录后执行git config core.autocrlf false然后把仓库删掉重新克隆确保换行符已经是原样保留。我不建议你手动用编辑器去把所有文件转一遍那样容易改坏其他内容重新克隆是最干净的。4.4 现象四技能装好了但 Codex 回答时完全没反应这类问题最气人因为安装步骤看起来全都成功了。你在 Codex 里提到“使用 todos 技能”它却像没听见一样照旧直接给你写代码。排查路径应该按下面这个顺序走确认AGENTS.md文件内容正确并且放在C:\Users\你的用户名\.codex\下重新打开终端让 Codex 重新加载在当前项目目录下打开 Codex确认它是把AGENTS.md读进去了。你可以在提示里直接问它“你读了哪些指令文件”它会如实回答。如果它说没读到检查路径。Windows 下最容易犯的错就是用户目录判断错误。你可以在 PowerShell 里执行echo $HOME看看输出结果是不是C:\Users\你的用户名。如果输出跟你预想的不一样说明终端当前用的用户环境有问题所有配置都要按实际输出路径调整。5. 安装验证用一个真实任务观察技能是否真正接管了 Codex装完之后最让人心痒的就是想知道到底成没成。我强烈建议你不要只盯着目录结构看而是实际跑一个任务通过 Codex 的行为变化来判断。5.1 先检查技能文件的完整状态做完前三步你应该能在C:\Users\你的用户名\.codex\skills下看到类似下面的结构skills/ todos/ SKILL.md brainstorming/ SKILL.md subagents/ SKILL.md ...如果技能文件都在说明安装环节已经成功。这时候可以进入下一步验证看 Codex 的运行行为。5.2 用一段能触发技能指令的提示词测一次在 PowerSheell 里进入一个临时目录比如C:\temp\test启动 Codexcd C:\temp\test codex然后输入一段带明确技能指令的提示例如请使用 todos 技能帮我规划一次登录模块的重构先不要写代码只输出任务拆解清单。如果 Superpowers 生效你会看到 Codex 的行为明显区别于裸跑它不会急着生成代码而是先输出一张结构化的清单。清单里可能会包含“确认现有登录流程”“梳理接口依赖”“划分重构步骤”“制定测试方案”这样的条目。不夸张地说这一步是判断安装是否成功的金标准。目录再好看Codex 的行为没变化那都是白搭。5.3 用日志确认 Codex 到底读没读指令如果你观察不到明显变化不要急着下结论。执行codex --verbose进入会话重新跑一次同样的提示然后看日志输出。不同版本的 Codex 日志输出格式不同但一般会包含“loading instructions from ... AGENTS.md”之类的内容确认它确实读取了全局指令文件。如果日志里没有相关记录问题大概率还是出在路径或文件名上。Windows 上大小写不敏感是常态但某些版本对隐藏文件.codex目录的识别反而有细微要求。确认一下.codex目录是不是真的在用户主目录下而不是在某个项目的根目录下。6. 装好只是开始Windows 下的日常使用细节值得你多留个心眼安装成功后真正的日常使用才算开始。以下几条是 Windows 环境下使用 Superpowers 的一些经验总结每条都是我实际用下来觉得有价值、值得提前注意的。6.1 符号链接和复制目录按你的更新习惯选我在前面提到过两种绑定技能目录的方式符号链接和直接复制。日常使用中选哪种主要看你对更新频率的预期。如果你希望 Superpowers 上游仓库一更新技能就自动同步那就用符号链接。每次启动 Codex它读到的是仓库里的实时文件。代价是如果你手动改了技能文件可能被上游更新覆盖。如果你更希望自己定制技能内容并且不想被上游改动打扰那就用复制目录。缺点是要手动同步更新升级时比较麻烦。我的习惯是基本不动上游技能只新增自己的技能文件。这种情况下复制目录反而更稳当。6.2 项目内的技能调用建议把本目录的 AGENTS.md 也配好Codex 不仅会读取用户全局的AGENTS.md它也可能读取当前项目目录下的AGENTS.md。这在多项目工作中非常实用。你可以在某个项目的AGENTS.md里写明这个项目特有的约束比如“禁止使用某个依赖包”“所有接口必须写单元测试”“代码风格遵循 eslint 配置”这样当你在该项目里调用 Superpowers 技能时Codex 会把项目约束和通用技能结合起来输出结果的质量会明显提升。这一点在 Windows 上尤其值得注意因为很多开发者是直接在 Windows 上跑项目而不是在 WSL 里全局配置和项目配置的层级关系容易搞混。你可以在项目目录下用一条命令临时测试codex 告诉我你读过哪些 AGENTS.md如果它列出的文件里包含当前项目的配置说明项目级配置加载正常技能跟配置的协同机制是通的。6.3 更新技能库的方法其实比你想的更简单Superpowers 本身就是 Git 仓库所以更新逻辑很简单。进入仓库目录cd C:\tools\superpowers git pullpull 完成后如果装的是依赖变了再跑一次npm install。如果你用的是符号链接技能文件会自动同步不需要重新把技能注册一遍。如果你用的是复制目录那就再复制一次技能文件Copy-Item -Path C:\tools\superpowers\skills\* -Destination $HOME\.codex\skills -Recurse复制时如果遇到文件占用报错先关闭正在运行的 Codex 会话再试。Windows 下文件锁是很常见的问题不用慌关掉占用它的程序就行。6.4 UTF-8 乱码问题提前设置一劳永逸Windows PowerShell 的默认编码在很多版本下还是跟 UTF-8 有点不对付。Superpowers 技能文件里的中文、表情符号或者其他 Unicode 字符在旧版终端里可能会显示成乱码虽然不影响脚本执行但很影响排查问题。建议你在 Windows Terminal 的设置里把默认代码页切成 UTF-8。也可以在 PowerShell 里执行chcp 65001这种设置只对当前窗口有效想要全局生效就去系统区域设置里勾选“使用 Unicode UTF-8 提供全球语言支持”。注意这个选项可能影响部分老软件的显示动手前自己权衡一下。我实际用下来开发环境里基本都是 UTF-8改了之后几乎没有副作用。6.5 给自己留一个“无技能”的备用法最后分享一个我自己的习惯。Superpowers 很香但不是每个任务都必须用它。简单到一句话就能说清楚的改动强行套技能流程反而是负担。当你需要快速验证一个想法时直接在纯 Codex 环境下跑就好。等想法开始变得复杂、需要多文件改动时再切换回技能模式。这种“按需切换”的使用方式才是把工具价值最大化的关键。我在实际使用中发现Superpowers 最让我上瘾的不是它让 Codex 变“听话”了而是它在不知不觉中帮我把项目里那些“应该做但总忘做”的事情补齐了——写测试、列计划、确认边界条件。这些东西过去靠人盯着现在靠一套技能文件稳定执行不闹情绪。如果你在 Windows 上把技能装好、跑通、用顺手了你会发现 Codex 从一个“写代码很快的实习生”慢慢变成了“有自己工作节奏的同事”。这个转变比任何一次升级带来的快感都踏实。