Claude Code /doctor 怎么用:环境故障自检与 prompt-audit 指令冲突体检指南

遇到 Claude Code 升级后版本号不变、settings.json 不生效、搜文件极慢或者老项目总是无视某条规范时,先别急着重装。本文按官方文档讲清 claude doctor 环境自检与 /doctor prompt-audit 指令体检各自查什么及如何安全修复。

NNathaniel bigo··原创首发·AI 辅助撰写
9 分钟读完
资料核对于 2026-11-18 · 依据官方文档与公开资料整理 免费账号 账号

结论先说

  1. 进不去交互界面时在系统终端敲 claude doctor,进得去时直接敲 /doctor:它能在几秒内把安装方式、多版本路径冲突、自动更新状态、ripgrep 搜索组件和配置文件语法过一遍筛子。
  2. 「升级后版本没变」九成靠它破案:doctor 会直接打出当前实际运行的二进制绝对路径,帮你抓出「以前用 npm 装了一份残留,遮挡了新装的原生版本」。
  3. 觉得模型变笨或不守规矩时,跑 /doctor prompt-audit:它会全面扫描你的 CLAUDE.md、规则目录、技能与子代理定义,找出互相冲突的指令和早已删除的幽灵文件路径。
  4. prompt-audit 默认绝对安全:只出体检报告与修改建议,在你明确点头确认之前,不会擅自改写任何一份本地或仓库文件。

claude doctor 常规自检与指令体检对比

图:本站根据 Claude Code 官方文档 Troubleshooting 与 Memory 整理的示意图

本文根据 Claude Code 官方文档《Troubleshooting》《How Claude remembers your project》整理,核对日期 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 Anthropic 官方网站。

适用于谁

  • 搜「claude doctor 怎么用」「claude code 自检」「doctor prompt-audit」的开发者;
  • 明明跑了更新命令却还是旧版本、配了 JSON 权限却不拦截、或者某个 MCP 服务悄悄断连找不到日志的人;
  • 团队仓库里的 CLAUDE.md 和 .claude/rules/ 攒了大半年,感觉模型越来越「不听话」,想一次性揪出过期或自相矛盾条款的人。

如果你遇到的是明确的登录 403 或网络报错码,也可以对照汇总篇 /guides/claude-code-common-errors;本文专门讲官方内置的两把系统级听诊器怎么用。

一、常规自检(claude doctor / /doctor)重点看哪四行输出

在项目根目录打开终端直接运行 claude doctor(或在会话内输入 /doctor),不要只看顶部的绿色对勾,排障时重点核对下面四个模块:

1. 安装来源与可执行文件路径(Installation & PATH)

很多老用户早期用 npm install -g 装过旧版,后来又用官方推荐的原生脚本装了新版(升级渠道差异见 /guides/claude-code-changelog-release-notes-how-to-check)。如果系统 PATH 里旧的 npm 全局目录排在 ~/.local/bin 前面,你每次敲 claude 启动的其实一直是半年前的旧壳子。看一眼 doctor 打印出的当前路径与告警,删掉多余残留副本即可根治。

2. 配置文件语法解析状态(Settings Validation)

手改 ~/.claude/settings.json 或项目 .claude/settings.local.json 时,只要在最后一行多打了一个尾随逗号(Trailing comma),整份配置可能就会解析失败回退默认——表面上终端能正常聊天,但你配的 deny 安全规则全没生效。/doctor 会直接标出哪一份 JSON 文件的哪一行格式非法。

3. 代码检索加速组件(Search / ripgrep)

在大仓库里如果发现 Claude 每次找函数都要卡十几秒甚至漏结果,检查 doctor 输出里的搜索工具状态:确认内置或系统级 rg(ripgrep)是否有可执行权限(在部分企业安全软件拦截未知内嵌二进制的电脑上,可通过环境变量切换改用系统包管理器安装的 rg)。

4. 已注册 MCP 服务器健康度

如果某个本地或远程 MCP 工具突然消失(基础配置见 /guides/claude-code-mcp-setup),运行 /doctor 配合 /mcp 可以快速定位是启动命令找不到(比如切换了 Node 版本导致全局包路径变了)还是握手超时。

