1. Superpowers到底是什么，为什么三大工具都要适配

1.1 从Skills机制聊起

如果你从去年开始频繁使用AI编程助手，大概率会发现一个趋势：不对劲，越来越像“毛坯房”了。基础回答、简单补全当然没问题，可一旦你要它完成多步骤的工程任务——批量重构、跨文件追踪依赖、自动跑测试、按规范提交代码——它就经常犯迷糊，或者做到一半停下来问你“需要我继续吗”。

问题出在哪？出在“技能”这个层面。不管是Claude Code、Codex还是OpenCode，AI助手本身内置的能力是通用的，它会写代码、能读文件、可以执行终端命令。但它不会自动知道你项目里的测试命令是什么、代码风格规范有哪些、Git提交格式该怎么写。这些知识不在模型参数里，而在项目上下文和工具链里。

这时候就轮到Skills机制登场。简单理解，Skill就是给AI助手预置的一套“操作手册+工具扩展包”。它通常是一个目录，里面包含若干Markdown文档和可执行脚本。Markdown文档用来告诉大模型“遇到什么场景该调用哪套流程”，脚本则负责真正落地执行。比如“代码审查”这个Skill，它可能包含一份review-checklist.md，还有几个脚本，自动枚举变更文件、分析diff、生成审查报告。

1.2 Superpowers能解决什么问题

Superpowers是一个开源的Skills集合项目，主打“一次性配齐，多个工具通用”。它把日常开发里高频出现的工程场景，比如代码审查、单元测试补充、技术方案设计、重构建议、Commit信息规范、Bug复现报告等，都做成了标准化的Skill包。

这个项目解决了两个非常现实的痛点。

第一个痛点：每个AI工具的Skill格式不互通。Claude Code的Skill可能是一套目录规范，Codex则更依赖AGENTS.md这种说明文件，OpenCode对Skill的约定又不一样。如果没有一个中间层，你在Claude Code里养好的技能习惯，切到Codex就全废了。Superpowers做的事，就是定义一套相对中立的Skill表达方式，再通过各自的适配逻辑挂载到不同工具上。

第二个痛点：默认提示词太单薄。直接跟AI说“帮我做代码审查”，它可能会给出泛泛而谈的意见。但如果你提前加载了一个“代码审查Skill”，它就会按照既定流程走：先读取改动文件列表，再逐个分析风险点，检查错误处理、边界条件、资源释放，最后按严重级别输出问题清单。这个差别，体验过的人都知道有多大。

1.3 为什么选择这三个工具一起适配

Claude Code、Codex、OpenCode是目前终端型AI编程助手里面最值得关注的三条线，而且恰好代表了三种不同的形态。

Claude Code是最早把“Agentic Coding”体验做完整的工具之一，它的对话交互、文件编辑能力和终端执行力都相当成熟，很多人拿它当主力开发助手。

Codex是OpenAI官方的CLI工具，最大的特点是和ChatGPT生态、以及开放接口体系深度绑定。如果你是ChatGPT的重度用户，或者团队后端已经接入了OpenAI兼容接口，那Codex天然就有优势。

OpenCode则是一个更“极客向”的开源终端AI助手，它不绑定某个特定模型服务商，而是通过配置自由接入各种模型后端。很多人喜欢它，除了免费开源之外，还因为它的配置足够透明，几乎每个行为都能自己掌控。

有一个有趣的生态现象是：发布Superpowers的社区和OpenCode走的很近，但仍然刻意保持工具无关。你在OpenCode上安装Superpowers很顺滑，同时也能在Claude Code、Codex里用。这种“一套技能，三端复用”的能力，对需要在多工具之间切换的开发者来说特别有价值。我自己的日常就是：Claude Code负责重活，Codex负责快速问答和写测试，OpenCode在VSCode里无缝穿插。三套工具各司其职，底下的Superpowers技能层则是统一的。

2. 跨平台部署的整体思路与环境准备

