Claude Code /doctor 详解：一键诊断你的开发环境

为什么需要 /doctor

用 Claude Code 开发，总会遇到一些莫名其妙的问题：

命令跑着跑着突然没反应了，是 API 断了还是 Token 没了？
MCP 服务器连不上，是配置写错了还是端口被占了？
搜索功能失灵了，ripgrep 到底装没装？
从 npm 升级到原生安装，旧版本残留会不会冲突？

这些问题一个个排查，费时费力。你得看环境变量、检查配置文件、测试网络连接、确认权限设置——每次都像在做侦探工作。

你需要一个一键诊断的工具。

这就是 /doctor。

/doctor 是什么

/doctor 是 Claude Code 的环境诊断命令。它会自动检测你的安装状态、配置、连接、权限等方方面面，然后告诉你哪些正常、哪些有问题、怎么修。

在交互模式下输入：

/doctor

或者在终端直接运行：

claude doctor

几秒钟后，你会看到一份完整的诊断报告，每一项检查都标记了状态：绿色通过、黄色警告、红色报错。

/doctor 检查了什么

1. 安装诊断

这是最基础也最重要的一组检查。/doctor 会检测：

安装类型：你是通过 npm 全局安装的、本地安装的、还是原生安装的？不同安装方式影响升级路径和权限管理。

Installation type: npm-global
Installation path: /usr/local/lib/node_modules/@anthropic-ai/claude-code
Version: 2.1.88

多重安装检测：如果你同时存在多个安装（比如 npm 全局装了一份，~/.claude/local 又装了一份，Homebrew 还装了一份），/doctor 会全部列出来并警告你。

这是很常见的问题——升级安装方式后忘了卸掉旧的，导致版本冲突或者跑到了错误的二进制文件。

自动更新状态：auto-updates 是否开启？如果是 npm 全局安装，是否有权限执行更新（有些系统需要 sudo）？

配置一致性：你实际的安装方式和 config 里记录的安装方式是否匹配。比如你已经切换到了原生安装，但配置还写着 npm-local，/doctor 会提醒你修正。

2. Ripgrep 状态

Claude Code 的搜索功能（Grep tool）依赖 ripgrep。/doctor 会检测它的运行状态：

Ripgrep: working (mode: builtin)

三种模式：

system：使用系统安装的 ripgrep
builtin：使用 Claude Code 自带的 ripgrep（npm 安装时）
embedded：编译进二进制的 ripgrep（原生安装时）

如果 ripgrep 不可用，搜索功能会完全失效。/doctor 会告诉你具体原因和修复方法。

3. 上下文用量警告

这组检查帮你发现上下文被意外吃掉的问题：

CLAUDE.md 文件大小：如果你的 CLAUDE.md 超过了 4 万字符，/doctor 会警告你。过大的 CLAUDE.md 每次对话都会加载，白白消耗上下文窗口。

Warning: Large CLAUDE.md files detected
  └ .claude/memory.md - 52,341 characters
  └ CLAUDE.md - 41,209 characters

Agent 描述过多：自定义 Agent 的描述会占用系统提示词空间。如果你的自定义 Agent 描述总量超过了 15,000 tokens，/doctor 会列出占用最多的 Agent，建议你精简。

MCP 工具过多：MCP 服务器注册的工具越多，系统提示词越长。阈值是 25,000 tokens。如果你连了好几个 MCP 服务器，每个注册了几十个工具，上下文就被工具描述吃掉了大半。

权限规则冲突：检查是否有被遮蔽的权限规则。比如你设了一个允许 npm test 的规则，但上面有一条更宽泛的拒绝规则覆盖了它，导致你的允许规则永远不会生效。

4. 沙箱状态

Claude Code 使用沙箱来隔离工具执行。/doctor 会检测：

当前平台是否支持沙箱
沙箱功能是否已启用
沙箱依赖是否就绪

如果沙箱不可用但你以为它在保护你，这就是个安全风险。/doctor 会明确告诉你实际状态。

5. MCP 服务器配置

如果你配置了 MCP 服务器，/doctor 会验证：

配置文件的 JSON 格式是否正确
服务器连接是否正常
有没有解析错误或启动失败

MCP 配置错误是常见问题——少了一个逗号、路径写错了、命令不存在，/doctor 都能发现。

6. 快捷键配置

检查 ~/.claude/keybindings.json 是否有效：

格式是否正确
是否有冲突的快捷键绑定
是否引用了不存在的操作

7. 环境变量验证

/doctor 会检查几个关键环境变量是否设置合理：

BASH_MAX_OUTPUT_LENGTH：Bash 工具的输出上限。设太大可能导致上下文溢出
TASK_MAX_OUTPUT_LENGTH：后台任务的输出上限
CLAUDE_CODE_MAX_OUTPUT_TOKENS：模型最大输出 Token 数。如果超过了模型支持的上限，会给出警告

8. 更新信息

/doctor 还会异步检查是否有新版本可用，显示当前版本和最新版本，以及更新渠道（stable、latest 等）。

什么时候该用 /doctor

环境刚搭好的时候：新装或升级后跑一次，确认一切正常。

出现莫名问题的时候：搜索不好使了、MCP 连不上了、响应变慢了——先跑 /doctor 看看有没有红色报错。

切换安装方式后：从 npm 升级到原生安装，或者反过来，跑一次检查是否有残留冲突。

团队排障的时候：让同事跑一次 /doctor，把输出发过来，比让他描述半天问题快多了。

一个真实排障场景

你升级到原生安装后，发现 Claude Code 启动变慢了，而且有些搜索返回空结果。

跑 /doctor，发现：

Warning: Multiple installations detected:
  └ native: ~/.local/bin/claude
  └ npm-global: /usr/local/lib/node_modules/@anthropic-ai/claude-code

Warning: Configuration mismatch:
  └ Running: native
  └ Configured: npm-local
  └ Fix: Update your install method in settings

Ripgrep: not working (mode: system)
  └ System ripgrep not found at expected path

问题一目了然：

旧的 npm 全局安装没删干净 — npm uninstall -g @anthropic-ai/claude-code
配置文件里的安装方式没更新 — 更新 settings
系统 ripgrep 丢了 — 重新安装或让 Claude Code 用内置版本

三个问题，三步修复，不用猜。

使用注意

信任目录

/doctor 运行时会跳过工作区信任对话框，并且会启动 MCP 服务器进行健康检查。所以只在你信任的目录下运行 claude doctor。在陌生的项目目录里跑可能会触发不受信任的 MCP 配置。

异步加载

部分检查是异步完成的。比如 MCP 工具的 Token 计数可能需要等 MCP 连接建立后才准确，可用版本检查需要网络请求。第一次看到的结果可能不完整，等几秒钟数据会补全。

写在最后

/doctor 是 Claude Code 里最容易被忽略的命令之一。

很多人遇到问题第一反应是上网搜、问 AI、翻文档。但其实大部分环境问题，/doctor 几秒钟就能给你答案——不只是告诉你”哪里有问题”，还告诉你”怎么修”。

养成习惯：环境有异常，先跑 /doctor。