# 51 · 常见问题排查（FAQ / Troubleshooting）

> 📚 **系列导航**：上一篇 [50 反模式：常见的错误用法](50-anti-patterns.md) 把那些「看着没错、其实在挖坑」的用法挨个点名。这一篇接着聊排查——**当 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](https://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 卡顿一个道理——**先收拾「工作台」，别急着重装。**

### 卡顿 / 高内存：先收拾上下文

官方给的处理顺序很务实：

1. 定期用 **`/compact`** 压缩上下文（把对话整理成一页要点，详见第 19 篇）。
2. **在主要任务之间关掉再重启** Claude Code。
3. 把大型构建目录加进 `.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](https://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 和上下文窗口啥关系」，你现在能用一句话讲清吗？