2.1 三种工具的安装路径盘点

在部署Superpowers之前，得先把三个工具本身装好，并且确认它们能在你的操作系统上正常运行。这里是跨平台的第一步。

Claude Code官方推荐通过npm全局安装，命令很简单：

npm install -g @anthropic-ai/claude-code

装完后执行claude -v验证版本。Windows上注意一点：不要混用Node.js自带的npm和nvm安装的npm环境，否则全局目录会乱，claude命令经常找不到。macOS和Linux上也要注意，如果你用homebrew装了node，又用nvm切换过版本，那npm install -g装到的目录可能不是当前shell里的PATH路径。

Codex的安装方式则更偏向“原生二进制分发”。它官方推荐下载预编译好的可执行文件，或者用Homebrew：

brew install codex

Linux上需要手动下载二进制并放到PATH目录里。这里有一个Windows用户经常踩的坑：Codex的Windows安装包，有时候会卡在“installing”状态，装到一半停住不动。有人反复重装也没解决，最后发现是安装程序在等待一个被系统防火墙拦截的本地服务启动。遇到这种情况别急着折腾安装包，可以先检查系统防护记录，把相关目录加白，然后重新跑安装脚本。

OpenCode是纯开源项目，安装方式最灵活。官网提供一条curl命令直接安装，也可以从GitHub Releases页面下载对应平台的压缩包，还可以通过npm装：

npm install -g opencode-ai

或者用官方脚本：

curl -fsSL https://opencode.ai/install | bash

三者的安装路径差异，我整理成了表，方便你在排查问题时对照：

2.2 配置文件与数据目录的差异

跨平台部署Superpowers，最核心的工作就是处理配置文件的差异。这三个工具对“技能/指令”的读取路径完全不一样。

Claude Code从很早开始就支持plugins和skills机制，默认扫描两个地方：全局目录~/.claude/plugins，以及项目级目录.claude/plugins。你在项目里看到的.claude文件夹就是干这个用的。

Codex更特别，它不叫Skill，而是通过AGENTS.md来传递“做事约定”。版本更新后也开始支持类似skills的机制，但和Claude Code的目录结构并不通用。如果你直接把Claude Code的Skill目录拷给Codex，它很大概率读不到。

OpenCode的设计则和上述两者都不一样。它本身有一个Session机制，也定义了opencode.json作为入口配置。对Superpowers这类外部技能，OpenCode更偏向通过“Command/Prompt”或opencode.json里引用的自定义指令来加载。

你可别小看这些路径差异。实际部署中，很多人Superpowers“装上没反应”，90%都是因为把技能文件放到了错误的目录，工具根本没有扫描到。所以跨平台部署的第一课，就是先分清全局和项目级这两个维度。全局意味着这台机器上所有项目都能用，适合放通用技能；项目级则只对本项目生效，适合放业务相关的专用规则。

2.3 Node.js版本与运行时依赖

Superpowers这类技能集合，底层脚本大部分用Shell和Node.js编写。所以跨平台部署时，Node.js版本是一个容易被忽视但又非常关键的环境变量。

Claude Code官方要求Node.js 18以上，有些新版本甚至建议20以上。Codex的本地运行也会有Node运行时依赖。OpenCode是基于Bun构建的，安装脚本自己会带运行时，但如果你开的是npm安装方式，还是会依赖系统环境。

我的建议是：部署前先统一Node.js版本到20 LTS以上。

node -v # v20.15.0 或更高版本

如果你的机器上同时有多个Node版本，建议在部署Superpowers之前，先确认当前shell激活的Node版本是你打算长期使用的那一个。很多诡异的问题，比如技能脚本执行时报Cannot find module 'fs/promises'，或者某个依赖包安装失败，最后回溯都是Node版本太老或太新直接导致的。

另外，Superpowers项目自身可能涉及安装一些依赖包。比如把仓库clone下来之后，可能需要执行：

npm install

