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 條評論

登入 後參與評論

還沒有評論,來搶沙發~