6.18 Doctor诊断

claude doctor 命令是 Claude Code 的核心诊断工具，用于检查安装状态、排查问题并确保系统健康运行。

概述

/doctor 命令会对您的 Claude Code 安装进行全面的健康检查，使故障排除变得简单高效。该命令提供完整的诊断和修复工具，帮助维护健康的 Claude Code 安装环境，特别关注自动更新功能，这对于保持工具的最新特性和改进至关重要。

如何使用

您可以通过以下几种方式运行诊断命令：

# 直接运行 doctor 命令
claude doctor

# 使用 npx 运行
npx claude /doctor

# 在 Claude Code 会话中使用斜杠命令
/doctor

检查内容

Doctor 命令会执行全面的安装健康检查，重点关注 npm 权限。运行时会显示以下诊断信息：

• 安装类型 - 当前运行的安装类型（原生安装、npm、Homebrew 等）
• 版本信息 - 当前安装的版本号
• 安装路径 - Claude Code 二进制文件的路径
• 调用命令 - 用于启动的命令
• 配置安装方法 - 配置文件的安装方式
• 自动更新状态 - 自动更新是否启用
• 更新权限 - 是否有权限进行更新
• 搜索功能 - 验证搜索功能是否正常工作

诊断项目详情

Doctor 命令会检查以下各项：

安装状态检查

# 检查安装健康状态
claude doctor

# 输出示例
Installation Type: native
Version: 2.1.0
Path: ~/.local/bin/claude
Auto-updates: enabled
Update permissions: OK

MCP 服务器配置

检查 MCP 服务器配置是否存在错误。

设置文件验证

验证设置文件是否存在无效的 JSON 或类型错误。

快捷键配置

检查快捷键绑定配置是否存在问题。

上下文使用警告

• 大型 CLAUDE.md 文件警告
• 高 MCP token 使用量警告
• 无法访问的权限规则警告

插件和代理加载

检查插件和代理是否正确加载。

自动更新诊断

Doctor 命令会显示自动更新器禁用的原因（如果禁用）。这对于确保您的 Claude Code 保持最新版本非常重要。

# 查看自动更新状态
claude doctor

# 如果自动更新被禁用，会显示原因
Auto-updates: disabled
Reason: DISABLE_AUTOUPDATER environment variable is set

搜索功能诊断

如果搜索工具、@file 提及、自定义代理和自定义技能无法正常工作，Doctor 会检测到并提供解决方案：

# 安装系统 ripgrep（如果 Doctor 报告搜索问题）

# macOS (Homebrew)
brew install ripgrep

# Windows (winget)
winget install BurntSushi.ripgrep.MSVC

# Ubuntu/Debian
sudo apt install ripgrep

# Alpine Linux
apk add ripgrep

# Arch Linux
pacman -S ripgrep

然后在环境变量中设置 USE_BUILTIN_RIPGREP=0。

文档中的引用

Doctor 命令在多个官方文档中被引用：

• 成本指南：使用 claude doctor 查看当前版本和安装详情
• 故障排除指南：验证安装：claude doctor # 检查安装健康状态
• 设置指南：安装后运行 claude doctor 检查安装类型和版本
• 斜杠命令指南：将 /doctor 列为内置命令