这时候要注意平台的包管理差异。Windows下如果遇到node-gyp编译报错，需要先安装Visual Studio Build Tools；macOS下则可能要装Xcode Command Line Tools。Linux下通常是build-essential。这一步不在官方说明里，但影响极大。

3. Claude Code部署Superpowers实操

3.1 安装Claude Code并完成鉴权

先把Claude Code装好，并做一次完整的登录验证。执行安装命令：

npm install -g @anthropic-ai/claude-code

安装完成后，在项目目录执行：

claude

首次运行会要求登录授权。按终端提示跳转浏览器完成认证即可。这里有个小细节要提醒：Claude Code的登录态是缓存在本地的，如果你配置了多套环境，之后每次启动有可能会提示重新连接或者鉴权过期。遇到这种情况，直接执行claude doctor可以检查整体配置状态，比自己乱翻日志高效得多。

验证成功后，可以简单问一句“当前工作目录是什么”，确认Agent能正常感知文件系统，再进行后续Superpowers挂载。

3.2 在Claude Code中挂载Superpowers的推荐步骤

Claude Code目前支持通过plugins方式挂载Superpowers。最常规的操作是把Superpowers项目clone到本地，然后通过路径引用。我在多个系统上试过，这个流程最稳定：

先clone项目到统一位置，我习惯放在用户目录下的.superpowers里：

git clone https://github.com/obra/superpowers.git ~/.superpowers

然后在Claude Code的配置中引用这个路径。新版Claude Code支持通过claude plugin add命令直接添加本地插件：

claude plugin add ~/.superpowers

或者手动编辑配置文件。全局插件配置路径在：

# macOS / Linux ~/.claude/plugins/config.json # Windows %USERPROFILE%\.claude\plugins\config.json

手动方式就是在配置里添加对应的插件路径引用。两种方式选一种就行，个人更推荐命令行方式，因为Claude Code会自动处理插件目录的符号链接和版本信息，手动改配置很容易因为JSON格式或者路径分隔符问题失败。

挂载完成后，重启Claude Code，输入/plugin应该能看到Superpowers相关的插件处于已启用状态。有些版本还支持/skills命令直接列出当前可用的技能列表。

3.3 技能加载逻辑与生效验证

挂载成功并不代表万事大吉。你需要实际验证技能是否真的被加载到了模型上下文里。

验证方法很直接：新建一个临时目录，故意制造一个“需要有代码审查技能才能处理”的场景。比如创建两个文件，一个main.js，一个有明显逻辑隐患的utils.js，然后让Claude Code执行：

请用Superpowers的代码审查技能，检查当前目录下的代码，输出风险清单。

如果返回的是结构化审查报告，包含问题严重级别、代码位置、修改建议，说明技能生效了。如果返回的是空的、泛泛的“看起来不错”，那大概率技能没有真正加载。

常见原因有两种：一种是插件路径配置错了，Claude Code扫描时没找到对应目录；另一种是技能内部的Markdown格式和当前Claude Code版本不完全兼容，导致解析失败但仍静默跳过。第二种问题比较隐蔽，排查时可以先用/plugin看插件是否启用成功。如果插件显示已启用但技能不生效，可以手动把技能文件里的Markdown头部信息与官方示例做对比，看是不是格式字段有出入。

4. Codex部署Superpowers实操

4.1 安装Codex CLI

安装Codex之前，先明确一点：它的定位是运行在终端里的AI编程代理，很多交互逻辑面向的是“以代码仓库为单位”的日常工作流。所以安装和配置必须落在“你平时跑命令的机器环境”里。

官方支持的安装方式主要有两种。macOS上推荐：

brew install codex

其他平台去官方Release页面下载对应平台的压缩包，把codex可执行文件放到/usr/local/bin或者$HOME/.local/bin，再确保PATH里有这个目录就行。Windows上如果下载的是.exe安装包，安装完成后检查版本：

codex --version

如果不能正常输出，多半是PATH配置问题，把安装目录手动加进环境变量即可。

