Claude Code 出问题时的分层排查方法

一次构建失败，日志依次出现四行：

14:02:11 PreToolUse hook "format.py" exit code 1
14:02:11 file not formatted
14:02:12 test failed: syntax error in app.ts
14:02:15 build aborted

很容易顺着时间读下去，认定是格式化脚本把 app.ts 弄坏了，于是去改 format.py。可时间顺序只是线索：格式化失败和语法错误也可能是两件互不相干的事。只修一处，另一处还在。

Claude Code 出问题时，界面往往只剩最后一个异常提示，而一次操作可能经过会话、指令加载、Settings、权限、Hook、MCP 和外部服务好几层。凭最后那句报错去改配置，常常改错地方；几处一起改，问题即使消失了，也说不清是哪一处起的作用。

更稳的排查有三步：

1. 先写一份能复现的故障记录：做了什么、期望什么、实际看到什么、环境有没有变；
2. 把症状归到一层，用这一层对应的工具取证；
3. 从日志里找到最早的那个异常，修完它，再逐项复测后面的结果。

下面先讲故障记录怎么写，再按层给出取证工具，最后回到这四行日志。

01 先写一份能复现的记录

先记录最短复现，再一次改变一个关键因素。若同时改配置、换模型和重装，问题即使消失，也很难判断哪个变化起了作用。记录至少包括：

• 你执行了什么具体操作，期望看到什么结果。
• 实际错误原文或异常表现是什么。
• 问题是否能够稳定复现，最短复现步骤是什么。
• 当前 Claude Code 版本、模型、账户和工作目录。
• 问题从什么时候出现，期间是否升级版本或修改配置。

有了时间、输入和期间的变化，就能提出值得先查的假设。比如一个斜杠命令突然换了输出格式，而期间有人新增了同名 Skill，“同名覆盖”就是第一个要查的方向，这个案例的完整排查见自定义 Skill 不显示或调到旧版的排查方法。

02 把症状归到一层

然后把症状归入最可能的层次：

无法启动或登录        → 安装、版本、认证、网络
回复慢或内容混乱      → 上下文、模型、网络、外部工具
规则或 Skill 未生效   → 配置发现与优先级
工具被拒绝            → 权限与沙箱
Hook 没触发           → 注册、匹配、脚本与退出结果
MCP 工具不可用        → 服务器配置、启动与认证
任务执行到一半卡住    → 后台任务、工具进程或 API 错误

先把排查范围缩小到一层，再动配置。排查到最后，应该留下能重复的判断依据。排查配置的官方文档对配置类问题的判断是：Claude 忽略一条指令、或者你配置的功能没出现时，原因通常是文件没加载，从你没预料到的位置加载了，或者被另一份文件覆盖了。

03 先拿到环境基线

当 Claude Code 无法正常启动、升级后行为异常、配置无法解析或认证连接有问题时，可以先在终端运行：

claude doctor

进入会话后也可以使用：

/doctor
/status

按 CLI 参考文档，claude doctor 不启动会话，只读地输出安装状态和设置文件校验错误；/doctor 是会话内的配置体检，会提出修复建议并在你确认后应用；/status 显示版本、当前模型、账户、连接状态和 Settings 来源。把它们作为环境基线，再针对具体故障取证。

04 各层的取证工具

响应慢：/context 会显示当前上下文由哪些内容组成，并给出优化建议。同一任务堆了长日志和无关历史，可以用 /compact 整理；换任务时，用 /clear 或新会话。

响应慢不一定来自上下文。先区分等待发生在首个输出前、输出过程中，还是固定工具调用之后，再查对应耗时与错误：

外部服务超时要查对应耗时与错误，盲目压缩上下文无法解决它。

规则未遵循：先用 /context 的 Memory files 核对实际加载；/memory 只提供文件入口，不能证明正文已经进入会话。完整步骤见CLAUDE.md 规则不被遵守的排查步骤。

工具被拒绝、反复询问：用 /permissions 看最终规则。先查命中的 deny、ask、allow，再核对托管策略、沙箱和工作区信任。只打开一个 settings.json，可能漏掉其他来源。

Hook 不工作：使用 /hooks 确认它是否注册，再检查事件、Matcher、命令路径、超时和退出码。

MCP 工具不能用：用 /mcp 查服务器启用了吗、启动成功了吗、认证有效吗。项目 MCP 可能还等首次批准；相对路径、环境变量和子进程目录不对，也可能让服务器反复断开。

分别确认调用是否允许、Hook 是否触发、MCP 是否连接，再沿实际链路检查相互影响。

05 在日志里找第一个错误

界面提示常只显示最终现象，详细日志用于还原失败过程。可以在会话中使用：

/debug Hook 为什么没有触发

官方文档对 /debug 的说明是：它为当前会话开启调试日志，并让 Claude 根据日志输出和设置路径来诊断。也可从终端用 claude --debug 或 claude --debug-file <路径> 启动；--debug 支持按类别筛选，筛选条件要用等号形式写，例如 --debug='mcp,startup'。

记录复现开始时间，按事件、工具、服务器或错误码提取相关片段，查看首次错误、触发输入、配置来源与相邻结果。整份日志会埋没重点，后续连锁报错也未必是根因。

回到开头那四行。先查 format.py 的输入和 stderr，再比较格式化结果、app.ts 的语法错误与构建失败。时间顺序只是线索，不能仅凭这几行证明格式化失败造成了语法错误；两项故障可能独立存在。

修正最早的异常后，后续结果仍要逐项复测。如果定位到了范围却还不知道是哪一项配置引起的，下一步就是做对照实验，方法见Claude Code 安全模式：找出出错的配置。一份能复现的记录、一个归好的层次、一行最早的错误，排查就有了起点。