Claude Code 跑 Agent + Hook + MCP 插件工作流：Key 用 TaoToken

昨天准备把一个 PR 交给 code-review 插件审查，命令刚敲下去，终端里瞬间出现 3 个并行 Agent 的进度条：一个查 CLAUDE.md 规则符合度，一个查明显 Bug，一个查历史上下文。等它们审完，security-guidance 的 Hook 又在文件保存和会话结束时各拦截了一遍。插件体系确实是 Claude Code 最工程化的那部分，但插件越复杂，模型调用次数就越翻倍，而且密钥分散在多个工具的配置文件里，想统一管理非常别扭。把这套工作流搬到 TaoToken 上，是我目前觉得最省心的做法：在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 拿一个 Key，把 Claude Code 的 Base URL 指到 https://taotoken.net/api，剩下一切照旧，插件目录不用动。

1. 插件目录：命令、Agent、Skill、Hook 与 MCP 的存放边界

插件的核心价值在于它不是一段独立脚本，而是可以把命令、Agent、Skill、Hook 和 MCP 组合成完整工作流的扩展单元。拿到这样一个仓库时，第一眼看到的是 plugins/ 目录下的稳定结构。它用一套统一约定把不同类型的组件拆开，让每个部分只承担一种职责。

plugin-name/
├── .claude-plugin/
│   └── plugin.json
├── commands/
├── agents/
├── skills/
├── hooks/
├── .mcp.json
└── README.md

1.1 plugin.json 是入口，其余目录各管一段

plugin.json 定义插件元数据，让 Claude Code 在启动时把它识别为独立插件。commands/ 放 Slash Command，适合承载用户主动触发的流程；agents/ 放专用 Agent，负责把某类分析任务拆给具备独立上下文的执行者；skills/ 放可被触发的能力说明与资源，封装特定领域的方法论；hooks/ 放事件处理逻辑，在工具调用、会话开始、会话结束等生命周期里插入规则；.mcp.json 则用来把外部服务或工具暴露给 Claude Code。

这套边界的价值在于认知负载低：命令定义入口，Agent 做专项判断，Skill 打包领域知识，Hook 做治理与提醒，MCP 管外部连接。你要加一个审查功能，不会去改 /code-review 的主逻辑，而是新增一个 Agent 或调整 Hook 的 matcher。你要让插件能查内部 API，也不会把所有调用写进命令，而是加一个 MCP server。

1.2 目录结构没问题，缺的是「模型通道」这一前提

插件结构本身完备，但它只回答了功能怎么组织，没有回答模型服务从哪来。code-review 能并行启动多个 Agent，security-guidance 能在文件编辑时精确拦截，背后的每一次语义分析、每一次工具调用，本质都是向模型服务发起请求。插件一多，请求次数成倍上升；仅仅一次 PR 审查就可能产生几十轮模型往返。更麻烦的是，命令、Agent、Skill、Hook 各自有调用点，密钥却集中在同一个 Claude Code 配置里，一旦某个组件需要单独指定模型通道，配置就开始拧巴。

这一步最好先把统一入口准备好：打开 TaoToken 注册并创建 API Key，把模型通道的凭证拿到手。后面配置时，所有组件的模型请求都会从这一个 Key 走。准备工作做完，回到插件目录本身，先看命令层怎么运转。

2. /code-review 的启动链：一个命令背后有多少次模型调用

真正跑起来时，第一个入口是命令层。feature-dev 插件里的 /feature-dev 把一次新功能开发拆成 7 个阶段：需求发现、代码探索、澄清问题、架构设计、实现、质量审查和总结。你输入 /feature-dev，Claude Code 会按这个顺序一路推进，期间穿插代码搜索、文件读写和上下文汇总。命令的价值在于降低启动成本，你不需要每次重新描述一遍完整流程。

2.1 Slash Command 把流程固化下来

code-review 埋得更深。它运行 /code-review 后，并不是把整个 PR 一次性抛给模型，而是先做一次「是否需要审查」的判断，收集 CLAUDE.md 里的规则，总结变更范围，再启动多个并行 Agent，最后用置信度过滤掉低价值结果。整套流程听上去优雅，实际上每一次判断、每一轮收集、每个 Agent 的分析，都在产生模型调用。

2.2 并行 Agent 是最大的调用消耗点

关键是 code-review 不是「一个 Agent 看完整个 PR」，而是同一时刻多个 Agent 从不同角度去审。一个负责规则符合性，一个负责明显 Bug，一个负责历史上下文；更完整的 pr-review-toolkit 甚至会拆出评论准确性、测试覆盖、静默失败、类型设计、通用代码审查和代码简化等专项 Agent。多视角审查确实比单次泛化审查稳定，但代价是请求量呈倍数增长。你可能注意不到这一点，直到某天发现一个命令跑完，额度消耗比预想快得多。