登录鉴权也是必要一步。执行codex login，会跳转浏览器完成账号授权。如果你有团队后端的开放接口环境，可以通过环境变量指定自定义的API地址和密钥，这一点在后文配置里展开。

4.2 让Codex认识Superpowers的两种方式

Codex对技能的处理逻辑，和Claude Code差异很大，这里需要单独讲透。

第一种方式：通过AGENTS.md注入。Codex在启动时会自动读取项目根目录以及用户级目录下的AGENTS.md文件。你可以在这些文件里显式引用Superpowers技能文档的路径和用途。比如在项目根目录的AGENTS.md中写入：

## 技能引用 - 代码审查技能：读取 ~/.superpowers/skills/code-review.md，执行审查流程 - 测试补充技能：读取 ~/.superpowers/skills/test-writer.md，按规范生成测试

这样做的好处是简单直接，Codex每次启动都会加载这些规则。坏处是当技能数量较多时，AGENTS.md会非常臃肿，而且每次请求都会消耗大量上下文token。

第二种方式：使用Codex的skills目录。新版Codex在一定程度上支持自定义Skills目录。你可以把Superpowers的技能文件复制到~/.codex/skills目录下，并在Codex的全局配置里声明启用哪些技能。这种方式更贴近“插件化”体验，技能按需加载，对上下文更友好。

配置示例：

{ "skills": { "enabled": [ "code-review", "test-writer", "bug-reporter" ] } }

具体字段名会根据Codex版本有所不同，建议先用codex --help或者查看对应版本的配置文档确认。实际部署时，我的经验是两种方式结合：全局开放目录放通用技能，项目级AGENTS.md只做按需引用，这样既不臃肿，又能在不同项目里灵活切换。

4.3 模型配置与AGENTS.md组织方式

Codex能不能稳定跑起来，一半看配置，一半看模型接口。

如果你是接的官方ChatGPT账号，那默认配置就能用。如果你是走后端开放接口的方式接入，需要在环境变量或者配置文件中指定接口地址和密钥。常见配置示例如下：

export CODEX_API_BASE="https://your-api-endpoint.example.com" export CODEX_API_KEY="your-api-key"

注意，不同兼容接口对路径的处理细节不完全一致，有些要求/v1结尾，有些不要求。配置不对时最常见的就是鉴权失败或者404。这两个报错很好区分：鉴权失败一般是401/403，接口路径不对一般是404。遇到404先检查是不是多写了几层路径，别急着怪模型。

组织AGENTS.md时还有个小技巧：Superpowers技能文档通常篇幅不短，如果直接把全部内容塞进AGENTS.md，每次对话都带着这些内容，成本很高。更好的做法是只写“索引”，把具体文档作为外部文件引用，并告诉Codex“当用户要求执行代码审查时，先读取xxx文档”。这样技能逻辑保持完整，上下文消耗却小得多。

5. OpenCode部署Superpowers实操

5.1 安装OpenCode并完成基础配置

OpenCode是三者中最轻量、最透明的。它的整个配置体系都围绕opencode.json展开，这个文件放在项目根目录，属于典型的“配置即代码”风格。

安装方式前面提过，官方脚本或npm都可以。安装完成后，先做基础配置。在项目根目录创建opencode.json，内容大致如下：

{ "provider": { "default": "your-model-provider" } }

我要特别提醒一点：OpenCode默认不帮你内置任何模型密钥，你在配置文件里指定什么Provider，它就请求什么后端。因此，如果你希望用之前用过的某个兼容接口，必须在配置里写清楚接口地址和模型名称。

OpenCode在启动时会读取多个来源的配置，顺序大概是：命令行参数 > 项目级opencode.json > 全局配置文件。平时改项目配置就够了，不要轻易去改全局配置，否则容易被不同项目的配置互相污染。

5.2 以Codex兼容模式接入

