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

图:本站根据 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 通道版本后再试。
相关教程
- /guides/claude-code-common-errors:Claude Code 常见报错码与连接异常排查汇总
- /guides/claude-md-auto-update-how-to-update:
CLAUDE.md维护更新与自动记忆区别 - /guides/claude-code-changelog-release-notes-how-to-check:查看更新记录与不同安装方式的升级命令
- /guides/claude-code-mcp-setup:Claude Code MCP 服务器安装与排错
参考资料
- Claude Code 官方文档:Troubleshooting — https://code.claude.com/docs/en/troubleshooting
- Claude Code 官方文档:How Claude remembers your project — https://code.claude.com/docs/en/memory
0 条评论
还没有评论,来抢沙发~