这个阶段如果让模型服务统一走 TaoToken，最大的价值不是「多一个 Key」，而是「所有 Agent 的模型请求都汇聚到同一个入口」。配置完成之后，你用 /code-review 审查同一个 PR，后台记录里能看到每个 Agent 各自消耗的请求数。这对判断哪些 Agent 值得保留、哪些 Agent 在重复劳动，非常有帮助。那么具体怎么切？进入 Claude Code 自己的设定文件看一下。

3. settings.json 里把 Claude Code 指到 TaoToken

Claude Code 读取用户级或项目级配置，路径通常是 ~/.claude/settings.json。你不需要给每个命令、Agent、Skill、Hook 分别配密钥，它们全部使用同一个模型服务配置。在配置文件的 env 块里写下这三项：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://taotoken.net/api",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY",
    "ANTHROPIC_MODEL": "YOUR_MODEL_ID"
  }
}

3.1 三个字段分别代表什么

ANTHROPIC_BASE_URL 是模型服务的根地址，填 https://taotoken.net/api，注意末尾不要补 /v1。ANTHROPIC_AUTH_TOKEN 就是前面从 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 创建出来的 API Key，正式使用前把 YOUR_API_KEY 替换成真实值。ANTHROPIC_MODEL 填模型 ID，具体型号以 TaoToken 官网模型广场为准，不要凭记忆写一个看起来差不多的名字。

3.2 为什么不是填官网地址

这里最容易翻车的是把官网地址放进 Base URL。https://taotoken.net/?utm_source=taotoken_aicg_blog_end 是注册、创建 Key、查看模型广场和用量统计的落地页，它是给人操作的界面，不是模型服务端点。Claude Code 需要的端点只有一个：https://taotoken.net/api。两者各自独立，不能混填；混淆之后工具会尝试向一个网页发起模型请求，结果自然是协议错误或 404。

改完 settings.json 后重启 Claude Code，在会话里查一下模型状态，确认端点生效。接着可以故意跑一个轻量命令验证最小链路，比如让任一 skill 的方法论加载一次；如果连渐进式披露都正常执行，说明 Agent 与 Slash Command 大概率也没问题。

4. security-guidance 与 hooks.json：在正确时机插入规则

Hook 的价值不是自动化，而是把规则放到正确的时机。security-guidance 在文件编辑、会话结束、提交等阶段各挂了一道检查：文件编辑之后会读取改动内容并提示风险；会话结束时会回顾整场对话，补上遗漏的安全提醒；提交阶段则在 git commit 前把关。设计思路是「不多跑、不白跑」，只在关键时间点触发，避免对整个仓库做全量扫描。

4.1 生命周期钩子如何减少无效调用

和命令启动的 Agent 不同，Hook 是被生命周期事件驱动的，开发者没法预判一次会话会触发多少次。会话里改了 8 个文件，编辑钩子就执行 8 次；每次执行如果都要做差异审查，模型往返次数就跟着文件数走。正因如此，Hook 场景对请求计费清晰的需求比命令还高：命令是主动发起的，Hook 是潜伏在工作流里的。统一的模型通道在这里的好处是，后台可以按时间把每次请求列出来，你能清楚看到一次会话结束后，编辑钩子、会话结束钩子和提交钩子各消费了多少请求。

4.2 security-guidance 的 hooks.json 配置写法

在插件自己的目录里，Hook 通常定义在 .claude-plugin/ 或 hooks/ 下。最通用的形式是单独一份 hooks.json。仿照 security-guidance 的思路，做一个「禁止危险 Bash 命令」的最小钩子：它只在 Bash 工具即将执行时触发，拦截风险命令后再决定要不要让 Claude Code 继续。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/plugins/security-guidance/scripts/bash-guard.py"
          }
        ]
      }
    ]
  }
}

这个钩子不会替你在终端里执行任何生产操作；它的工作是做事前判断并返回允许或拒绝结果，真正的风险命令仍然由你本地确认后才执行。安全审查比较重的团队，可以把会话结束钩子配成独立 Agent 的 review 模式，让模型把整场对话的重要结论汇总成检查项。由模型驱动的安全审查，此刻也在通过同一个 Base URL 走模型通道，请求记录会出现在 TaoToken 后台，方便对照当时会话行为做审计。

5. .mcp.json：把外部能力接进插件但不绕晕认证

