它到底是什么

/doctor 是 Claude Code 的配置与安装诊断命令。官方文档对其的精确定义为："Configuration diagnostics: invalid keys, schema errors, installation health"（配置诊断：无效键、schema 错误、安装健康状态）。

执行后会扫描当前环境并输出颜色编码的检查报告，覆盖配置文件合法性、安装完整性、MCP 服务器状态等维度。若 Claude Code 连启动都无法完成，可在系统终端改用等价 CLI 命令 claude doctor。

怎么触发 / 怎么使用

1. 在 Claude Code 会话内运行

/doctor

2. 从系统终端运行（Claude Code 无法启动时）

claude doctor

3. 报告出现后请求引导式修复

查看报告后按下 f 键，/doctor 会将诊断报告发送给 Claude，由其逐项引导你完成修复。

监控 / 控制 / 键位

检查项

官方文档对 /doctor 的范围界定为三类（debug-your-config 页面原文："Configuration diagnostics: invalid keys, schema errors, installation health"）：

关于检查报告：官方仅提供上述三类范围定义，未公开 /doctor 报告的逐行字段、颜色编码或末尾汇总行格式。社区博客曾描述 ripgrep 可用性、context 占用、环境变量、keybinding 等额外检查项，但这些未见于官方文档，且 context window 各分类占用在官方文档中归属 /context 命令而非 /doctor，请以实际运行输出为准。

/doctor 报告问题后，按 f 键可将诊断报告发送给 Claude 引导修复（官方 debug-your-config 原文："When /doctor reports issues, press f to send the diagnostic report to Claude and have it walk through fixes with you."）。

分层诊断升级流（官方"从看到净"）

/doctor 很少单独使用——官方 debug-your-config 页把它放在一条由浅入深的协作流里：先确认配置"加载了没有"，再逐项专项查，最后用净环境隔离定位。当 CLAUDE.md、settings、hook、skill 或 MCP "似乎被忽略"时，按下面顺序往下走：

1. /context 先确认加载：官方原话是"Run it first"。它列出当前会话占用 context window 的全部内容（system prompt、memory 文件、skills、MCP 工具、对话消息）。先看你的 CLAUDE.md、规则或 skill 描述到底有没有出现——很多"不生效"其实是根本没加载。

2. 专项命令逐类深入（/context 看到某类异常后跟进对应命令）：

   命令	查什么
   /memory	哪些 CLAUDE.md、规则文件加载了，以及 auto-memory 条目
   /skills	来自 project / user / plugin 三种来源的可用 skill
   /agents	已配置的子 agent 及其设置
   /hooks	当前会话已注册的 hook（按事件分组）
   /mcp	已连接的 MCP 服务器及其状态
   /permissions	当前生效的 allow / deny 规则

   • 若 /memory 里缺某个文件:子目录 CLAUDE.md 是按需加载的——当 Claude 用 Read 工具读取该目录下某个文件时才加载，不在会话启动时加载。
   • 若 /memory 确认加载了但指令仍不被遵守:问题多半在指令怎么写(措辞含糊、两文件冲突、文件过长),而非是否加载。

3. /doctor 验配置合法性:跑 /doctor 校验配置文件、暴露 invalid keys 与 schema 错误;报告问题后按 f 把诊断交给 Claude 引导修复。再配合 /status 看哪些 settings 来源生效(含 managed settings)。

4. claude --safe-mode（v2.1.169 起,净配置):官方建议从这里开始净化排查。它启动一个禁用全部定制的会话——CLAUDE.md、skills、plugins、hooks、MCP 服务器、自定义命令与 agent 全部关掉;而认证、模型选择、内置工具、permissions 照常工作。若问题在 safe mode 下消失,说明原因就在被禁的那几类里,再用上面的专项命令逐个定位。注意:组织下发的 managed settings 仍部分生效(policy 配置的 hook、status line 即便 safe mode 也会跑)。

5. CLAUDE_CONFIG_DIR 全净环境(safe mode 仍复现 / 怀疑 settings 本身时):把 CLAUDE_CONFIG_DIR 指向一个空目录以绕过 ~/.claude 下的一切,并从一个没有 .claude 目录、.mcp.json、CLAUDE.md 的目录启动,使项目级配置也被跳过:

   cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude
   

   复制

   这个净会话没有任何 user / project 的 settings、hooks、MCP、plugins 或 memory。几点须知:

   • managed settings 仍生效(它们位于 ~/.claude 之外的系统路径);
   • Linux/Windows 上会要求重新登录(凭据存在配置目录下);macOS 凭据在 Keychain,会带到净会话;
   • 若问题在此消失:原因就在你真实的 ~/.claude 或项目 .claude 文件里——把它们逐个拷回临时目录(或逐步从你的项目启动)即可定位是哪一个;若仍复现:原因在 user/project 配置之外,用 /status 看 managed settings,再排查影响 Claude Code 的环境变量。

   （以上全节来源:官方 debug-your-config 页"See what loaded into context""Test against a clean configuration"两节,逐字核实。）

官方 common-causes 精选表（症状 → 原因 → 修复）

官方 debug-your-config 页有一张"Check common causes"表,把大多数"配置惊喜"归到一小撮位置与语法规则。精选与 /doctor 排查最相关的若干条(全部逐字核实自该表):

（来源:官方 debug-your-config 页"Check common causes"表,逐条核实。）

跟同类原语对比

/doctor 属于配置诊断命令族。官方文档在 "Debug your configuration" 页面将以下命令并列介绍：

经典使用场景

• 安装或升级后验证：确认环境配置完整，安装路径与版本符合预期
• 配置不生效时的第一步：CLAUDE.md、settings、hook 或 skill 似乎被忽略时，先跑 /doctor 排除 schema 错误和无效键，再用 /memory / /hooks 等专项命令深入排查
• MCP 服务器异常：服务器无法连接时，/doctor 可快速定位是配置格式问题还是启动失败
• CLI 无法启动时：从系统终端运行 claude doctor，无需进入交互会话即可获取诊断报告

常见坑

1. ~/.claude.json 与 ~/.claude/settings.json 混淆：/doctor 检查的是 ~/.claude/settings.json（包含 permissions、hooks、env 等）。~/.claude.json 是另一个文件，存放 UI 状态和 app 开关。将 permissions 或 hooks 误写入 ~/.claude.json 时，/doctor 不会报告该文件内容，配置也会静默失效。（来源：官方 debug-your-config 页面"common causes"表格）

2. Hook matcher 为数组时 /doctor 报 schema 错误：hook 的 matcher 字段必须是用 | 分隔的单个字符串（如 "Edit|Write"），不能是 JSON 数组。数组格式会导致 /doctor 输出 schema 验证失败，该 hook 也会被静默丢弃，不出现在 /hooks 列表中。（来源：官方文档）

来源

• Debug your configuration — Claude Code Docs
• Commands — Claude Code Docs
• Claude Code /doctor: Fix Setup Issues in 30 Seconds — Vincent's Blog
• /doctor in Claude Code — wmedia.es