遇到异常先跑哪条诊断命令排查

图:本站根据 Claude Code 官方文档 Troubleshooting 整理的示意图

二、进阶利器:/doctor prompt-audit 给项目规则做大扫除

软件项目迭代半年后,仓库里的指令文件往往会出现三种典型的「慢性腐化」(维护背景见 /guides/claude-md-auto-update-how-to-update):

  • 幽灵路径引用:三个月前把 src/legacy-auth/ 删掉了,但 CLAUDE.md 里还写着「改鉴权前先读 src/legacy-auth/index.ts」,导致模型每次开局先白跑一次报错读取;
  • 跨文件规则打架:用户全局 ~/.claude/CLAUDE.md 写着「所有脚本默认用 pnpm」,项目 .claude/rules/ci.md 写着「必须统一用 yarn」,两条指令同时拼进上下文让模型左右为难;
  • 针对旧代模型写的过时补丁:以前为了哄早期弱模型写的冗长死板格式限制,反而束缚了新模型的工具规划能力。

在目标仓库启动会话后直接输入:

text
/doctor prompt-audit

Claude Code 会自动遍历检查 CLAUDE.md、CLAUDE.local.md、AGENTS.md 以及 .claude/ 和 ~/.claude/ 下的规则、技能、命令与子代理文件,生成一份结构化的诊断报告:逐条列出哪里有冲突、哪个文件路径已经不存在、哪段话过于含糊无法验证,并给出精简改写草案。你审阅同意后,再让它落盘提交 Git 即可。

平时保持干净精简的指令底座,不仅能提升首次改码准确率,还能省下每次会话白白加载废话消耗的订阅配额;个人或团队核对官方 Claude Code 订阅档位说明时,也可参考 /chongzhi/claude-code。

常见问题

Q:向技术支持或社区提问题单时,怎么安全提供环境信息?

优先贴 claude doctor 输出的版本号、操作系统、安装类型与错误摘要(记得先检查并抹掉内部私有域名或路径中的敏感用户名),比单纯截一张对话框报错图定位快得多;遇到客户端界面异常还可以在会话里使用 /bug 按官方指引提交反馈。

Q:为什么我敲 /doctor prompt-audit 提示子参数不识别?

该体检子功能随较新的 Claude Code 版本推出。如果提示不支持,先按 claude doctor 给出的安装方式把客户端升级到最新 latest 通道版本后再试。

相关教程

参考资料

  • Claude Code 官方文档:Troubleshooting — https://code.claude.com/docs/en/troubleshooting
  • Claude Code 官方文档:How Claude remembers your project — https://code.claude.com/docs/en/memory

Nathaniel 的更多内容

  1. 01

    LangGraph 流式输出(Streaming)详解:逐字 Token 流、节点进度与自定义事件写法

    多步智能体如果等全部节点跑完才返回,网页前端就会白屏干等十几秒。本文按 LangGraph 官方文档讲清 updates、messages、custom 与 values 四种 stream_mode 的区别,以及组合订阅逐字打字机输出加工具内部实时进度的完整代码。

    其他 AI 工具0
  2. 02

    LangGraph 持久化与长期记忆怎么配:Checkpointer、Store 与 PostgreSQL 实战

    在生产环境跑 LangGraph,单靠 InMemorySaver 一重启就会丢失全部对话。本文按官方文档讲清线程内短期检查点(Checkpointer)与跨线程长期记忆(Store)的分工,以及用 langgraph-checkpoint-postgres 对接 PostgreSQL 的完整步骤。

    其他 AI 工具0
  3. 03

    LangGraph 多智能体怎么写:Supervisor 主管包与 Subgraph 隔离子图实战

    在 LangGraph 里把单个图扩展成多智能体协作有两条官方路线:快速原型用预置包 langgraph-supervisor,大型生产系统用原生子图(Subgraph)嵌套。本文讲清两种写法的完整代码、私有状态隔离防 Token 膨胀技巧以及检查点传播规则。

    其他 AI 工具0
  4. 04

    LangGraph 人工介入审批怎么写:interrupt 暂停图运行与 Command 恢复实战

    企业之所以选 LangGraph,很大程度看中它能安全挂起等待人工审批(Human-in-the-Loop)。本文按官方最新规范讲清 interrupt() 动态暂停、Checkpointer 必备条件、Command(resume=...) 恢复执行,以及防止副作用重复运行的重入规则。

    其他 AI 工具0
  5. 05

    多 Agent 协作平台怎么选:Dify、扣子(Coze)、n8n 与 LangGraph 多智能体机制对比

    搜「多agent协作平台」时,Dify、扣子、n8n 和 LangGraph 都宣称支持多智能体,但底层的调度方式完全不同。本文跳过基础安装,专门从多 Agent 角色跳转、子代理工具调用、上下文隔离与私有化部署四个维度帮你一次选准。

    其他 AI 工具0
  6. 06

    企业微信有官方 MCP 和 CLI 吗:@wecom/cli 安装初始化、长连接机器人与接入教程

    搜「企业 微信 有 mcp 吗」不用再东拼西凑民间群机器人脚本了:企业微信官方已推出 @wecom/cli 命令行工具并内置 stdio 模式的 MCP Server。本文按官方开发者文档讲清安装、智能机器人长连接初始化、业务命令与接入 Claude Code 步骤。

    Claude其他 AI 工具0