OpenCode一个非常实用的地方在于，它支持“兼容模式”。也就是说，你可以把OpenCode当作一个客户端，去对接Codex的后端服务。这对那些已经在另一头配置好账号或接口，但不喜欢Codex原始交互界面的用户来说，是很顺滑的。

配置方式比较简单。在opencode.json里指定后端的Base URL和模型名即可，类似这样的结构：

{ "provider": { "default": "codex-compatible", "codex-compatible": { "baseUrl": "https://your-backend.example.com", "model": "your-model-name" } } }

配置完成后，在项目目录执行opencode，就能在保留OpenCode交互体验的同时，请求后端的模型能力。这个模式适合团队内部已经搭好统一模型网关的场景，也适合想在不同工具间保持模型一致性的人。

5.3 在VSCode里调用Superpowers

在VSCode里使用OpenCode，官方提供了一个扩展，安装后可以直接在编辑器右侧打开OpenCode面板。这个面板本质上是内置了一个终端环境，所以你在终端里能给OpenCode下发的指令，在编辑器面板里同样可以执行。

在VSCode里使用Superpowers，关键在于把技能指令作为对话上下文传入。我常用的做法是：在项目根目录建立一个.opencode/commands.md文件，里面写好Superpowers相关技能的调用方式。这样在VSCode的OpenCode面板里，直接引用对应命令就能触发完整技能流程。

举一个实际场景：我需要让Superpowers帮我总结最近的代码改动并生成规范的Commit信息。只需要在面板里输入：

使用Superpowers的commit-message技能，分析最近改动，输出一个符合规范的提交信息。

OpenCode就会读取技能规则，执行git diff分析，然后给你一条可以直接用的Commit信息。整个过程不用离开编辑器，体验和Claude Code的agent式操作已经非常接近了。

6. 高频报错与故障排查实录

6.1 本地网络代理配置异常的处理思路

不少人在配置Codex或OpenCode时，会遇到类似：

cc switch local proxy failed while handling codex endpoint /responses

这个报错看起来像是请求接口时出了网络问题。根据我的排查经验，绝大多数情况是本机网络代理设置错误导致的，而不是模型接口本身的问题。常见的诱因有：系统或终端里配置了代理环境变量，但代理服务没有启动；代理端口号填错；或者代理配置里写了某个地址，但当前网络环境下已经无法访问。

排查步骤可以按顺序来：

第一步，检查本机全局代理状态。macOS上查看“系统设置-网络-代理”，Windows上查看“设置-网络-代理”，Linux上检查桌面环境的网络代理配置。确认代理是否开启，以及地址端口是否有效。

第二步，检查终端环境变量。执行：

env | grep -i proxy

看到HTTP_PROXY、HTTPS_PROXY、ALL_PROXY之类的变量，说明当前shell继承了代理配置。如果当前并不需要走代理，直接清掉这些变量再重新运行：

unset HTTP_PROXY HTTPS_PROXY ALL_PROXY

第三步，检查本地端口占用。如果代理设置的端口已经被其他进程占用，也会导致请求转发失败。Windows上可以用netstat -ano | findstr 端口号，macOS/Linux上可以用lsof -i :端口号来确认。

这里有一个重点：这个报错并不是“接口被封”或“本地无法访问外网”的专属标识。很多时候你在纯内网环境里，只要代理设置是干净的、直连配置是正确的，同样能正常请求。所以遇到它时，不要急着怀疑网络本身，先按上面三步检查本机环境。我自己遇到最多的场景，其实是之前某次调试代理配置时，环境变量残留导出到zshrc里，后来代理停掉了，变量却没删干净。

6.2 Codex连接不上或登录状态异常

Codex启动后经常出现的两个问题，一个是无法连接，一个是登录过期。

如果是“无法连接”且你使用的是自定义后端接口，优先排查接口地址和密钥。

curl -X POST https://your-api-endpoint.example.com/v1/responses \ -H "Authorization: Bearer your-api-key" \ -d '{}'

