1. 从“superpowers”这个词说起它到底指什么第一次看到“superpowers”这个标题加上“agentic skills framework”“software development methodology”这几个关键词我脑子里第一反应是这不是某个具体软件的名字而是一套给 AI 编程代理agent赋予“超能力”的方法论框架。换句话说它讨论的不是“装哪个工具”而是“怎么让 AI 代理真正具备完成复杂软件任务的能力”。这个判断很关键因为很多人一看到 superpowers 就以为是某个可以npm install的包结果搜半天搜不到。实际上从热搜词能看出来大家真正关心的落点是Claude Code、Codex CLI 这类命令行 AI 编程代理怎么用、怎么装、怎么接本地模型、怎么在 VS Code 里跑起来。superpowers 更像是这些工具背后的一套“能力组织思路”——把一个大任务拆成可被代理逐步执行的技能单元让 AI 不只是补全代码而是能读文件、跑命令、改配置、验证结果。我先把这套框架的核心逻辑讲清楚再落到具体工具的安装、配置和实战上。因为脱离工具谈方法论是空的脱离方法论只谈工具又会让你用得很浅。这两者必须绑在一起看。1.1 为什么“代理技能框架”比“模型本身”更值得关注过去两年大家比的是模型谁更聪明但现在你会发现同一个模型在不同工具里表现差异巨大。原因就在于代理框架它决定了模型能看到什么上下文、能调用哪些工具、能执行几步、失败了怎么回退。打个比方模型是发动机代理框架是整辆车的底盘、变速箱和方向盘。发动机再强底盘不行车也跑不快。superpowers 这类框架的价值就是把“发动机”和“能上路的车”之间的差距补上。它定义了一套技能skills的组织方式每个技能是一个可复用的能力单元比如“读取项目结构”“运行测试”“修改配置文件”“调用终端命令”。代理在执行任务时按需加载对应技能而不是一次性把所有信息塞进上下文。这样做的好处很直接上下文更省、执行更稳、可复用性更高。我实测下来一个组织良好的技能框架能让同一个模型在复杂任务上的成功率提升非常明显因为它减少了模型“瞎猜”的空间。1.2 热搜词暴露的真实需求安装、配置、接模型把那一长串热搜词捋一遍其实能清晰分出几类需求安装类claude code 安装、codex cli 安装、mac 安装、ubuntu 配置、桌面版安装包配置类vscode 配置 claude code、vscode 接入、插件配置解释模型接入类调用 lmstudio 的本地模型、接入 deepseek、qwen、glm 等模型使用类claude code 使用教程、如何直接执行终端命令、命令有哪些/compact /model /resume报错类组织禁用了订阅访问、国家不可用提示、与 64 位 Windows 不兼容这些需求背后是同一件事大家想把 AI 编程代理真正跑在自己的工作流里而不是停留在网页对话框。下面我就按这个真实路径来展开从环境准备到跑通第一个任务再到接本地模型和排错。2. 环境准备Claude Code 与 Codex CLI 的安装路径选择安装这一步看着简单但踩坑最多。我见过太多人卡在“装完了但跑不起来”或者“跑起来了但连不上模型”。核心原因是没搞清楚这类 CLI 工具的运行依赖。2.1 先分清 Claude Code 和 Codex CLI 的定位差异这两个经常被放在一起提但它们不是一回事维度Claude CodeCodex CLI本质终端里的 AI 编程代理终端里的 AI 编程代理交互方式自然语言 斜杠命令自然语言 命令典型命令/compact、/model、/resume任务执行、文件操作模型来源官方模型或第三方接入官方模型或第三方接入适用场景长任务、多轮迭代快速任务、脚本化两者思路接近都是“在终端里让 AI 帮你干活”。选哪个更多看你的模型来源和使用习惯。我个人的做法是两个都装按任务类型切换。2.2 安装前的三个前置检查在敲任何安装命令之前先确认这三件事能省掉后面 80% 的报错Node.js 版本这类 CLI 工具大多基于 Node 生态版本太低会直接报错。建议 Node 18 以上最好 20 LTS。终端环境macOS 用自带 Terminal 或 iTerm2 都行Ubuntu 建议用 bash 或 zshWindows 建议用 WSL原生环境容易遇到兼容问题。网络与账号官方模型需要账号和订阅第三方模型需要 API Key。这一步决定了你后面能不能真正跑起来。提示如果你看到“你的组织已禁用订阅访问”这类提示通常是账号权限问题不是安装问题。换个人账号或改用第三方模型接入往往能绕过。2.3 安装命令与验证以 npm 全局安装为例通用路径是这样的# 检查 node 版本 node -v # 全局安装以 claude code 为例 npm install -g anthropic-ai/claude-code # 验证是否安装成功 claude --versionCodex CLI 类似npm install -g openai/codex codex --version装完之后别急着用先跑一次--version和--help确认命令能被系统识别。如果提示 command not found多半是 npm 全局路径没进 PATH这时候检查npm config get prefix把对应 bin 目录加到环境变量里。2.4 macOS 与 Ubuntu 的差异处理macOS 上一般比较顺Homebrew 装好 Node 之后基本一路通。Ubuntu 上要注意两点一是权限全局安装可能需要sudo但我不建议直接用 sudo 装 npm 包容易搞乱权限更好的做法是配置 npm 的用户级 prefix二是依赖库某些版本需要额外的构建工具遇到报错先apt install build-essential再试。Windows 用户我强烈建议走 WSL。原生 Windows 下经常遇到“与 64 位版本不兼容”这类问题本质是工具链对 Windows 的支持不完整。WSL 里跑 Ubuntu体验和原生 Linux 几乎一致省心很多。3. VS Code 集成把终端代理搬进编辑器很多人装完 CLI 就只在终端里用其实 VS Code 集成之后效率会高很多。你可以在编辑器里直接看到 AI 改动的文件、diff、执行结果不用来回切窗口。3.1 插件安装与基础配置在 VS Code 扩展市场搜索对应的 Claude Code 或 Codex 插件安装后一般需要配置两样东西可执行文件路径和模型/API 配置。配置项通常长这样以 settings.json 为例{ claudeCode.executablePath: /usr/local/bin/claude, claudeCode.model: your-model-name, claudeCode.apiKey: your-api-key }这里最容易出错的是executablePath。如果你在终端里能跑claude但插件说找不到多半是路径写错了。用which claude查一下真实路径填进去。3.2 插件配置里那几个容易看懵的字段插件配置界面经常有一堆字段我挑几个关键的解释executablePathCLI 可执行文件的绝对路径必须准确。model指定用哪个模型接第三方模型时这里要和你 API 端配置的一致。apiKey / baseURL第三方接入时baseURL 指向你的 API 服务地址apiKey 是鉴权凭证。autoApprove是否自动批准文件修改建议初期关掉看清楚 AI 改了什么再放行。注意autoApprove 打开后 AI 会直接改文件虽然快但一旦改错回滚麻烦。我自己的习惯是前几次任务手动确认熟悉之后再考虑放开。3.3 在编辑器里跑通第一个任务配置好之后打开一个测试项目在插件面板里输入一个简单任务比如“读取当前项目结构并总结用了哪些技术栈”。观察它是否能正确读取文件、返回结果。如果这一步成功说明链路通了。接下来可以试更复杂的任务比如“找到所有 console.log 并列出所在文件”。这类任务能验证代理是否真的能操作文件系统而不只是聊天。4. 接入本地与第三方模型lmstudio、deepseek、qwen、glm这是热搜里出现频率最高的一块。很多人不想只用官方模型原因无非是成本、隐私或者可用性。接第三方模型是完全可行的但配置细节决定成败。4.1 用 lmstudio 跑本地模型的完整链路lmstudio 的好处是本地起一个兼容 OpenAI 接口的服务然后让 CLI 工具指向它。步骤大致是在 lmstudio 里加载一个模型启动本地服务记下端口默认常见是 1234。确认服务地址一般是http://localhost:1234/v1。在 CLI 或插件配置里把 baseURL 指向这个地址apiKey 随便填一个非空值本地服务通常不校验。指定模型名称要和 lmstudio 里加载的模型标识一致。# 以环境变量方式配置示例 export OPENAI_BASE_URLhttp://localhost:1234/v1 export OPENAI_API_KEYlocal配好之后跑一个简单任务验证。如果报连接错误先确认 lmstudio 服务是否真的在跑再用 curl 测一下接口通不通。4.2 接入 deepseek、qwen、glm 的通用思路这几个都是提供 OpenAI 兼容接口的第三方服务接入方式和 lmstudio 几乎一样区别只在 baseURL 和 apiKey模型来源baseURL 特征关键配置lmstudiolocalhost 本地地址端口要对deepseek官方 API 地址apiKey 必填qwen官方 API 地址apiKey 必填glm官方 API 地址apiKey 必填核心就一句话只要对方兼容 OpenAI 接口格式就能接。配置时把 baseURL、apiKey、model 三个字段填对基本就能跑。4.3 cc switch 这类切换工具的价值热搜里提到“使用 cc switch 接入 deepseek、qwen、glm 等模型”这类工具解决的是多模型切换的痛点。你不可能每次换模型都手动改配置文件切换工具帮你把多套配置存好一条命令切换。我自己的做法是维护一个配置文件里面存好几套 profile需要哪个切哪个。这样在测试不同模型效果时特别方便不用反复改环境变量。4.4 接第三方模型时的三个坑模型名不匹配配置里写的 model 名称必须和 API 端支持的完全一致差一个字符就报错。上下文长度本地小模型的上下文窗口往往比官方模型小长任务容易截断要提前评估。工具调用能力不是所有模型都支持 function calling而代理框架高度依赖工具调用。选模型时优先选支持工具调用的。5. 常用命令与实战技巧/compact、/model、/resume 怎么用命令用得好不好直接决定你用得顺不顺。这几个斜杠命令是高频操作值得单独讲。5.1 /compact上下文压缩的救命稻草长任务跑到后面上下文会越来越长模型开始“忘事”或者变慢。/compact的作用就是压缩历史对话保留关键信息腾出上下文空间。我的使用习惯是当一个任务跑了很久、感觉模型开始答非所问时先/compact一次往往能救回来。但要注意压缩是有损的太频繁会丢失细节重要节点前先手动记录关键结论。5.2 /model随时切换模型/model让你在会话中切换模型不用退出重开。这在对比不同模型效果时特别有用。比如同一个任务先用 A 模型跑效果不好直接/model切到 B 模型继续。5.3 /resume恢复中断的会话任务跑到一半终端关了或者你想接着昨天的进度继续/resume能恢复之前的会话。这个功能对长周期项目非常关键避免了每次从头描述需求。5.4 让代理直接执行终端命令这是很多人最关心的能力AI 能不能直接跑命令。答案是能但要有边界意识。代理执行命令的典型流程是它提出一个命令你确认它执行读取输出继续下一步。这个“确认”环节很重要尤其是涉及删除、覆盖这类操作时。提示永远不要让代理在无人看管的情况下执行破坏性命令。我一般会把危险操作单独拎出来手动执行只让代理做读取和验证类命令。6. 报错排查从“国家不可用”到“64 位不兼容”报错是绕不开的我把常见几类整理出来附上排查思路。6.1 账号与地区相关提示“claude code might not be available in your country”这类提示本质是服务可用性限制。遇到这种情况优先考虑改用第三方模型接入或者检查账号状态。不要在这类问题上死磕换条路往往更快。6.2 组织禁用订阅访问“your organization has disabled claude subscription access”是账号权限问题。如果你用的是组织账号管理员可能关闭了相关权限。解决办法是用个人账号或者走第三方 API。6.3 Windows 兼容性问题“与 64 位版本的 Windows 不兼容”是典型的原生 Windows 环境问题。最稳的解法是上 WSL在 Linux 子系统里跑几乎不会遇到这类报错。6.4 排查通用流程遇到任何报错我建议按这个顺序走看报错原文定位是安装问题、配置问题还是网络问题。用--version、--help确认工具本身正常。用 curl 测 API 接口是否通。检查配置文件字段是否填对。换环境比如 WSL复现判断是不是系统问题。这套流程能覆盖绝大多数情况。真正难缠的往往是配置字段的细微错误所以每次改配置后都要重新验证一遍。7. 把 superpowers 思路落到日常开发里回到最开始那个词。superpowers 作为一套代理技能框架的思路真正的价值不在于某个工具而在于它教你怎么组织 AI 的能力。我自己的实践体会是不要指望一个模型或一个工具解决所有问题而是把任务拆成清晰的技能单元让代理一步步执行、验证、回退。安装和配置只是入场券真正拉开差距的是你怎么设计任务、怎么管理上下文、怎么设置确认边界。最后分享一个小技巧每次开始一个新项目前先让代理读一遍项目结构并输出一份“能力清单”——它能做什么、不能做什么、需要哪些权限。这份清单能帮你在后续任务里少走很多弯路。踩过几次坑之后你会发现把边界划清楚比追求模型多聪明更重要。