疑難排解、安全與資源管理

24.1　遇到問題，先跑這一招：/doctor

用久了難免遇到「它今天怪怪的」「指令好像沒反應」這種狀況。先別急著重灌、也別急著放棄——九成以上的怪事，第一步動作都一樣：讓 Claude Code 自己做一次健康檢查。

這就像人覺得不舒服先量個體溫。/doctor 是 Claude Code 內建的「自我體檢」，一次幫你看：安裝有沒有壞、設定有沒有寫錯、外接的工具（MCP）通不通、目前對話的上下文用量（佔了多少百分比、還剩多少）。它會把哪裡不對勁標出來，你照著它說的修就好，不用自己猜。

下面用三個步驟帶你做。請依你「現在卡在哪」對號入座：能進得去 Claude，就用第①步；連開都開不起來，跳第②步；懷疑是某個外掛在搗蛋，看第③步。

1. 1
   ✋動手做

   能進 Claude → 在裡面打 /doctor

   如果你還能正常啟動 Claude Code（畫面有出現它的對話框），直接在輸入列打斜線指令 /doctor 按 Enter。它會跑一輪體檢，列出安裝、設定、MCP 連線、上下文用量的狀況。

   /doctor

   複製

   ✅ 預期會看到

   # 它會列出一份健檢清單，大致像這樣（實際項目依版本略有不同）：
   Installation    ✔ healthy
   Config          ✔ valid
   MCP servers     ✔ all reachable
   Context usage   42% used
   # 有問題的項目會標成 ✘ 或 warning，並附上修正建議

   複製

   想知道原理：/doctor 說「Config ✔ valid」，到底在驗哪份檔案？

   Claude Code 其實有兩份長得很像、卻管完全不同東西的設定檔，搞混是很多「明明改了設定，怎麼沒用」的根源。~/.claude/settings.json（以及專案層級的 .claude/settings.json）管的是權限、hook、環境變數這類行為設定；~/.claude.json（在你的使用者根目錄，注意名字裡沒有 .claude/ 那層資料夾）存的則是應用程式狀態——像是一些介面開關、MCP 連線紀錄這類東西。最容易踩的雷是把 hooks、env、permissions 這類欄位寫進 ~/.claude.json：不會報任何錯誤，但也完全不會生效，因為那份檔案根本不認得這些欄位。真的分不清楚，記一個口訣：想調整它的行為，用 settings.json；其他大小事才輪得到 .claude.json。

   連帶一個常見的追加雷區：如果你是透過 .mcp.json 接外部工具（第 9 章），想讓某個 MCP 伺服器拿到專屬的環境變數，那組 env 得寫進 .mcp.json 那個伺服器自己的 env 欄位——寫進 settings.json 的 env 對 MCP 子行程完全沒有作用，這是兩條互不相通的環境變數注入路徑，別假設「反正都是 env，應該共用」。若是團隊或組織環境，另外還有一份優先權更高的「受管理設定」（managed settings，通常由 IT 統一部署），衝突時一律它說了算。

2. 2
   ✋動手做

   claude 根本開不起來 → 在終端機打 claude doctor

   如果打 claude 連畫面都跑不出來、或一開就閃退，那就沒辦法用「裡面」的 /doctor 了。改成在終端機直接打 claude doctor（注意：這是兩個字、中間有空格，不是斜線指令）。它一樣會做體檢，告訴你是哪裡裝壞了。

   claude doctor

   複製
3. 3
   ✋動手做

   懷疑某個外掛在搗蛋 → 用 claude --safe-mode 開

   有時候裝了某個外掛（plugin）、某個外接工具（MCP）或某條自動化規則（hook）之後，Claude Code 才開始出怪。想知道是不是它們害的，就用安全模式啟動：它會暫時略過那些外加的東西，只跑最乾淨的核心。如果安全模式下一切正常，那兇手就是你某個外加設定，再回頭一個一個排查。

   claude --safe-mode

   複製

   想知道原理：安全模式到底「略過」了哪些東西？

   安全模式（--safe-mode）啟動時，會把你自己加上去的那一層設定整個暫時關掉，只跑 Claude Code 最原始的核心。最常見的兇手是這五類：① 你寫的 CLAUDE.md 規則（專案記憶）；② 你裝的技能 skills；③ 你裝的外掛 plugin；④ 你接的外部工具 MCP；⑤ 你設的自動化 hook；除了這些，你自訂的指令與代理人（custom commands、agents）也會一併停用。換句話說，凡是「你自訂的」都先拿掉。所以如果安全模式下就正常了，問題就出在你某一項自訂設定上——接著你就能用刪去法，把它們一個一個開回來，找出真正的兇手。安全模式只是「排查用」的暫時狀態，不會刪掉你任何設定，關掉它再正常啟動，東西都還在。

# 從一個乾淨資料夾、乾淨設定目錄啟動，排除所有使用者層級設定
cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude

💡 建議執行：對不上症狀時，讓它幫你開回報

翻遍下面 24.2 的表還是對不到你的狀況？在 Claude 裡打 /feedback，它會把你的對話記錄與描述送給 Anthropic，並順手幫你開一個預填好的 GitHub issue（碰到它「明顯做錯」的 bug，則用 /bug）。

# 找不到對應症狀、或想直接回報問題時：
/feedback     # 送出回饋，並可開好預填的 GitHub issue
/bug          # 回報明顯的程式錯誤

24.2　常見問題與解法

下面這張表收了新手最常撞到的幾種狀況。左邊是你看到的「症狀」，右邊是「為什麼會這樣、怎麼解」。先在左欄找跟你最像的那一列，再照右欄做。如果你是 🍎 Mac 或 🪟 Windows 使用者，有幾列特別標了你的系統，看清楚再動手。

24.3　安全須知：最重要的一章，請務必讀完

前面教的都是「怎麼讓它做更多事」，這一節相反：教你怎麼守住底線、不讓它闖禍。Claude Code 很強，但「強」這件事是雙面刃——它能照你說的改一堆檔案，也就代表如果你沒看清楚就點頭，它可能照著一個壞指示把東西改壞。好消息是：只要記住一個核心原則、養成三個習慣，你就能放心地用。這節份量稍多，但每一段都關係到你的檔案安全，請慢慢讀完。

24.4　遇到打不通的關，去哪裡回報與求助

自己試過、/doctor 也跑過，還是卡住怎麼辦？別一個人硬撐。Claude Code 背後有官方團隊和一大群同好，回報問題、找人求助都有正規管道。下面四個入口，依你的情況挑著用。

24.5　持續學習：最好的老師，就在你手邊

學到這裡，這份教學要陪你的部分告一段落了——但你的路才剛開始。好消息是：以後想學新功能、想查怎麼用，你不一定得翻文件或上網問人。最好的老師，其實就住在你的終端機裡。