手动curl一下，返回什么就是什么，比看Codex的提示信息靠谱得多。如果你用的是官方账号，则要留意登录态的缓存问题。可以执行：

codex login status

查看当前登录状态。如果状态异常，重新执行一次codex login即可。有时候Codex在Windows上提示“正在重新连接”但始终连不上，多半是因为本地某个后台进程卡死了，退出所有Codex相关进程再重新启动能解决。

6.3 技能加载后不生效的常见原因

Superpowers部署好后，技能“不生效”是最容易让人抓狂的问题。我总结下来，原因不外乎四类：

第一类，路径错了。技能文件没放到工具扫描的目录，或者符号链接指向的目标不存在。检查方式就是进入对应工具的配置界面，确认插件/skill为启用状态。

第二类，格式不兼容。某些工具对Skill文件的Front-matter格式有严格要求。比如Claude Code要求标题、描述、触发场景等字段遵循特定格式，Codex则要求Markdown文件头部不能有空行。Superpowers项目本身覆盖多工具，但你在不同工具里挂载时，最好对照各工具的官方示例检查格式。

第三类，上下文长度限制。技能文档太大，导致工具在拼装上下文时自动丢弃了部分内容。这种情况在长对话后期特别明显。解决办法是把大技能拆分为“入口文件 + 子文档”，让模型按需读取。

第四类，模型没有主动触发。技能是被动加载的，得让大模型知道“应该使用它”。如果模型判断当前用户请求不需要技能，它就不会调用。这时候需要你在提示词里更明确地指定使用某个技能，或者在技能描述里写清楚什么场景下触发。

7. 实战经验总结与避坑提醒

7.1 跨平台同步配置的三种方式

三套工具部署完成之后，紧接着的问题就是：换电脑怎么办？或者同一台电脑，在不同项目里用的工具不一样，技能怎么同步？

第一种方式：Git仓库管理配置文件。把~/.claude、~/.codex、~/.config/opencode这三个目录里你觉得需要保留的配置抽出来，放进一个私有Git仓库。新机器上clone下来，再软链接回对应的系统路径。好处是版本可追溯，改坏了能回滚；坏处是Windows和macOS/Linux路径结构差异大，软链接在Windows下需要管理员权限，操作起来没有在Unix环境里顺手。

第二种方式：借助云同步盘。让配置目录直接指向云同步文件夹。这个做法的成本最低，也最无感，但要注意不同机器上的工具版本可能不一致，配置被同步到旧版本机器上反而可能报错。

第三种方式：只同步Superpowers技能本身。毕竟配置这种东西，每台机器的模型偏好、后端地址都不一样，强求同步意义不大。真正通用的只有技能文件。所以我的习惯是把Superpowers项目本身做成独立仓库，所有机器都clone到同一路径，然后在各工具的配置文件里引用这个路径。这样技能是一份，配置是各自独立的，灵活度最高。

7.2 我的最终配置推荐

经过一段时间的折腾，我目前最稳的配置方案是这样的：

• Claude Code：作为主力重型agent，挂载完整Superpowers插件，负责大型重构、代码审查、测试补全。
• Codex：作为快速辅助工具，通过AGENTS.md索引引用Superpowers技能，不一次性加载全部技能文档，节省上下文。
• OpenCode：主要嵌在VSCode里，以兼容模式接入后端，日常写代码时随手调用Superpowers的技能命令。

三套工具共享同一个Superpowers技能仓库，任何技能更新只需要同步一次，其他工具重启后就能读到最新内容。

再分享一个小细节：成功部署之后，建议花点时间按自己的项目类型写一个“项目级AGENTS.md”或技能配置，把业务相关的领域知识也沉淀进去。Superpowers提供的是通用流程，业务上下文才是你区别于其他人的部分。AI工具链的意义不是替你思考，而是把你的思考逻辑固化下来，让它变成可复制、可复用、跨工具可迁移的资产。这也是我当初坚持要在三个工具里统一部署Superpowers的原因。