MCP 解决的是「外部能力」接入问题。一个 code-review 插件如果只能读 diff，它能给出的建议很有限；一旦接上缺陷追踪系统、性能监控平台或数据库，它就能在评论里带上 issue 编号、错误日志和真实数据。.mcp.json 就是把这类外部服务封装成标准工具的地方，Claude Code 通过 MCP 协议发现并调用它们。

5.1 MCP 服务在插件里扮演什么角色

原文对 MCP 与命令的边界说得很清楚：当插件需要访问外部系统时，把能力封装成 MCP server，而不是把外部调用逻辑硬编码进 Slash Command。这样做的好处是权限控制和复用更清晰——同一个 MCP server 可以被多个命令、Agent、Skill 共享，而不是每个命令各写一套 HTTP 请求。

以「让插件能查询团队缺陷管理系统」为例，把 MCP server 声明在插件根目录的 .mcp.json 里：

{
  "mcpServers": {
    "issues-tracker": {
      "command": "npx",
      "args": ["-y", "@your-scope/issues-server"],
      "env": {
        "API_BASE_URL": "https://taotoken.net/api",
        "API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

这里的 @your-scope/issues-server 是占位包名，实际使用时要换成你们团队自己的 MCP server 包或本地脚本入口。env 里出现模型服务接口地址，是因为这个 MCP server 需要调用模型来把 issue 文本归纳成结构化卡片；它和 Claude Code 走同一个通道，所以模型请求会记到同一个账户下，后台能直接看到来自该 MCP server 的调用。

5.2 外部数据连接与本地执行的边界

MCP 负责把外部数据带进对话，不等于它可以直接操作生产系统。插件里的 Agent 拿到 issue 编号和日志后，可以生成对应的 SQL 或修复脚本，但这些 SQL 应该在本地数据库客户端执行，执行结果再贴回 Claude Code 做二次分析。把「读数据」和「写生产」分开，是插件设计中比较稳妥的做法；尤其当多个 Agent 并行工作、每个 Agent 各拿一份外部数据时，你在本地核对再让模型总结，能少踩不少「模型擅自改配置」的坑。MCP 连接数据库、API、内部平台的价值正在于此：把外部能力接到对话，同时把操作权留在人手里。

6. 验证执行与常见报错排查

配置完成后的完整验证路径可以这样走：重启 Claude Code，加载带 code-review 插件的项目，找到任意一个待审查的 PR，输入 /code-review。命令执行过程中观察 Agent 并发时的日志；结束后，回到 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 的用量记录看请求明细。你会看到这次操作对应的若干条模型请求，它们的 Base URL 都是 https://taotoken.net/api，可以逐个核对发起时间与命令执行时间是否吻合。如果后台记录与前台动作对得上，说明命令、Agent、Hook 和 MCP 全部收敛到了同一个入口，整个插件工作流已经真正跑通。

6.1 401 报错：Key 没替换干净

401 Unauthorized 通常在插件运行到一半时出现，表现为某个 Agent 突然拒绝继续。原因几乎都是 ANTHROPIC_AUTH_TOKEN 没有替换成有效 Key，或者从落地页复制时带进了换行。去官网重新复制一次，粘贴到 settings.json 时注意不要有多余字符。

6.2 404 报错：Base URL 多写了 /v1

404 通常在 Claude Code 启动模型检测或 Agent 尝试加载模型时出现。最主要的原因是 Base URL 写成了 https://taotoken.net/api/v1，或把官网落地页直接填进了工具。接口路径以 https://taotoken.net/api 为准，末尾不加 /v1；官网只负责管理 Key 和查看用量，不参与模型请求。

还有一种是模型 ID 错误。ANTHROPIC_MODEL 填了模型广场里不存在的 ID，Claude Code 能连上端点但拿不到合法模型，表现为「命令能启动，Agent 一运行就空结果」。这不是接口地址问题，而是模型名没有对齐；打开模型广场复制当前可用的模型 ID，回填 settings.json 即可。

插件体系里最容易低估的就是「一次 /code-review 背后到底有多少次模型调用」。命令、Agent、Skill、Hook、MCP 组合起来会产生大量请求，而密钥与端点只需要一份。把 settings.json 里的 ANTHROPIC_AUTH_TOKEN 替换成你的 Key，代码仓库、插件目录和团队协作方式都可以保持不变。花十分钟去 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 创建一个 Key，跑一次 /code-review，然后回 TaoToken 后台核对这次调用的请求清单——那些并行 Agent 和潜伏的 Hook，都会用一行行记录告诉你，插件工作流到底是怎么运转的。