同产品的其他教程

  1. 01

    MCP 收费吗:开源协议免费边界、第三方 API 账单与隐形 Token 开销说明

    搜「mcp 收费 吗」的人常担心装多了插件会被扣费。MCP(模型上下文协议)本身和官方 SDK 采用 MIT 协议完全免费;实际使用中可能产生费用的只有两处:挂载过多工具占用的大模型上下文 Token,以及部分外部商业数据源自带的 API 套餐。

    Claude其他 AI 工具0
  2. 02

    MCP 协议最新版本更新了什么:无状态架构、OAuth 2.1、结构化输出与异步 Tasks 详解

    搜「mcp 重大 更新」「mcp 协议 更新」想补齐规范演进脉络?本文对照 modelcontextprotocol.io 官方规范更新日志,梳理从 Streamable HTTP 到无状态优先架构、OAuth 2.1 资源服务器、Elicitation 交互补参与异步 Tasks 扩展的核心变化。

    Claude其他 AI 工具0
  3. 03

    A2A 和 MCP 有什么区别:工具连接协议与智能体通信协议的边界和配合

    很多人问「有了 MCP 为什么还要出 A2A,两者是不是二选一的竞争关系」。两份官方规范都明确写明它们是上下互补关系:MCP 负责给单个智能体挂载工具与数据源,A2A 负责让多个独立黑盒智能体跨团队、跨框架互相派单协作。

    Claude其他 AI 工具0
  4. 04

    LangGraph 怎么使用 MCP:用 langchain-mcp-adapters 接入本地与远程工具

    想让自建的 LangGraph 状态图直接调用现成的 MCP 服务器,官方标准方案是安装 langchain-mcp-adapters 并使用 MultiServerMCPClient。本文讲清 stdio 与 streamable_http 两种配置写法、异步图运行及按节点分工具技巧。

    Claude其他 AI 工具0
  5. 05

    LangGraph 入门教程:Python 安装、核心概念与跑通第一个状态图智能体

    面向搜「python 安装 langgraph」和「langgraph 中文 文档」的初学者:本文按 LangChain 官方最新 Graph API 规范,讲清安装步骤、State/Node/Edge 四大概念,并从零写出第一个带工具调用循环的 StateGraph。

    Claude其他 AI 工具0
  6. 06

    Claude Agent SDK 子代理怎么写:AgentDefinition 配置、权限收敛与 Python/TS 示例

    在 Python 或 TypeScript 里用 Claude Agent SDK 编排多角色协作,核心是配置 ClaudeAgentOptions 的 agents 字段与 AgentDefinition。本文讲清必开的 Agent 委派权限、工具收敛、模型分级与完整代码示例。

    Claude0

0 条评论

登录 后参与评论

还没有评论,来抢沙发~