AI Agent / 系统课时
排查 MCP 与 Hooks 问题
排查 MCP 与 Hooks 问题
MCP 与 Hooks 都能把 Claude Code 接到外部能力,但它们的故障边界不同:MCP 主要经过配置、连接与认证链路,Hooks 则经过事件、匹配器、输入、处理器和返回决策。把两条链路拆开检查,才能快速判断是扩展没加载、认证失效,还是 Hook 根本没有按预期触发。
学习目标
- 按配置作用域、连接状态和认证顺序排查 MCP
- 验证 Hook 的事件、matcher、stdin JSON 与退出行为
- 识别第三方 MCP、插件与 Hooks 带来的执行和凭据风险
先把两条故障链分开
MCP 的典型现象包括服务器完全不出现、处于待批准或未认证状态、连接失败,以及服务器已连上但工具被权限规则隐藏或拒绝。Hooks 的典型现象则是事件未触发、matcher 写错、脚本路径错误、stdout JSON 不合法,或误把普通退出码当成阻断结果。

因此第一步不是重装扩展,而是回答一个问题:当前失败发生在“服务器/工具不可用”,还是“事件处理逻辑不工作”。两者需要不同证据,混在一起修改只会扩大排查面。
按作用域和状态排查 MCP
MCP 有 local、project、user 三个常用作用域。local 默认只对当前项目生效并保存在 ~/.claude.json 的项目条目中;project 配置写入项目根目录 .mcp.json,适合团队共享;user 同样保存在 ~/.claude.json,但跨项目可用。同名服务器同时存在时,不会逐字段合并,而是按作用域优先级选中一个定义,所以“我改了 .mcp.json 却没生效”可能是更高优先级的 local 定义覆盖了它。
先在终端检查目标服务器:
claude mcp list
claude mcp get <NAME>预期结果
<NAME>: ✔ Connected实际输出格式和服务器详情可能随版本、传输类型而不同,但目标状态应为已连接。若看到 ⏸ Pending approval,进入交互式 Claude Code 完成工作区信任和项目服务器批准;若是 ! Needs authentication,用 /mcp 或 claude mcp login <NAME> 完成认证;若是 ✘ Failed to connect,继续检查端点、stdio 启动命令、环境变量和服务器返回的错误。
远程服务器使用静态 Header、OAuth 或动态 Header 时,要特别检查凭据来自哪里。.mcp.json 可以通过 ${VAR} 引用环境变量,避免把密钥直接提交到仓库;如果变量缺失,配置可能仍被加载,但服务器会带着未展开值继续工作并产生警告。认证失败时不要先重建服务器,先确认当前加载的是哪个同名定义以及该定义使用的认证方式。
验证 Hook 是否真的收到事件
Hooks 的核心链路是:事件触发后先由 matcher 决定是否执行,命令型 Hook 再从 stdin 接收 JSON。通用输入中可包含 session_id、cwd、hook_event_name,工具相关事件还会带 tool_name、tool_input 和 tool_use_id。所以最可靠的诊断方式不是在 stdout 随便 echo,而是把收到的字段写到独立调试文件。
下面是处理器片段示例,可保存为 .claude/hooks/inspect_hook.py。它依赖 Claude Code 在 PreToolUse 事件中通过 stdin 注入 JSON,用于记录关键字段,并且不向 stdout 输出调试文本:
import json
import os
import sys
from pathlib import Path
payload = json.load(sys.stdin)
project_dir = Path(os.environ.get("CLAUDE_PROJECT_DIR", "."))
log_path = project_dir / ".claude" / "hook-debug.jsonl"
record = {
"event": payload.get("hook_event_name"),
"tool": payload.get("tool_name"),
"cwd": payload.get("cwd"),
}
log_path.parent.mkdir(parents=True, exist_ok=True)
with log_path.open("a", encoding="utf-8") as handle:
handle.write(json.dumps(record, ensure_ascii=False) + "\n")预期结果
{"event": "PreToolUse", "tool": "Bash", "cwd": "<PATH>"}再把处理器挂到项目设置中。下面是配置片段示例,matcher 只匹配 Bash 工具:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "python3",
"args": [
"${CLAUDE_PROJECT_DIR}/.claude/hooks/inspect_hook.py"
]
}
]
}
]
}
}保存后可在 /hooks 中确认事件、matcher、处理器类型和配置来源。随后让 Claude 触发一次 Bash 调用,再检查 .claude/hook-debug.jsonl。若没有新记录,优先查 Hook 是否加载、工作区信任、matcher 是否使用了正确的工具规范名,以及脚本路径或解释器是否存在。
理解退出码与 stdout 的语义
Hook 返回值经常是误判来源。对大多数可阻断事件,exit 0 表示处理器正常结束;如果 stdout 是合法的结构化 JSON,Claude Code 会读取其中的决策字段。exit 2 才是通过退出码直接表达阻断的特殊值,而且不同事件对“阻断”含义不同,例如 PreToolUse 会阻止工具调用。
普通的 exit 1 对大多数 Hook 事件并不自动等价于“禁止执行”,通常只是非阻断错误。另一个常见问题是 stdout 混入调试文本:当 Hook 需要返回 JSON 决策时,stdout 应只包含该 JSON 对象,否则解析失败后动作可能继续执行。调试信息更适合写 stderr 或独立日志文件,并用 Claude Code 的 debug 日志核对 matcher、退出码、stdout 和 stderr。
需要更完整证据时,可以启动诊断会话:
claude --debug-file <PATH>预期结果
调试日志写入 <PATH>;终端中的交互会话正常启动。实际日志内容与事件有关。Hook 没触发时重点找加载来源和 matcher;Hook 已触发但行为不对时,再看退出码、stdout 解析以及事件是否支持对应决策。
控制第三方扩展的信任边界
MCP 服务器和 Hooks 都可能引入本机之外的代码与数据。项目级 .mcp.json 需要关注工作区信任和服务器批准;命令型 Hooks 更敏感,因为它们会以当前用户权限执行 Shell 命令。不要因为仓库能正常克隆,就默认其中的 .claude/settings.json、.claude/hooks/ 或插件内容可信。
上线前至少核对三点:第三方 MCP 只获得任务所需的最小认证范围;共享配置不直接保存长期密钥;Hook 命令、参数和脚本路径经过代码审查。对陌生仓库做非交互自动化时尤其要谨慎,因为无交互执行与普通交互式信任流程并不完全相同。
MCP 排障要沿“作用域→批准→连接→认证→工具→权限”前进,Hooks 排障则沿“事件→matcher→输入→处理器→返回值”前进。只要先确认链路断点,再用状态命令、输入日志和 debug 日志形成证据闭环,大多数扩展问题都不需要靠删除配置或反复重装来碰运气。