51 · 常见问题排查（FAQ / Troubleshooting）
📚 系列导航：上一篇 50 反模式：常见的错误用法 把那些「看着没错、其实在挖坑」的用法挨个点名。这一篇接着聊排查——当 Claude Code 真出毛病的时候，怎么按图索骥、一步步排查到根。装不上、登不进、权限拦你、MCP 不连、跑得卡、蹦个红字报错……这篇给你一套「症状 → 该翻哪、该敲啥」的查问题地图。
先说一个特别典型、又特别容易把人坑进去的场景，理解它你就明白这一篇要解决什么。
设想这么个情况：刚换了台新 Mac，从公司项目里把 Claude Code 装好，一启动就弹 This organization has been disabled。第一反应往往是「完了，是不是账号被封了」，赶紧登 claude.ai 查订阅——好好的，Max 还在。又怀疑是网络，挂了魔法上网重试，还是那行字。这么前前后后折腾快四十分钟，重装了两遍 Claude Code，差点就去开工单了。
结果根因是啥？那台老 Mac 迁移配置过来的时候，~/.zshrc 里躺着一行早就忘了的 export ANTHROPIC_API_KEY=...，是半年前接的一个已经注销了的公司项目留下的旧 key。环境变量优先级压过了订阅登录，Claude Code 老老实实拿那把作废的 key 去认证，可不就被告知「这个组织已禁用」么。一行 unset ANTHROPIC_API_KEY，秒好。
说这个例子是想让你记住一件事：排查问题最忌讳「靠猜」。 那四十分钟全花在瞎猜上了——猜账号、猜网络、猜得越多离真相越远。其实 Claude Code 自己就带着体检工具，一句 /status 就能告诉你「当前用的是哪套凭证」，根本不用猜。这一篇就教你不靠猜、按流程把问题逼到墙角。
看完这一篇，你会拿到：
- 一张「症状 → 去哪查」的总路由表：报错先对号入座，别一上来乱试
- 两个最该先敲的自助命令——
/doctor体检、/feedback上报——分别什么时候用 - 按六大类（安装、登录认证、权限、MCP、性能、报错信息）整理的「问题 → 解决」对照
--debug系列调试开关怎么用，以及「干净配置对照法」这个排查杀手锏- 一个能照着跑、给了预期输出的实战：亲手用
/doctor给自己的安装做一次体检
01 排查的第一原则：先定位「这是哪一类问题」，别瞎试
先给结论，这条原则比后面所有具体命令都重要：遇到问题，第一步不是动手修，是先搞清楚「它属于哪一类」——是装的问题、登录的问题、配置的问题，还是 API 那头的问题。 类别定错，后面全白忙。
类比：水管漏水先关阀门，别先撬地砖。 家里某处渗水，老师傅来了不会上来就砸墙——他先判断「是水龙头的、是接头的、还是楼上漏下来的」。判断错了，地砖撬一地也找不着漏点。排查 Claude Code 一个道理：先分诊，再下手。
为什么这条最重要？因为 Claude Code 的官方文档本身就是按类别拆开的——安装登录一页、运行时报错一页、配置调试一页、性能一页。你要是连「我这属于哪类」都没分清，翻文档都不知道翻哪页。官方故障排除页开头直接甩了一张路由表，我把它翻成你最可能撞上的样子：
| 你看到的症状 | 这属于哪类 / 去翻哪篇 |
|---|---|
command not found: claude、装不上、PATH 问题、EACCES | 安装类（详见第 02 篇 + 本篇 02 节） |
反复让你登录、403 Forbidden、organization disabled | 登录认证类（本篇 03 节） |
| 设置没生效、hooks 没触发、MCP server 没加载、权限规则没拦住 | 配置类（本篇 04 节 + 调试你的配置） |
API Error: 5xx、529 Overloaded、429 | API 报错类（本篇 06 节，多半不是你的错） |
model not found / you may not have access to it | 报错类（本篇 06 节，模型选错或没权限） |
| 卡顿、高 CPU / 内存、搜索找不到文件 | 性能类（本篇 05 节） |
用法很简单：左列找一句最像你屏幕上那句的，右列告诉你该往哪个方向查。 这一篇后面每一节，就是把这张表的每一类掰开细讲。
这里插一句官方的话，值得你刻在脑子里：「如果你不确定哪个适用，请在 Claude Code 内运行
/doctor来自动检查你的安装、设置、MCP 服务器和上下文使用情况。如果claude根本无法启动，请从你的 shell 运行claude doctor。」
也就是说——分不清类别？别纠结，先 /doctor 跑一遍，它会替你把大半个方向指出来。下一节就专门讲这俩自助命令。
💡 一句话总结：排查第一步永远是先分诊、不瞎试——对着症状路由表认清「这是哪一类」，再去对应章节下手；实在分不清就先
/doctor。
02 两个自助命令：/doctor 体检、/feedback 上报
在你翻任何文档、问任何人之前，Claude Code 自带两个「自助」入口。九成的问题，要么 /doctor 直接给你指出来，要么实在解决不了用 /feedback 上报。 先把这俩用熟，能省你大把时间。
类比：身上不舒服，先去做个全身体检。 你哪儿疼了不会一上来就开刀，先做个体检——血压、心率、各项指标一拉，医生扫一眼报告就知道大概问题出在哪。/doctor 就是 Claude Code 的体检仪：一条命令，把安装是否健康、配置有没有语法错、MCP 连没连上、上下文占了多少，一次性给你查个遍。
/doctor：一键体检
/doctor 是你排查时最该先敲的命令。它检查的东西，官方列得很清楚——安装健康状况、设置有效性（有没有无效的键、schema 错误）、MCP 配置、上下文使用情况。
关键看你能不能启动：
- 能进会话：直接在 Claude 里敲
/doctor。 claude根本起不来（比如command not found、一启动就崩）：在你的终端（shell）里敲claude doctor——注意这个没有斜杠，是个独立的命令行子命令。
/doctor 还有个贴心设计：当它报出问题时，按 f 能把这份诊断报告直接发给 Claude，让它陪你一步步解决。 等于体检完，医生就在旁边给你读报告。
/feedback：实在搞不定，上报
如果你按文档查了、/doctor 也跑了，问题还在——别自己死磕，用 /feedback 上报给 Anthropic。它会把你的对话记录连同描述一起发过去，这是官方诊断真实问题（尤其是「响应质量莫名变差」这种没有报错的玄学问题）最快的方式。这个命令还提供一个选项：帮你打开一个预填好内容的 GitHub issue。注意：如果你用的是 Bedrock、Vertex 等第三方提供商，/feedback 不会把信息发给 Anthropic，而是保存到本地存档，需要你手动发给 Anthropic 的账户代表。
你可能在别处听过
/bug这个说法——它就是「上报问题」这件事的旧叫法。现在官方统一用/feedback：在会话里把记录和描述发给 Anthropic，或顺带开一个预填的 GitHub issue。记/feedback这一个就够。
这里给你整理一张「先敲啥」对照表：
| 你的处境 | 先敲这个 | 它干嘛 |
|---|---|---|
| 不确定问题属于哪一类 | /doctor | 一次性体检，指出大方向 |
claude 压根起不来 | claude doctor（在终端） | 启动前就能跑的诊断 |
/doctor 报了问题、想让 Claude 帮我解 | 在 /doctor 结果里按 f | 把诊断报告甩给 Claude |
| 查完文档也解不了 | /feedback | 把记录 + 描述上报 Anthropic |
| 想看看是不是官方在挂 | 浏览器开 status.claude.com | 查 API 是否有线上事故 |
最后那条 status.claude.com 特别值得记住：遇到一堆 5xx、529 这种服务器错误时，第一件事是去这个状态页看一眼，而不是怀疑自己——很多时候是 Anthropic 那头在抖，跟你的配置一毛钱关系没有。这点第 06 节还会细说。
💡 一句话总结：排查前先动两个自助命令——
/doctor（或终端claude doctor）做体检指方向、/feedback在搞不定时上报；服务器疑似挂了先看status.claude.com。
03 登录认证类：被反复要求登录、组织被禁用
从这节起，咱们按类别过具体问题。先说登录认证——这类最容易让新手慌，因为报错字眼一个比一个吓人（disabled、Forbidden、revoked），但真相往往特别朴素。
类比：进公司刷门禁卡，刷不开未必是你被开除了。 可能是卡消磁了、可能是你拿错了一张旧工牌、可能是门禁系统时间没对上。报错说「拒绝进入」，不等于「你没资格」。认证问题也一样——先看「Claude Code 到底拿哪套凭证去认证的」，别一上来就往最坏处想。
第一招：看清「当前用的是哪套凭证」
这是认证类问题的万能第一步，也是开头那四十分钟弯路的解药。在会话里敲：
text
/status预期：它会显示当前活跃的身份验证方式——是你的订阅（OAuth 登录），还是某个 API key。如果你明明是订阅用户，这里却显示在用 API key，问题基本就锁定了。
最经典的坑：ANTHROPIC_API_KEY 偷偷压过订阅
开头栽的就是这个。官方把机制讲得明明白白：
环境变量优先于
/login，因此在你的 shell 配置文件中导出或从.env文件加载的密钥，即使你有有效的 Pro 或 Max 订阅也会被使用。在非交互模式（-p）中，当存在密钥时总是使用该密钥。
所以只要你环境里有个 ANTHROPIC_API_KEY（哪怕是几个月前某项目留下、你早忘了的），Claude Code 就会拿它去认证。这个 key 一旦失效或属于被禁用的组织，就报 This organization has been disabled。解药：
bash
unset ANTHROPIC_API_KEY
claude但 unset 只对当前终端窗口有效，要彻底根治，得去 ~/.zshrc、~/.bashrc 或 ~/.profile 里把那行 export ANTHROPIC_API_KEY=... 删掉（Windows 上查 PowerShell 配置文件 $PROFILE 和用户环境变量）。删完重启 claude，再 /status 确认已经切回订阅。这套「凭证优先级」第 04 篇（API 配置）讲过，认证出问题时记得回去对一眼。
其它几个常见认证报错，对症下药
| 报错 | 啥意思 | 怎么修 |
|---|---|---|
Not logged in · Please run /login | 这个会话没有效凭证 | 敲 /login 登录；若指望环境变量认证，确认 ANTHROPIC_API_KEY 真的导出了 |
OAuth token revoked / has expired | 保存的登录失效了 | /login 重登；同会话又报就先 /logout 再 /login |
| 反复被要求登录（跨多次启动） | 令牌总是失效 | 查系统时钟准不准（令牌校验依赖正确时间戳）；macOS 上 Keychain 锁了也会这样，跑 claude doctor 查 Keychain 访问 |
403 Forbidden（登录后） | 订阅 / 角色 / 代理问题 | Pro/Max 去 claude.ai/settings 看订阅；Console 用户确认账户有 Claude Code 或 Developer 角色 |
Invalid API key | key 被拒 | 查拼写、确认没在 Console 撤销；env | grep ANTHROPIC 看是不是 .env 加载了过时 key |
那个「反复登录就查系统时钟」是真容易被忽略——一台长期没联网的虚拟机上常会死活登不上，最后往往发现是机器时间慢了三天，令牌一签发就被判过期。对一下时间，秒好。
💡 一句话总结：认证问题先
/status看「在用哪套凭证」；最坑的是 shell 里残留的ANTHROPIC_API_KEY压过订阅（unset+ 删配置文件）；反复掉登录优先查系统时钟和 macOS Keychain。
04 配置类：设置 / hooks / MCP「写了没生效」
第二类是配置不生效——你明明在 settings.json 里写了规则、配了 hook、加了 MCP server，结果 Claude 跟没看见似的。这类问题官方专门有一页叫「调试你的配置」，核心就一句话：先确认 Claude Code 到底「实际加载了什么」，别假设你写的就生效了。
类比：交了作业不等于老师收到了。 你把作业放讲台上就走了，没生效可能是放错了桌子、夹在别人本子里了、或者被另一份覆盖了。配置一个道理——没生效，先去查「它实际读进去的是哪份」，而不是反复改你以为对的那份。
一组「查实际加载了啥」的命令
这是配置类的核心工具箱，每个命令查一类东西，对症用：
| 命令 | 查什么 |
|---|---|
/context | 当前会话里上下文都被谁占了（系统提示、内存文件、skills、MCP 工具、消息） |
/memory | 加载了哪些 CLAUDE.md 和规则文件 |
/skills | 来自项目 / 用户 / 插件的可用 skills |
/agents | 配置的子代理及其设置 |
/hooks | 当前会话注册了哪些 hook |
/mcp | 连上的 MCP server 及其状态 |
/permissions | 当前生效的允许 / 拒绝规则 |
/debug [问题描述] | 为会话启用调试日志，并提示 Claude 用日志输出和设置路径来诊断 |
/status | 哪些设置源是活跃的（含是否启用了托管设置） |
用法是「我配了啥没生效，就敲对应那个命令看它在不在」。比如你写了 hook 没触发，先 /hooks 看它有没有被注册——没出现，说明压根没被读到；出现了却不触发，那是匹配器（matcher）的问题。
几个新手最常踩的配置坑
官方那张「症状 → 原因 → 修复」表里，我挑出小白最高频的几条：
| 症状 | 多半是因为 | 怎么修 |
|---|---|---|
| hook 永远不触发 | matcher 写成了小写（如 "bash"） | 工具名区分大小写且首字母大写：Bash、Edit、Write、Read |
| hook 永远不触发 | hook 写进了独立文件 | 项目 / 用户的 hook 必须放在 settings.json 的 "hooks" 键下 |
settings.json 的值好像被忽略 | 同一个键在 settings.local.json 里也设了 | settings.local.json 覆盖 settings.json，两者都覆盖 ~/.claude/settings.json（详见第 31 篇） |
.mcp.json 里的 MCP server 从不加载 | 文件放进了 .claude/ 目录下 | 项目 MCP 配置要放在仓库根目录的 .mcp.json，不在 .claude/ 里 |
| 项目 MCP server 没出现 | 一次性批准提示被关掉了 | 项目级 server 需要批准，敲 /mcp 查状态并批准（详见第 22 篇） |
子目录的 CLAUDE.md 指令没生效 | 它是「按需加载」的 | 只在 Claude 用 Read 读那个目录文件时才加载，不是启动时（详见第 18 篇） |
那个「hook 的 matcher 大小写」最容易踩：第一次写 PostToolUse hook，matcher 填了 "edit|write"，怎么改文件都不跑。/hooks 里明明显示注册了，对着配置看半天也看不出毛病——最后才反应过来工具名得大写成 "Edit|Write"。官方原文：「匹配是区分大小写的。」 这种坑不知道就是死活查不出，知道了就一秒解决。
权限相关：「明明配了规则，怎么还是拦不住 / 老来问我」
权限（permission）问题也归在配置这一类，新手常撞两种：
一种是「我写进 CLAUDE.md 的禁令没拦住」。 关键认知：CLAUDE.md 里的「永远不要编辑 .env」是一句「请求」，不是「保证」。官方把这点说得很透——要 Claude「做好决定」用 CLAUDE.md，要「无论它怎么决定都强制执行」的硬约束，得用权限规则或 hook（详见第 20、21 篇）。所以真要拦死某个操作，别指望 CLAUDE.md，去写 deny 权限规则或 PreToolUse hook。
另一种更隐蔽：deny 规则写了，却拦不住等效命令。 比如你写了 Bash(rm *) 想禁删除，结果 Claude 用 /bin/rm 或 find . -delete 照样删得掉。原因是——前缀规则匹配的是「字面命令字符串」，不是底层那个可执行文件。解法是为每个变体都加显式规则，或者干脆上 PreToolUse hook / 沙箱来拿「硬保证」。排查权限时，先敲 /permissions 看当前实际生效的允许 / 拒绝规则，对一眼是不是你以为的那套。
这背后是第 50 篇反模式讲过的同一个道理：把「安全边界」托付给一句自然语言指令，本身就是个反模式——指令是软的，规则和 hook 才是硬的。
💡 一句话总结：配置没生效，先用
/context、/memory、/hooks、/mcp、/permissions这组命令查**「实际加载了什么」**；高频坑是 hook matcher 大小写写错、配置被优先级更高的settings.local.json覆盖、.mcp.json放错目录、以及把「安全禁令」错写进 CLAUDE.md 而不是deny规则。
05 性能类：卡顿、高内存、搜索找不到文件
第三类是跑得不舒服——响应越来越慢、内存吃得吓人、@file 死活补全不出来。这类官方归在「性能和稳定性」里，大多跟「上下文塞太满」和「环境小问题」有关，很少是 bug。
类比：电脑越用越卡，多半是后台开太多，不是硬件坏了。 你不会一卡就送修，先关几个吃内存的程序、清一波缓存。Claude Code 卡顿一个道理——先收拾「工作台」，别急着重装。
卡顿 / 高内存：先收拾上下文
官方给的处理顺序很务实：
- 定期用
/compact压缩上下文（把对话整理成一页要点，详见第 19 篇）。 - 在主要任务之间关掉再重启 Claude Code。
- 把大型构建目录加进
.gitignore，别让它去扫。
如果这么做内存还是高，可以跑 /heapdump——它会把一份 JavaScript 堆快照写到 ~/Desktop（Linux 上没桌面就写主目录），报内存问题时把它附在 GitHub issue 上。这命令你日常用不到，知道有这么个东西就行。
关于「卡死、转圈不动」：官方说得很干脆——先按 Ctrl+C 试着取消当前操作；要是彻底没反应，关掉终端重启。重启不会丢对话，在同一目录跑
claude --resume就能接着上次的会话往下走。
自动压缩「抖动」：一个新手会被吓到的报错
你可能撞见这行：Autocompact is thrashing: the context refilled to the limit...。别慌——意思是自动压缩成功了，但有个超大文件或工具输出立刻又把上下文塞满了，Claude Code 为了不空转烧 API 调用，主动停了重试。恢复办法：让它分块读那个超大文件（指定行范围或某个函数，别整文件读），或者 /compact 时点名「只保留计划和 diff」，再不行就 /clear 重开。
搜索 / @file 补全失灵：换个 ripgrep
如果搜索工具、@file 提及、自定义 skill 找不到文件，多半是 Claude Code 自带的那个 ripgrep（一个高速搜索工具）在你系统上跑不起来。官方解法是装系统版的 ripgrep 再让 Claude Code 改用它：
bash
# macOS
brew install ripgrep然后在环境变量里设 USE_BUILTIN_RIPGREP=0（环境变量怎么配详见第 42 篇）。
这里给一张性能类的「症状 → 先做啥」速查：
| 症状 | 先做这个 |
|---|---|
| 越用越慢、内存高 | /compact，然后重启 Claude Code |
| 彻底卡死、转圈不动 | Ctrl+C；不行就关终端，claude --resume 续上 |
看到 Autocompact is thrashing | 让它分块读大文件 + /compact keep only ... |
@file 补全 / 搜索找不到文件 | 装系统 ripgrep，设 USE_BUILTIN_RIPGREP=0 |
| 集成终端里文字乱码、糊成方块 | 在 Claude 里跑 /terminal-setup 关掉 GPU 渲染 |
最后那条「乱码」在 VS Code 内置终端里偶尔会撞见，整屏字符糊成豆腐块，挺唬人。跑个 /terminal-setup 把终端的 GPU 加速关掉，重载窗口就清爽了——纯渲染问题，跟 Claude 本身没关系。
💡 一句话总结：性能问题先怀疑「上下文太满」——
/compact+ 重启是万金油；卡死按 Ctrl+C /claude --resume；搜索失灵换系统ripgrep；终端乱码跑/terminal-setup。
06 API 报错类：蹦红字了，先分清「是不是你的锅」
第四类是会话里直接蹦出一行 API Error: ...。新手一看红字就慌，其实这类最该做的，是先分清这报错是「服务器那头的事」还是「你这头的事」——两者的处理方式完全相反。
类比：网页打不开，先分清是网站挂了还是你断网了。 网站挂了你刷新一百遍也没用，等它修；你断网了那才该去查自己的路由器。API 报错一个逻辑——先判断锅在谁那儿，再决定是「等」还是「改」。
先记住：Claude Code 早就帮你自动重试过了
官方有个机制值得先知道：服务器错误、过载、超时、临时限流、断连，Claude Code 都会自动以指数退避重试最多 10 次，重试时你会看到转圈旁边显示 Retrying in Ns · attempt x/y 的倒计时。所以——当你真看到一行报错时，意味着这些重试已经全用完了，不是它一下就放弃了。
三大类报错，三种应对
我把官方那张超长报错表归成你最该分清的三堆：
| 报错长这样 | 锅在谁 | 你该干嘛 |
|---|---|---|
API Error: 500 / 529 Overloaded / Server is temporarily limiting requests | 服务器（不是你） | 等一会儿重试；查 status.claude.com；/model 换个模型（容量是按模型算的） |
You've hit your session/weekly/Opus limit | 你的额度用完了 | 等重置时间；/usage 看额度；/usage-credits 加购或升级套餐 |
Prompt is too long / Request too large | 你的请求太大了 | /compact 或 /clear；超大文件按路径让它分块读，别整段粘贴 |
这三堆的处理逻辑天差地别：第一堆「等就完了」，第二堆「掏钱或等重置」，第三堆「精简你的输入」。分不清就容易做反——服务器在抖你却在删自己的对话，或者额度满了你却以为是 bug 一直重试。
还有一类是连不上 API（Unable to connect to API、fetch failed、Request timed out 带「检查网络」字样）——这通常不是 Anthropic 的事，是你这头的网络、VPN、代理或防火墙。第一步先在同一个终端里验证你能不能摸到 API 主机：
bash
curl -I https://api.anthropic.com通了说明网络没问题，问题在更上层（比如代理 / 证书）；Could not resolve host 或超时就是网络被挡了。国内用户这里十有八九是要开魔法上网；公司网络后面则多半得配 HTTPS_PROXY。如果是慢网络老超时，可以把单次请求超时调长——官方给了两个旋钮（环境变量配法详见第 42 篇）：
| 环境变量 | 默认值 | 干嘛的 |
|---|---|---|
API_TIMEOUT_MS | 600000（10 分钟） | 单次请求超时，慢网络 / 代理就调大 |
CLAUDE_CODE_MAX_RETRIES | 10 | 自动重试次数，脚本里想快点失败就调小 |
两个新手高频、又容易误解的报错
model not found / you may not have access to it：配置的模型名没被识别，或你账户没权限。先在交互式 CLI 里敲 /model 从可用模型里重选。如果错误的模型老是冒出来，说明某处设了过时的模型 ID——按优先级查：--model 标志 → ANTHROPIC_MODEL 环境变量 → settings.local.json → 各级 settings.json 里的 model 字段，把过时值删掉就回落到账户默认了。官方还有个实在建议：用别名（如 sonnet、opus）而不是写死的版本号 ID，别名会自动跟最新版，不会过时（/model、ANTHROPIC_MODEL 等配置方式详见第 04 篇 API 配置）。
Claude Code is unable to respond to this request, which appears to violate our Usage Policy：使用政策检查拦下了。注意一个反直觉的点——这个检查评估的是整段对话，不只是你最后那句，所以在同一会话里换句话再发，往往还会触发同样的拒绝。正确做法是按两下 Esc 或 /rewind 回退到触发那一轮之前（详见第 37 篇），换个表述或思路；实在找不到是哪轮，/clear 重开一段对话。
💡 一句话总结：API 报错先分三堆——
5xx/529是服务器的锅（等 + 查状态页 + 换模型）、hit your limit是额度（等重置或加购）、too long/too large是你输入太大（/compact/ 分块读）；Unable to connect是你这头的网络（curl验主机、必要时开魔法上网 / 配代理）；模型报错优先用别名、查过时 ID。
07 杀手锏：--debug 调试日志 + 干净配置对照法
前面六类覆盖了九成情况。但总有那么一两次，症状怪、按文档查也定位不到。这时候祭出两个进阶武器，基本能把最刁钻的问题也逼出来。
类比：查电路故障，万用表 + 逐个拔插。 修电路的老师傅遇到说不清的故障，一是拿万用表实时量哪段电压不对（看实时日志），二是把电器一个个拔下来试、看拔哪个故障消失（逐个排除）。排查 Claude Code 的两个杀手锏，正是这两招的翻版。
武器一：--debug 实时看它在干啥
光看结果猜不出原因时，带 --debug 启动，让它把内部过程打出来给你看。针对不同问题还能加子标志，精准只看你关心的那部分：
| 命令 | 用来查 |
|---|---|
claude --debug | 通用调试日志，看整体在干啥 |
claude --debug mcp | MCP server 启动 / 连接的 stderr 输出（server 显示连上却零工具时用它） |
claude --debug hooks | 实时看每个 hook 事件、匹配了哪些 matcher、退出码和输出（hook 不触发时用它） |
还有个会话内的入口 /debug [问题描述]：它为本次会话开启调试日志，并直接提示 Claude 用日志和设置路径帮你一起诊断。
用法举例：你的 hook 在 /hooks 里明明注册了却死活不跑——这时候 claude --debug hooks 启动，触发一次工具调用，日志会清清楚楚告诉你「这个事件来了，检查了哪个 matcher，匹没匹上」。比你对着配置干瞪眼强一百倍。
武器二：干净配置对照法（最被低估的一招）
这招特别值得记住，专治「到底是不是自己配置惹的祸」这种悬案。思路是：开一个啥都不加载的干净会话，跟你平时那个对照——问题要是在干净会话里消失了，那就是你自己配置里某处出了问题。官方给的命令：
bash
cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude这一句把 CLAUDE_CONFIG_DIR 指向一个空目录，绕开 ~/.claude 下的一切；再从一个没有 .claude 文件夹、没有 .mcp.json、没有 CLAUDE.md 的目录（/tmp）启动，连项目配置也一并跳过。于是这个会话没有任何用户 / 项目设置、hooks、MCP、插件、内存。
- 问题在干净会话里消失了 → 根因就在你真实的
~/.claude或项目.claude里。接下来一次只加回一样（复制一个文件进去、或从你项目启动），看加回哪个问题重现，凶手就是它。 - 干净会话里照样有问题 → 那根因在你的用户和项目配置之外（可能是托管设置、环境变量，或更底层的安装问题）。
这套「二分法」是排查的通用智慧——通过「砍掉一半变量看问题在不在」来缩小范围。比如 Claude 莫名其妙不读某条 CLAUDE.md 规则，靠干净会话就能确认「不是 Claude Code 的 bug，是项目里两份 CLAUDE.md 指令打架」，省了去翻一晚上文档。
💡 一句话总结：怪问题上两个杀手锏——
claude --debug [mcp/hooks]实时看内部过程定位「为啥不工作」，**干净配置对照法（CLAUDE_CONFIG_DIR指向空目录）**判断「到底是不是我配置的锅」，再二分法逐个加回锁定凶手。
08 动手：给你的安装做一次完整体检
光看不练记不住。下面带你亲手把 /doctor 体检跑一遍，再顺手验证一下你的认证状态。全程不依赖任何复杂环境，装好 Claude Code 就能做。
第一步：在终端确认 claude 装对了、版本是新的
bash
claude --version预期：打印一行版本号，类似 2.1.xxx (Claude Code)。看到版本号 = 安装基本健康。 如果报 command not found: claude，说明安装目录不在 PATH 里——这是安装类问题，回第 02 篇按你的平台修 PATH（macOS/Linux 的本机安装在 ~/.local/bin）。
第二步：进会话，跑体检
bash
claude进去后敲：
text
/doctor预期：弹出一份诊断面板，逐项列出安装健康状况、设置文件是否有效（无效的键 / schema 错误会被标红）、MCP server 配置、上下文使用情况。每项都没报错 = 你的配置是干净的。 要是某项被标了问题，按 f 把这份报告发给 Claude，让它陪你一条条解。
第三步：确认「当前用的是哪套凭证」
接着敲：
text
/status预期：显示当前活跃的身份验证方式。如果你是订阅用户，这里应该显示订阅（OAuth），而不是某个 API key。 万一显示在用 API key、跟你预期不符——恭喜你提前抓到了开头那个坑，去 shell 配置文件里 unset ANTHROPIC_API_KEY 并删掉那行 export。
第四步（可选）：体验一次干净配置对照
想感受第 07 节那招，开一个啥都不加载的干净会话：
bash
cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude预期：启动后这个会话没有你平时的任何 CLAUDE.md、自定义命令、MCP server（在里头敲 /memory、/mcp 会发现是空的）。这就是你日后排查「是不是我配置惹的祸」时的对照基准。注意：Linux / Windows 上它会让你重新登录（凭证存在配置目录下），macOS 因为凭证在 Keychain 里会自动带过来。玩完正常退出即可，这个临时目录不影响你真实的 ~/.claude。
跑通这四步，你就把**「体检 → 看凭证 → 起干净会话对照」**这条排查主干道亲手走了一遍。以后真出问题，照这个顺序来，比慌慌张张瞎试强太多了。
💡 一句话总结：动手把
claude --version→/doctor→/status→ 干净会话 这条体检链走一遍；记住「/doctor指方向、/status看凭证」，九成新手问题在这一步就现了原形。
09 小结
这一篇给你建了一套**「不靠猜、按流程」的排查框架**——从「先分诊属于哪一类」到「该敲哪个命令」，再到最刁钻问题的两个杀手锏。
把核心串起来回顾：
| 你的处境 | 排查动作 | 关键点 |
|---|---|---|
| 不知道问题属于哪类 | 对症状路由表 + /doctor | 先分诊再下手，别瞎试 |
| 反复登录 / 组织被禁用 | /status 看凭证 | 多半是残留 ANTHROPIC_API_KEY 压过订阅 |
| 设置 / hook / MCP 没生效 | /context、/hooks、/mcp | 查「实际加载了啥」；当心大小写和覆盖 |
| 卡顿 / 高内存 / 搜索失灵 | /compact + 重启 / 换 ripgrep | 多半是上下文太满或环境小问题 |
蹦 API Error 红字 | 先分「服务器 / 额度 / 你的请求」 | 5xx 看状态页、limit 等重置、too long 精简 |
| 怪问题定位不到 | --debug + 干净配置对照 | 看实时日志 + 二分法砍变量 |
你现在应该能： 遇到任何 Claude Code 的毛病，不再对着报错干慌——先用症状路由表认清这是哪一类，敲 /doctor 体检指方向、/status 看凭证；按类别（安装 / 认证 / 配置 / 性能 / 报错）对症下药；实在刁钻就上 --debug 看日志、用干净配置对照法把根因二分出来；真搞不定就 /feedback 上报。这套流程练成肌肉记忆，你就从「一报错就懵」升级成「一报错就知道该往哪查」了。
到这儿，从「装上」到「用顺」再到「出问题怎么救」，整套实操你都过了一遍。剩下的，就是把这一路冒出来的术语彻底捋清楚。
下一篇 52「术语表（小白友好）」——这一路读下来，CLAUDE.md、上下文窗口、MCP、Subagent、Hook、检查点、auto-compact……几十个名词在你脑子里来回飞。下一篇给你做一份小白友好的术语表：每个词一句话说人话、配一个最贴切的类比，按主题归好类，随时能翻、查完就懂。想想看：要是有人突然问你「token 和上下文窗口啥关系」，你现在能用一句话讲清吗？