如果你也把 Codex CLI 当成日常写代码的搭子，一定遇到过这种尴尬：让它看一眼设计稿，它礼貌回复“我只能处理文本”；让它扒一个网页，它老老实实给你 curl 回来一堆 HTML 标签；让它查点资料，它只能凭训练时的记忆瞎猜，连个出处都没有。最近我一直在折腾一个叫superpowers的开源项目，它正好就是冲着这些短板去的。简单说，superpowers 是一套给 Codex CLI 加“技能系统”的扩展方案，通过结构化技能文件、项目级挂载和外部工具接入，让 Codex 从“只会读写终端文本”的工具人，变成能看图、能抓网页、能跑深度研究的助手。这篇内容适合两类人：一是已经在用 Codex CLI 但觉得它不够聪明的开发者，二是刚听说 Codex 想把它用在真实项目里的新手。我会把安装、配置、核心技能、实战过程、常见坑一次性讲透。
1. 为什么需要 superpowers：先搞清楚 Codex 的边界在哪
1.1 Codex 已经很能打，但它是个“近视眼”
Codex CLI 是 OpenAI 推出的命令行编程 Agent，跑在终端里，能读你的代码仓库、改文件、执行命令、跑测试、甚至自己修 bug。我用了很长一段时间，坦白说它在“改代码”这件事上确实有一手：给它一个报错信息，它能顺着调用栈定位到文件，改完跑一遍测试确认通过。但你让它跳出纯文本的舒适区，问题就来了。
最典型的三类场景，Codex 原生几乎是无能为力的：
- 看不见图像。设计稿、截图、UI 效果图、PDF 里的图表，在 Codex 看来就是一坨二进制数据，它不知道图里画了什么。程序员日常恰恰离不开设计稿，前端开发尤其痛苦。
- 不能主动访问网页。它确实能在你的终端里执行 curl，但 curl 拿到的是原始 HTML，真正的正文内容、排版结构、关键信息全埋在标签和脚本里，靠人眼都费劲，让模型去硬啃更不现实。
- 长文档处理很粗糙。一个几十页的 API 文档、一份冗长的竞品分析报告，你没法“丢”给 Codex，它也没有系统的办法把核心信息抽取出来。
这不是 Codex 模型能力不行，而是它的工作形态太“干净”了：一个终端，一堆文本流。真实开发中我们要面对的是屏幕上的像素、网页里的多媒体、格式复杂的文档，这些信息形态 Codex 原生根本接不住。
1.2 superpowers 到底给 Codex 加了什么
superpowers 的做法不是给模型加魔法，而是建立了一套技能（Skills）机制。它把高频操作沉淀成结构化的 Markdown 技能文件，每个技能文件里写清楚：这个技能解决什么问题、什么条件下触发、执行分几步、每一步具体怎么做、输出格式是什么、有哪些注意事项。
然后在项目里通过AGENTS.md这个文件把技能“挂载”给 Codex。Codex 每次启动都会读取项目里的AGENTS.md，发现在这个项目里可以做哪些事，需要时再去读具体的技能文件，按步骤执行。
这套设计的好处特别明显。首先，它能复用。我在 A 项目里调好的一套“抓取网页并提炼要点”的流程，B 项目直接就能用，不用每次重新描述需求。其次，它稳定。直接跟模型说“帮我看看这个网页”是模糊指令，能不能做好全看模型心情，而技能文件是精确步骤，Codex 会一格一格地走。最后，它可审查。技能是纯文本，写得好不好、有没有安全隐患，打开文件一眼就能看到，比黑盒 prompt 强太多。
此外，superpowers 还支持通过 MCP（Model Context Protocol）把外部工具接进来。模型不需要自己“知道”某个工具怎么用，只需要按技能文件里的说明去调用，工具返回的结果再交给模型分析。这也是为什么这个项目敢叫 superpowers——它等于给 Codex 装了一套可扩展的“外设驱动”，装什么驱动，就有什么超能力。
2. 安装与初始化：从零搭建带“超能力”的 Codex
2.1 装前准备：先把地基打牢
superpowers 是对 Codex CLI 的扩展，前提是你已经装好并登录了 Codex CLI。如果你还没装，先做这一步：
# 安装 Codex CLI npm install -g @openai/codex # 确认安装成功 codex --version第一次运行codex会引导你登录 OpenAI 账号，按提示操作即可。装好 Codex 之后，再来准备 superpowers 的环境，要求不多，但容易忽略：
- Node.js 版本最好在 18 以上。我用 Node 16 试过一次，各种依赖报错，升到 20 之后一路畅通。建议先
node -v查一下，低于 18 就先升级，别在版本问题上浪费时间。 - 建议准备一个干净的测试项目目录专门做安装演练。superpowers 安装时会往项目里写文件、改
AGENTS.md，在一个空目录里先跑通，比直接在生产仓库里折腾要稳妥得多。 - 确认网络能正常访问 npm registry。这个听起来像废话，但实际很多人卡在安装阶段就是因为 npm 镜像配置问题，后面我会单独讲。
2.2 三步完成安装与项目激活
安装过程比我预想的简单，核心就三步。第一步是全局安装脚手架工具，第二步是运行 install 命令，第三步是检查生成的文件结构。
# 第一步：全局安装 superpowers 脚手架 npm install -g @obra/superpowers # 第二步：在你自己的项目根目录里执行 cd your-project npx superpowers@latest install第二步会做几件重要的事：创建一个隐藏的.superpowers/目录，往里面写入技能文件库；检查项目里有没有AGENTS.md，没有就新建，有就把 superpowers 的技能索引段落追加进去。
跑完之后，用tree或者编辑器看一眼项目结构，正常情况下应该是这样的：
your-project/ ├── AGENTS.md # 被追加了 superpowers 技能索引 └── .superpowers/ └── skills/ # 内置技能文件，按类别分目录存放这里有个关键点：AGENTS.md就是 Codex 读取项目说明的入口文件。superpowers 在AGENTS.md里写了类似“本项目启用了 superpowers 技能系统，常用技能清单如下……”这样的段落，Codex 看到这段就会知道要去.superpowers/skills/里找具体技能定义。如果你发现技能不生效，八成就是AGENTS.md没配好，后面排查部分会再讲。
2.3 config.toml 里的关键配置
superpowers 本身不需要改太多配置，但 Codex CLI 的配置文件里有两个点值得留意。配置文件在~/.codex/config.toml，先打开看看当前内容。
# ~/.codex/config.toml model = "gpt-5-codex" # 或你账号可用的最新模型，重要的是支持视觉输入 [agent.codex] enable_skills = true # 如果存在这个字段，务必确认是 true第一个是model 字段。superpowers 里的图像类技能需要模型支持视觉输入，如果你的模型不带视觉能力，让它读设计稿就会直接报错。我自己的经验是选账号当前可用的最新模型，不仅视觉识别准确，处理长网页抓取结果时也不容易断片。
第二个是技能开关。不同版本的 Codex 配置文件字段名不太一样，新版可能在[agent.codex]下有类似enable_skills的选项。这个字段不是所有版本都有，如果没有就忽略，不用自己硬加，加了反而可能报解析错误。一个小技巧：改完config.toml后重启终端或者重新打开项目目录，确保 Codex 重新读取了新配置。
如果你在团队协作或者多台机器上工作，.superpowers/目录和AGENTS.md的改动务必提交到 Git 仓库。这样团队里其他人 clone 下来就直接具备同样的技能环境，不用每个人重复安装，而且技能文件的版本变更也能通过 Git 记录追溯，出了问题好排查。
3. 核心技能拆解：这些“超能力”分别解决什么问题
3.1 图像与视觉技能：让 Codex“看见”设计稿
我最初被这个项目吸引，就是因为它的图像技能。装好之后，我在项目里做了一次测试：把一张产品原型图丢进去，在对话里明确说“使用图像查看技能，读取docs/ui-design.png，描述整体布局和主要交互元素”。Codex 会读取技能文件，按里面的步骤先确认文件存在、再加载图像、然后分段描述内容。
实际效果确实惊艳。它不仅能描述“这里有左侧导航、顶部有搜索栏”，还能进一步分析元素尺寸比例、颜色搭配、间距规范。我在前端项目里最常用的场景是：把设计稿交给 Codex，让它按照稿子生成 Vue 组件骨架，或者对照稿子检查现有页面差在哪里。
但这里有个使用细节：触发技能时，指令越具体效果越好。只说“帮我看看这张图”，Codex 不一定能联想到技能文件；而“使用图像查看技能读取xxx.png，输出布局描述和组件拆分建议”，基本上百发百中。
实操中还要注意图片尺寸问题。分辨率过高的截图（比如 4K 屏全屏截图）会被模型缩放或截断，信息丢失严重，而且 token 消耗会暴涨。我现在的习惯是先把大图压缩到 1200px 宽以内，在保证清晰的同时控制开销。压缩这一步用系统自带预览工具或者sips命令都行，30 秒搞定，后面能省不少时间和 token。
3.2 网页抓取与信息提取：告别满屏 HTML 噪音
第二类高频技能是网页抓取。以前让 Codex 看一个网页，它只能 curl，然后在一堆 HTML 里挣扎。superpowers 的抓取技能会先把目标 URL 的内容转换成干净的 Markdown 或结构化数据，再交给模型分析，这个预处理环节直接决定了信息提取质量。
我实际测试过几个场景，效果比较稳定：
- 抓 API 文档：写 SDK 封装时，让 Codex 抓取接口文档页面，提取出所有接口路径、请求参数、响应字段，生成 TypeScript 定义和封装函数。
- 抓竞品页面：把竞品官网的某个功能介绍页面转成 Markdown，然后问它“这个功能的卖点描述集中在哪几个部分，用什么词形容用户价值”，有一定参考价值。
- 抓 GitHub README：调研开源库时先抓 README，再让它对比几个库的安装方式、功能特性和维护活跃度。
使用的时候我会明确给出 URL 和输出要求，比如“使用网页抓取技能，访问https://...，提取全部接口路径和参数说明，以表格输出”。如果页面内容很长，建议拆分成几个子任务处理，一次抓一个章节，比一次性全部塞给模型要稳得多。
这个技能也有它的边界：有反爬机制的页面、需要登录才能看的页面、纯 JavaScript 渲染的动态页面，抓取效果取决于页面结构和抓取工具本身的能力。遇到抓取失败或者抓回来是空壳，别硬试，换个思路用浏览器技能或者直接让 Codex 根据用户提供的文本内容分析。
3.3 深度研究技能：让 Codex 学会“做功课”
deep-research 是我最近才认真用的技能，它解决的问题是：让 Codex 不满足于单次搜索或单页抓取，而是像一个做调研的人那样，拆解问题、追查来源、交叉验证、输出带引用的结论。
触发方式和前面类似，我会在对话里说“使用深度研究技能，调研一下 Rust 和 Go 在 CLI 工具开发上的社区生态差异”。Codex 会先拆解关键词（比如 Rust CLI、Go CLI、cobra、clap），然后挨个去抓取搜索结果页面、开源项目 README、技术讨论帖，最后生成一份带来源链接的对比报告。
坦白说它的研究深度和人类研究员还有差距，信息来源基本依赖它能抓到的页面质量，但在“快速了解一个陌生技术方向”和“技术选型前扫雷”这两个场景下，已经能省下大量搜索时间。它输出的报告有个好习惯：每条结论后面都带来源 URL。这点我很喜欢，因为可以自己点开验证，而不是完全相信模型的判断。
使用的时候我会克制一点，明确限制来源数量和报告长度，比如“最多抓取 10 个来源，报告控制在 500 字以内”。不加限制的话，Codex 会为了“深度”疯狂抓取，token 消耗非常快。这种成本控制意识，在长期使用 superpowers 时非常重要。
3.4 其他值得关注的技能：按需启用就好
superpowers 内置的技能不止上面三大类，还有一些在特定场景下非常好用。我整理了几个自己测试过觉得实用的：
| 技能方向 | 主要用途 | 我的评价 |
|---|---|---|
| 文档格式处理 | 把 PDF、Word 内容转成可分析的纯文本 | 处理合同、报告等资料时很省心 |
| 文件批量整理 | 对目录内多个文件做统一分析或重构 | 批量补注释、统一导出格式时好用 |
| 浏览器自动化 | 模拟浏览器操作特定页面 | 适合处理动态渲染页面，但配置成本稍高 |
| 结构化数据抽取 | 从文本中抽取实体、字段、关系 | 处理日志、问卷、非结构化数据时很强 |
需要注意，技能清单是跟着 superpowers 版本走的，不同版本的技能数量和名称可能有差异。最靠谱的方法是打开.superpowers/skills/目录，看看当前版本内置了哪些技能，每个技能文件开头都有触发条件和适用范围说明，花十分钟过一遍，你就知道这个版本能做什么了。
4. 一个完整的实战：从设计稿到可运行代码
4.1 任务背景与我的方案选择
理论讲再多不如跑一次真实任务。我用一个自己最近做的小项目来演示：一个内部工具的数据看板页面，UI 设计稿已经画好了，接口文档也写好了，但页面还没开发。我计划用 superpowers 让 Codex 帮我从设计稿直接生成前端页面，并完成接口对接。
整个任务拆成三个阶段：第一阶段用图像技能看懂设计稿，第二阶段用网页抓取技能提取接口文档，第三阶段让 Codex 生成代码并和现有工程对接。这个拆分方式很重要，每个阶段是独立的子任务，上下文清晰，Codex 不容易把设计稿信息和接口信息搞混。如果你一口气把所有需求都塞在一个会话里，模型很容易顾此失彼，后面排查问题也麻烦。
4.2 实际执行过程记录
第一阶段，我先把设计稿放到了docs/dashboard-design.png，然后在 Codex 里发了一条指令：
使用图像查看技能，读取 docs/dashboard-design.png。 这是一个数据看板的设计稿，请描述整体布局结构、主要模块、每个模块包含的图表和数据字段，尽量具体。Codex 读完技能文件后开始执行，先确认图像存在，再逐步输出描述：顶部是标题和日期筛选区，左侧是四个 KPI 卡片，中间主体区域是一个大的趋势折线图，右侧是两个表格模块，分别展示订单列表和异常告警。底部还有一个占比环形图。它连 KPI 卡片的色块主色和字体大小层级都描述出来了，信息量足够支撑写代码。
第二阶段，我需要接口文档的字段定义。文档在内部 Wiki 的一个页面上，我直接把 URL 给了 Codex：
使用网页抓取技能，访问 https://internal.wiki/api/dashboard-doc.html。 提取所有接口的路径、请求参数、响应字段，以表格输出。重点标注响应里的 data 结构。抓取结果转成 Markdown 后被 Codex 整理成了接口清单，响应字段的统一结构是{ code, message, data: { kpis, trend, orders, alerts, ratio } }。跟我随手翻原始文档核对了几个字段，没发现错误，数据对应关系准确，说明预处理环节把页面里的表格和嵌套结构都正确保留了。
第三阶段，把设计稿描述和接口字段合并成开发指令：
基于之前的设计稿结构分析和接口文档字段，用 Vue 3 + TypeScript 在 src/views/dashboard 下生成页面。 布局按设计稿描述，数据用接口文档的字段名。先生成组件骨架，再填充业务逻辑。Codex 在会话里同时保留了前两个阶段的信息，直接生成了一整套.vue文件。我检查了代码结构，布局基本还原了设计稿的模块划分，数据变量名和接口返回字段完全对应，还有一个 mock 数据文件方便本地调试。整个过程大概二十分钟，中间只有一处我手动修正过 — 设计稿里某个指标卡片的单位标注不够清楚，Codex 按照自己的猜测写了，我改成了正确单位。
4.3 过程中踩到的两个坑
上面这个流程跑得顺利，不代表没有意外。第一个坑是设计稿截图分辨率太高。第一次我丢了一张完整的 2K 截图进去，Codex 处理到一半提示输入超过限制。后来我把截图按模块裁成几张图，每个功能区单独分析，问题立刻解决，而且分析得比之前更细致。
第二个坑是接口文档页面太长，一次抓取之后 Codex 输出了一半就断了。我把指令改成“先抓取接口列表部分，输出路径和参数，再抓取响应字段部分”，分两次执行，效果稳定很多。
这两件事的核心教训是同一个：给 Codex 喂信息的粒度很重要。内容太多就拆，任务太杂就分，这也是使用 superpowers 所有技能时最值得养成的习惯。
5. 常见问题与排查技巧：装完不代表能用
5.1 问题速查表
这几天在多个环境里折腾 superpowers，我自己和身边朋友遇到过的典型问题都差不多，整理成一张速查表，方便你直接对照排查：
| 症状 | 常见原因 | 处理方式 |
|---|---|---|
| 对话里提到技能，Codex 无动于衷 | AGENTS.md没有被正确写入技能索引 | 重跑npx superpowers@latest install，或手动检查AGENTS.md内容 |
| 图像技能报“无法处理该文件” | 模型不支持视觉，或路径写错 | 检查config.toml的 model 字段，确认路径相对当前目录正确 |
| npm 安装卡住或报错 | Node 版本过低、npm 镜像异常 | 升级 Node ≥18，检查 npm config 里的 registry 配置 |
| 抓网页技能返回空内容 | 页面强依赖 JavaScript 渲染，或反爬 | 换用浏览器自动化技能，或手动保存页面内容后传给 Codex |
| token 消耗异常大 | 技能没有限制抓取数量和输出长度 | 在指令里强制要求“最多抓 N 个来源”“报告不超过 N 字” |
| Codex 不按技能步骤执行，反而自由发挥 | 指令太模糊 | 明说“使用 xxx 技能”，并把输出格式一并指定 |
| 本地多个项目技能版本不一致 | 不同时间安装、版本不同 | 把.superpowers纳入 Git，统一版本管理 |
5.2 安全与权限管理：别忘了这是一把真刀
superpowers 给 Codex 开了很多新通道，但能力越大，越要管好边界。我最想提醒的是：给 Codex 联网和浏览器能力之后，它就有了“替你访问外部世界”的能力。如果项目里有敏感信息，或者你运行它的环境连了生产网络，务必设置好边界。
几个我自己的安全习惯：
- 在配置里留意是否开启了终端命令自动执行。有些场景下 Codex 会自动跑命令来确认代码是否正确，这是好事，但我不建议在完全无人值守的模式下让它跑 all-in-one 命令。
- 不要轻易让 Codex 把抓取到的网页内容写进项目核心文件。它抓回来的是外部数据，可能包含恶意脚本样本、漏洞描述等内容，写进工程文件有潜在风险。我一般让它在输出里展示，确认无害后再决定是否落盘。
- 定期审阅技能文件和历史记录。每隔一段时间看看
.superpowers/skills/里有没有被改过的痕迹，确认没有多出不明来源的技能文件。本质上是把 superpowers 当成有权限的服务来管理，遵循最小权限原则：不需要的技能就不启用，不需要的权限就不开。
5.3 让 superpowers 更好用的几个实战小技巧
最后分享几个我实际使用中总结出来的技巧，不算什么高深的东西，但很管用。
第一，养成“先技能，后提问”的对话习惯。每次用 Codex 之前，先在脑子里想一下：这个任务属于哪类问题？有没有对应技能？如果有，就明确说出来。这能让 Codex 直接进入正确的执行路径，而不是从零猜你的意图。
第二，把你自己常用的操作也写成技能。superpowers 允许在.superpowers/skills/下加自定义技能。我最开始只是用现成的内置技能，后来发现团队里有一套固定的代码审查流程，每次都花不少时间重复描述。于是把流程写成了一个自定义技能文件，触发条件是“使用团队代码审查技能”，里面规定了审查范围、检查清单、输出格式。从那以后，Codex 每次执行这套流程都一丝不苟，比我口头描述稳定太多。
第三，结合项目背景信息使用。在项目AGENTS.md里除了 superpowers 的技能索引，还可以顺手补一段项目简介：技术栈是什么、目录结构怎么组织、常用的构建命令有哪些。这样 Codex 在调用技能时能结合项目上下文，而不是像个临时工一样对项目一无所知。
第四，善用 Git 管理和版本对比。技能文件不只能被 Codex 读取，它本身也是普通的 Markdown，完全可以纳入代码评审流程。我们团队现在的新规则很简单：新增技能文件要过评审，评审内容就是看这个技能文件会不会让 Codex 做出不安全的行为。这样等于把“给 AI 开权限”这件事也变成可审查的工程实践，而不再是一个黑盒。
我个人用下来最大的体会是：superpowers 真正贵的不是那点 token，而是你愿不愿意把自己的工作流沉淀成“机器也能看懂的说明书”。把一次性的指令变成可复用的技能，把个人的操作习惯变成团队的共同资产，这个转变带来的效率提升远比多几个技能文件大得多。如果你也在用 Codex CLI，花一个下午装好它、读一遍内置技能、把你最常干的流程写成自定义技能，之后你会回来感谢这个下午的投入。
