1. 为什么 Claude Code 需要 MCP、Hooks 和 Subagent 三件套Claude Code 本身是一个能读写文件、执行命令的编码助手但它的默认能力边界很清楚不能直接查数据库、不能调 GitHub API、不能在你写完代码后自动跑 lint也没法同时让一个“代码审查专家”和一个“性能优化专家”并行干活。MCP、Hooks、Subagent 就是用来突破这三层边界的。MCPModel Context Protocol解决的是“连得上”的问题。它像 USB 标准一样把外部工具文件系统、数据库、GitHub、搜索服务统一封装成 Claude 能调用的接口。你只要在.mcp.json里声明一个 serverClaude 就能像调用内置工具一样调用它。Hooks 解决的是“自动触发”的问题。它让你在 Claude 执行某个动作的前后自动跑一段 shell 脚本。比如写完文件自动格式化、执行危险命令前拦截、任务完成后弹通知。Hooks 是事件驱动的不依赖你手动输入。Subagent 解决的是“专业化分工”的问题。一个 Claude 不可能同时精通代码审查、性能调优、安全审计和文档生成。Subagent 允许你定义多个专家代理每个有自己的系统提示词、工具权限和模型选择Claude 会根据任务自动调用合适的专家甚至并行调用多个。这三者组合起来Claude Code 就从“一个会写代码的助手”变成“一个能接入你整个工具链、自动执行流程、按需调度专家的开发平台”。下面我按 MCP、Hooks、Subagent 的顺序给出可复制的配置和逐步验证动作。2. TaoToken 前置准备与 Claude Code 接入配置在配置 MCP 和 Hooks 之前你需要先确保 Claude Code 能正常调用模型。这里用 TaoToken 作为 API 接入点它兼容 Anthropic 的接口格式配置方式和你平时用 Claude Code 一样只是把 Base URL 和 Key 换成 TaoToken 的。先拿到 API Key。打开https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite登录后创建一个新的 Key复制保存。这个 Key 后面会用在环境变量里不要硬编码到任何提交到 Git 的文件中。然后配置 Claude Code 的接入信息。Claude Code 读取的是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY两个环境变量。在 Linux/macOS 下你可以写到~/.bashrc或~/.zshrcexport ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的TaoToken密钥Windows PowerShell 下用$env:ANTHROPIC_BASE_URL https://taotoken.net/api $env:ANTHROPIC_API_KEY sk-你的TaoToken密钥如果你用的是 Claude Code 的 settings 文件方式可以在~/.claude/settings.json里写{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥 } }配置完成后启动 Claude Code输入/status查看当前模型和 API 端点。如果显示的是你配置的 Base URL说明接入成功。这一步很关键因为后面 MCP 和 Hooks 的调试都依赖 Claude Code 能正常对话。如果你在团队里用建议把 Base URL 和 Key 放在项目级的.claude/settings.local.json里并把这个文件加入.gitignore。团队共享的.claude/settings.json只放非敏感配置比如 Hooks 的 matcher 和命令模板。TaoToken 的接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite里面有不同客户端的配置示例。如果你用的是 Claude Code 的 Anthropic 兼容模式直接按上面的环境变量配置即可。配置完成后你可以先用模型对话页面验证 Key 是否有效https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite发一条消息确认能正常返回。3. MCP 服务配置从 .mcp.json 到 Commands 联动MCP 的配置有两种方式项目级.mcp.json和 CLI 命令claude mcp add。团队协作推荐用.mcp.json因为可以提交到 Git所有人共享同一套工具链。个人测试用 CLI 更快。先看.mcp.json的完整结构。在项目根目录创建这个文件{ mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, .], env: {} }, github: { command: npx, args: [-y, modelcontextprotocol/server-github], env: { GITHUB_TOKEN: ${GITHUB_TOKEN} } }, sqlite: { command: npx, args: [-y, modelcontextprotocol/server-sqlite, ./data/app.db], env: {} } } }这里filesystem的 args 里最后一个.表示允许访问项目根目录。github的GITHUB_TOKEN用${GITHUB_TOKEN}引用环境变量Claude Code 启动时会自动读取同名环境变量不需要你把 token 写进文件。sqlite指向本地的./data/app.db适合开发环境快速查表结构。如果你用 CLI 添加命令是claude mcp add filesystem -s user -- npx -y modelcontextprotocol/server-filesystem D:/Desktop D:/develop claude mcp add github -s project -- npx -y modelcontextprotocol/server-github claude mcp list-s user表示用户级所有项目可用-s project表示项目级只对当前项目生效。claude mcp list会列出所有已配置的 server 和它们的 scope。删除用claude mcp remove filesystem -s user。配置完成后启动 Claude Code你应该能看到类似✓ filesystem✓ github✓ sqlite的提示。如果某个 server 启动失败Claude Code 会显示错误信息通常是 Node.js 版本不够需要 v18或者 npx 下载超时。MCP 配置好之后你可以在 Commands 的 frontmatter 里直接引用 MCP 工具。格式是mcp__服务器名__工具名。比如一个自动创建 GitHub Issue 的 Command--- allowed-tools: - mcp__github__create_issue - mcp__filesystem__read_file - mcp__sqlite__query --- 读取当前项目的 TODO.md提取未完成项在 GitHub 上创建对应的 Issue。这样这个 Command 就能同时驱动 GitHub、文件系统和 SQLite 三个外部服务形成完整的自动化工作流。MCP 的三大作用域优先级是 Local~/.claude.json项目条目 Project项目根.mcp.json User~/.claude.json全局。含密钥的配置放 Local团队共享的放 Project个人通用工具放 User。4. Hooks 触发脚本settings.json 配置与实战示例Hooks 写在settings.json的hooks字段里。项目级放在.claude/settings.json用户级放在~/.claude/settings.json。项目级只对当前项目生效可以提交 Git用户级对所有项目生效。基本格式{ hooks: { PostToolUse: [ { matcher: Write|Edit, hooks: [ { type: command, command: jq -r .tool_input.file_path | xargs prettier --write } ] } ] } }matcher是正则表达式用来匹配工具名。空字符串匹配所有工具Write只匹配 Write 工具^Bash$精确匹配 Bash 避免误触BashScriptWrite|Edit匹配 Write 或 Edit。最佳实践是在 PreToolUse 里用严格正则防御危险命令在 PostToolUse 里用较宽的正则比如Write|Edit。Hook 脚本执行时Claude 会注入几个环境变量$CLAUDE_TOOL_NAME是当前工具名$CLAUDE_FILE_PATHS是被操作的文件路径空格分隔$CLAUDE_PROJECT_DIR是项目根目录$CLAUDE_TOOL_INPUT是工具的完整输入 JSON。几个实战场景。写完文件自动格式化{ hooks: { PostToolUse: [ { matcher: Write|Edit, hooks: [ { type: command, command: jq -r .tool_input.file_path | xargs -I {} prettier --write {} } ] } ] } }记录所有 Bash 命令到审计日志{ hooks: { PreToolUse: [ { matcher: ^Bash$, hooks: [ { type: command, command: echo \$(date) $CLAUDE_TOOL_INPUT\ $CLAUDE_PROJECT_DIR/audit.log } ] } ] } }任务完成后播放提示音macOS{ hooks: { Stop: [ { matcher: , hooks: [ { type: command, command: afplay /System/Library/Sounds/Glass.aiff } ] } ] } }注意 PreToolUse Hook 退出码为 2 时会阻止该工具调用其余退出码不会阻断执行。这个特性可以用来做危险命令拦截比如检测到rm -rf就退出码 2。配置完成后你可以这样验证在 Claude Code 里让它写一个文件然后检查文件是否被自动格式化。如果没生效先确认settings.json的路径和 JSON 格式正确再用echo $CLAUDE_FILE_PATHS在 Hook 脚本里打印变量确认注入是否正常。5. Subagent 定义与并行调用从 /agents 到多专家协作Subagent 是 Claude Code 通过 Task 工具启动的专业化 AI 代理。每个 Subagent 有自己的系统提示词、工具权限和模型选择。你可以用/agents交互式创建也可以手动写.md定义文件。手动安装的话全局代理放在~/.claude/agents/项目专用放在.claude/agents/。一个 Subagent 定义文件长这样--- name: code-reviewer description: Use this agent when the user requests code review, 代码审查, or 检查代码质量. tools: Glob, Grep, Read, WebFetch, WebSearch model: Sonnet memory: project --- 你是一位资深代码审查专家拥有超过15年的软件工程经验。你精通多种编程语言和架构模式擅长发现代码中的质量问题、潜在 bug 和性能瓶颈。 审查时请关注 1. 代码可读性和命名规范 2. 错误处理和边界条件 3. 性能问题和资源泄漏 4. 安全漏洞和注入风险 5. 测试覆盖和可维护性 输出格式按严重程度分级Critical / Major / Minor每条给出文件路径、行号和修复建议。tools字段控制这个代理能用的工具。只读审查用Glob, Grep, Read需要修改文件加Edit, Write需要执行命令加Bash。model可选 Sonnet、Opus、Haiku 或 Inherit from parent。memory可选 project、user、local 或 none。用/agents交互式创建更简单。输入/agents选择 Create new agent然后选存放位置Project 或 Personal选 Generate with Claude用自然语言描述代理职责Claude 会自动生成名称、系统提示词和工具选择。你只需要确认工具权限和模型按 s 保存即可。创建完成后直接在对话里说“给我做下代码审查”Claude 会自动识别并调用 code-reviewer 代理。你会看到绿色标识表示 Subagent 正在独立执行任务。对于复杂任务可以显式并行调用多个专家并行调用各个专家查看/解决以下问题 需要 - code-reviewer 检查代码质量 - performance-engineer 分析性能 - security-auditor 审计安全漏洞Claude 会同时启动 3 个子代理返回综合报告。但要注意每个子代理都有独立的上下文窗口token 消耗量巨大。建议按需调用不要一次性启动太多代理。常见故障排查/agents看不到代理检查文件是否在~/.claude/agents/或.claude/agents/代理安装成功但不被调用检查.md文件的 frontmatter 格式特别是description字段是否包含触发关键词并行调用超时减少并行代理数量改为分批调用。6. 常见报错排查与验证清单配置 MCP、Hooks、Subagent 的过程中最容易遇到几类报错。下面按现象、原因、解决方法对照。MCP 相关。启动时看不到 MCP 服务器先确认.mcp.json在项目根目录JSON 格式正确可以用jq . .mcp.json验证。服务器启动失败检查 Node.js 版本是否 v18node -v确认。${VAR}环境变量未生效用echo $VAR确认变量已导出重启终端。npx 下载超时可以设置npm config set registry https://registry.npmmirror.com换镜像源。工具调用被拒检查 Commands 的allowed-tools是否声明了对应的mcp__服务器名__工具名。Hooks 相关。Hook 没有触发确认settings.json路径正确JSON 格式无误。脚本报“命令未找到”脚本里用了 shell 别名或 PATH 不完整写完整路径比如/usr/local/bin/prettier。PreToolUse 误拦截matcher 正则范围太宽精确化正则比如^Bash$而不是Bash。文件路径变量为空工具不涉及文件操作改用$CLAUDE_TOOL_INPUT获取完整输入。Subagent 相关。/agents看不到代理安装路径错误或仓库未克隆确认代理文件在~/.claude/agents/或.claude/agents/。代理安装成功但不被调用Subagent 定义文件格式错误检查.md的 frontmatter 格式。并行调用导致超时启动的代理太多超过 token 限制减少并行数量改为分批调用。代理返回结果不符合预期代理描述匹配度不高在调用时更明确说明需求或显式指定代理。Token 消耗过多每个子代理都有独立上下文按需调用避免一次性启动太多。验证清单。MCP 配置后启动 Claude Code 看到✓标记在对话里让它读取一个文件确认 filesystem 生效。Hooks 配置后让 Claude 写一个文件检查是否自动格式化查看audit.log是否有记录。Subagent 配置后输入/agents看到代理列表在对话里说“做代码审查”确认自动调用。如果你在接入过程中遇到 401 错误先检查 TaoToken 的 Key 是否有效可以在https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite重新生成一个。如果报local proxy failed检查 Base URL 是否写成了https://taotoken.net/api不要多加路径。如果报reading choices相关错误通常是模型 ID 不对确认你用的模型名在 TaoToken 的模型列表里。OAuth 相关报错一般出现在 GitHub MCP 的 token 配置上确认GITHUB_TOKEN有repo权限。长期做编码和 Agent 开发的可以看下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite里面有适合持续开发的套餐。接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewriteMCP 和 Hooks 的配置示例都可以在里面找到对应说明。