1. 为什么 Claude Code 需要 Superpowers 这套骨架Claude Code 本身已经能读写文件、跑命令、改代码但默认状态下它有个通病拿到需求就直接开写不先想清楚设计不写测试也不做审查。你让它加个功能它三分钟给你一坨能跑但没人敢维护的代码。Superpowers 这个开源项目GitHub 上已经拿到 198k Star解决的正是这个问题——它给 AI 编程代理套上一整套强制工作流先头脑风暴、再写计划、然后 TDD 红绿重构、最后两阶段代码审查全程自动触发你不需要记任何命令。我把它理解成给 Claude Code 装了一个工程纪律插件。它由 14 个可组合技能Skills构成核心是让代理在正确的时间点自动进入正确的工作阶段。比如你刚说我想做个登录模块它不会立刻写代码而是先激活 Brainstorming 技能用苏格拉底式提问帮你把需求理清楚输出设计文档后才进入下一步。这套东西适合谁适合已经在用 Claude Code、Cursor、Codex CLI 这类 AI 编码工具但被代理乱发挥折磨过的开发者。如果你只是偶尔让 AI 补个函数可能用不上但如果你想让代理自主跑几个小时还不跑偏Superpowers 的配置骨架值得认真搭一遍。下面我按可复制的顺序把 settings.json、config.toml 骨架和 TaoToken 统一通道接入讲清楚最后给你验证代理调用是否真的生效的命令。2. 前置准备TaoToken 统一 Key 与 API 通道在配 Superpowers 之前先把模型通道理顺。Claude Code 默认走 Anthropic 官方通道但很多人在多工具Claude Code Cursor Codex CLI之间切换时Key 管理很乱。TaoToken 的作用是提供一个统一的 API 入口你申请一个 Key就能在多个编码工具里复用同一套通道省去每个工具单独配 Key 的麻烦。具体操作打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后在控制台创建 API Key。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。拿到 Key 后先别急着填进 Claude Code我们分两步先确认通道能通再写进配置文件。API 基础地址是 https://taotoken.net/api 注意这个地址不带任何查询参数配置时直接用它作为 base_url。如果你用的是 Anthropic 兼容协议Claude Code 需要的是 ANTHROPIC_BASE_URL 和 ANTHROPIC_API_KEY 两个环境变量或者写进 settings.json 的 env 字段。这里有个坑Claude Code 读的是 Anthropic 格式的接口不是 OpenAI 格式所以 base_url 后面不要自己拼 /v1/chat/completions 这类路径让它按协议自己走。提示Key 只在创建时完整显示一次复制后存到密码管理器里。控制台里能看到 Key 的前缀和创建时间但看不到完整值丢了就重新建一个。3. 可复制配置settings.json 与 config.toml 骨架Claude Code 的配置分两层全局配置在~/.claude/settings.json项目级配置在项目根目录的.claude/settings.json。Superpowers 的插件安装和 Hook 加载主要靠全局配置模型通道可以放全局也可以放项目级。下面这份骨架你可以直接抄把 Key 换成自己的。先看全局~/.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-20250514 }, permissions: { allow: [ Bash(git:*), Bash(npm:*), Bash(pnpm:*), Read, Write, Edit ] }, hooks: { SessionStart: [ { matcher: *, hooks: [ { type: command, command: bash ~/.claude/plugins/superpowers/hooks/session-start.sh } ] } ] } }这里几个关键点。env里的ANTHROPIC_BASE_URL指向 TaoToken 的 API 地址ANTHROPIC_API_KEY填你申请的 Key。hooks.SessionStart是 Superpowers 自动加载技能的入口——每次新会话启动时这个脚本会跑一遍把引导指令注入上下文这样代理才知道有哪些技能可用、什么时候该触发。如果你还没装 Superpowers 插件这个 hook 路径会报错所以顺序是先装插件再配 hook。再看项目级的.claude/settings.json主要放项目特有的权限和模型覆盖{ env: { ANTHROPIC_MODEL: claude-sonnet-4-20250514 }, permissions: { allow: [ Bash(pytest:*), Bash(cargo:*), Bash(go test:*) ], deny: [ Bash(rm -rf:*), Bash(git push --force:*) ] } }deny列表建议加上强制推送和递归删除Superpowers 的子代理会自主跑很久万一计划里有危险操作这层兜底能救命。如果你同时用 Codex CLI它的配置在~/.codex/config.toml骨架如下model claude-sonnet-4-20250514 model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY [profiles.default] model claude-sonnet-4-20250514 approval_policy on-requestCodex CLI 用的是env_key引用环境变量所以你要在 shell 里 exportTAOTOKEN_API_KEY或者写进~/.zshrc。注意base_url同样不带路径后缀让它按 provider 协议走。Superpowers 插件本身的安装Claude Code 里最简方式是# 在 Claude Code 会话里执行 /plugin install superpowersclaude-plugins-official装完后插件会落在~/.claude/plugins/superpowers/这时候上面 settings.json 里的 hook 路径才对得上。如果你用的是 Cursor在 Agent 聊天里输入/add-plugin superpowersGemini CLI 用gemini extensions install加仓库地址。多工具并用的话每个工具都要单独装一遍配置不共享。4. 验证请求确认代理调用真的生效配完不代表生效得验证。分三层查通道通不通、插件加载没加载、技能触发没触发。第一层先确认 TaoToken 通道能通。用 curl 直接打 APIcurl -s https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的TaoToken密钥 \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role: user, content: reply with ok}] }返回里如果有content字段且文本是 ok 之类说明 Key 和通道没问题。如果返回 401检查 Key 有没有复制全返回 404检查 base_url 是不是多写了路径。第二层验证 Claude Code 读到了配置。启动一个新会话输入claude --print echo $ANTHROPIC_BASE_URL如果输出https://taotoken.net/api说明环境变量注入成功。如果输出空或者官方地址说明 settings.json 的 env 没被读到检查文件路径和 JSON 语法用jq . ~/.claude/settings.json验一下。第三层验证 Superpowers 技能加载。新开会话后问代理claude --print 列出你当前可用的 superpowers 技能正常应该能看到 brainstorming、test-driven-development、systematic-debugging 这些技能名。如果代理说不知道检查 hook 脚本有没有执行权限ls -l ~/.claude/plugins/superpowers/hooks/session-start.sh chmod x ~/.claude/plugins/superpowers/hooks/session-start.sh然后手动跑一遍看有没有报错bash ~/.claude/plugins/superpowers/hooks/session-start.sh第四层端到端验证自动触发。给代理一个真实小任务比如帮我给这个项目加一个 utils 函数并写测试观察它是不是先进入 Brainstorming 提问而不是直接写代码。如果它直接开写说明技能没触发回到第三层查 hook。注意验证时用--print模式跑单次请求别在交互模式里反复试省 token。确认通道和技能都正常后再进交互模式做真实开发。5. 本篇常见错排查配这套东西踩坑概率不低我把高频问题列一下。报错一SessionStart hook failed with exit code 127。这是 hook 脚本路径不对或没执行权限。127 是 command not found检查~/.claude/plugins/superpowers/hooks/session-start.sh是否存在不存在说明插件没装成功重跑/plugin install。存在的话chmod x加执行权限。报错二401 Unauthorized但 Key 明明是对的。多半是 base_url 写错了。Claude Code 走 Anthropic 协议base_url 应该是https://taotoken.net/api不要写成https://taotoken.net/api/v1或带/messages。协议路径由客户端自己拼你只给根地址。报错三技能列表为空代理说没有 superpowers。检查 settings.json 里 hooks 字段的 JSON 结构。Claude Code 的 hooks 是SessionStart数组每个元素有matcher和hookshooks里才是type和command。层级写错就不会执行。用jq .hooks ~/.claude/settings.json看结构对不对。报错四代理跑着跑着卡住不动。Superpowers 的子代理驱动开发会派发独立子代理执行任务如果某个子代理卡在等待确认主流程会挂起。检查是不是approval_policy设成了always改成on-request或never后者慎用。另外deny列表里如果误拦了 git 操作子代理会反复重试直到超时。报错五多工具配置冲突。Claude Code 和 Codex CLI 同时用环境变量ANTHROPIC_API_KEY和TAOTOKEN_API_KEY别混。Claude Code 读ANTHROPIC_*Codex CLI 读env_key指定的那个。建议在 shell 里分别 export别写进同一个配置文件互相覆盖。报错六TDD 技能强制删代码。Superpowers 的 test-driven-development 技能有个硬规则删除所有在测试之前写的代码。如果你手动先写了实现再让它补测试它可能把你刚写的删掉。正确姿势是先让它写失败测试观察失败再让它写最少实现。这个规则很严格但确实是 TDD 的精髓。6. 长期编码与 Agent 场景的通道选择如果你只是偶尔用 Claude Code 补个函数上面这套配置够用了。但如果你打算让代理长期自主跑任务——比如 Superpowers 的子代理驱动开发一个任务派发一个子代理跑几个小时——那 Key 的消耗和通道稳定性就要认真考虑。这种场景下建议单独用 Coding Plan 通道地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。它和普通 API Key 的区别在于更适合高频、长时的编码代理调用配额和并发策略不一样。配置方式一样把ANTHROPIC_API_KEY换成 Coding Plan 的 Key 就行base_url 不变。模型对话类的轻量验证比如你只想确认某个模型响应正常用模型对话入口 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 更快不用起 Claude Code。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有针对不同工具的配置示例遇到协议细节可以对照查。Claude Code 的 Anthropic 协议接入专项说明在 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 如果你在 settings.json 的 env 字段上反复调不通直接看这份。最后说个实际经验Superpowers 的自动触发机制依赖 hook 在会话启动时注入引导指令所以每次改完 settings.json 都要新开会话才生效别在当前会话里改完就试。另外子代理驱动开发跑长任务时建议把ANTHROPIC_MODEL固定成你验证过稳定的版本别用会漂移的别名不然跑到一半模型换了行为会变。配置骨架搭好之后剩下的就是让它按 TDD 流程自己跑你只需要在关键审查点看一眼。