偵錯您的設定
診斷為什麼 CLAUDE.md、settings、hooks、MCP servers 或 skills 沒有生效。使用 /context、/doctor、/hooks 和 /mcp 查看實際載入的內容。
當 Claude 忽略您的指令或您設定的功能沒有出現時，通常是因為檔案沒有載入、從您預期以外的位置載入，或被另一個檔案覆蓋。本指南展示如何檢查 Claude Code 實際載入的內容，以便您縮小範圍。
如需安裝、驗證和連線問題的協助，請改為參閱 Troubleshoot installation and login。
查看載入到 context 的內容
/context 命令顯示佔用目前工作階段 context 視窗的所有內容，按類別細分：系統提示、記憶檔案、skills、MCP tools 和對話訊息。首先執行它以確認您的 CLAUDE.md、規則或 skill 描述是否存在。
如需特定類別的詳細資訊，請使用專用命令進行後續操作：
| 命令 | 顯示 |
|---|---|
/memory |
載入了哪些 CLAUDE.md 和規則檔案，加上自動記憶項目 |
/skills |
來自專案、使用者和外掛程式來源的可用 skills |
/agents |
已設定的子代理及其設定 |
/hooks |
作用中的 hook 設定 |
/mcp |
已連線的 MCP servers 及其狀態 |
/permissions |
目前生效的已解析允許和拒絕規則 |
/doctor |
設定診斷：無效的鍵、schema 錯誤、安裝健康狀況 |
/debug [issue] |
啟用工作階段的偵錯日誌記錄，並提示 Claude 使用日誌輸出和設定路徑進行診斷 |
/status |
作用中的設定來源，包括是否啟用了受管設定 |
如果記憶檔案在 /memory 中遺失，請根據 CLAUDE.md 檔案如何載入 檢查其位置。子目錄 CLAUDE.md 檔案在 Claude 使用 Read 工具讀取該目錄中的檔案時按需載入，而不是在工作階段開始時載入。
如果 /memory 確認檔案已載入但 Claude 仍未遵循特定指令，問題可能在於指令的編寫方式，而不是是否載入。CLAUDE.md 適用於您會給新隊友的指導類型，例如專案慣例、建置命令和檔案所在位置。
當指令模糊到可以多種方式解釋時、當兩個檔案給出衝突的方向時，或當檔案變得足夠長以至於個別規則獲得較少關注時，遵循度會下降。編寫有效的指令 涵蓋保持遵循度高的特異性、大小和結構模式。
檢查已解析的設定
設定在受管、使用者、專案和本機範圍之間合併。受管設定在存在時始終優先。在其餘的設定中，較近的範圍會按本機、專案、使用者的順序覆蓋較廣的範圍。某些設定也可以由命令列旗標或 環境變數 設定，這些變數充當另一個覆蓋層。當設定似乎不適用時，您設定的值通常被另一個範圍或環境變數覆蓋。
執行 /doctor 以驗證您的設定檔案並顯示無效的鍵或 schema 錯誤。當 /doctor 報告問題時，按 f 將診斷報告傳送給 Claude，讓它與您一起逐步進行修正。
執行 /status 以查看哪些設定來源處於作用中，包括是否啟用了受管設定。若要瞭解給定鍵的哪個範圍優先，請參閱 範圍如何互動。
檢查 MCP servers
執行 /mcp 以查看每個已設定的 server、其連線狀態，以及您是否已為目前專案核准它。server 可以定義正確但仍然不提供 tools，原因有幾個常見的：
.mcp.json中的專案範圍 servers 需要一次性核准。如果提示被關閉，server 將保持停用狀態，直到您從/mcp核准它。- 啟動失敗的 server 在
/mcp中顯示為失敗。command或args中的相對檔案路徑是常見原因，因為它們相對於您啟動 Claude Code 的目錄而不是.mcp.json的位置進行解析。 - 顯示為已連線但列出零個 tools 的 server 已成功啟動但未返回 tool 清單。從
/mcp選擇 Reconnect。如果計數保持為零，執行claude --debug mcp以查看 server 的 stderr 輸出。
如需設定位置和範圍規則，請參閱 MCP。
檢查 hooks
執行 /hooks 以列出為目前工作階段註冊的每個 hook，按事件分組。如果您定義的 hook 沒有出現，則它未被讀取：hooks 位於設定檔案中的 "hooks" 鍵下，而不是在獨立檔案中。
如果 hook 出現但不觸發，通常是 matcher 的問題。matcher 欄位是一個使用 | 匹配多個 tool 名稱的單一字串，例如 "Edit|Write"。拼寫錯誤的 tool 名稱會無聲地失敗，因為 matcher 永遠不會匹配。陣列值是 schema 錯誤：Claude Code 顯示設定錯誤通知，/doctor 報告驗證失敗，hook 項目被刪除，因此不會出現在 /hooks 中。
對 settings.json 的編輯在短暫的檔案穩定延遲後在執行中的工作階段中生效。您不需要重新啟動。如果在保存後幾秒鐘 /hooks 仍顯示舊定義，請再次執行 /hooks 以重新整理檢視。
如果 /hooks 顯示 hook 但它仍然不觸發，下一步是即時監視 hook 評估。使用 claude --debug hooks 啟動工作階段並觸發 tool 呼叫。偵錯日誌記錄每個事件、檢查了哪些 matchers 以及 hook 的結束代碼和輸出。如需日誌格式，請參閱 Debug hooks，如需常見失敗模式，請參閱 hooks 疑難排解。
針對乾淨的設定進行測試
如果目標檢查無法隔離原因，或您的設定處於未知狀態，請與不從您常用設定載入任何內容的工作階段進行比較。將 CLAUDE_CONFIG_DIR 指向空目錄以略過 ~/.claude 下的所有內容，並從沒有 .claude 資料夾、.mcp.json 或 CLAUDE.md 的目錄啟動，以便也跳過專案設定。
cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude
乾淨的工作階段沒有使用者或專案設定、hooks、MCP servers、外掛程式或記憶。
- 如果您的組織部署受管設定，它們仍然適用，因為它們位於
~/.claude外的系統路徑 - 在 Linux 和 Windows 上，您將被提示再次登入，因為認證儲存在設定目錄下
- 在 macOS 上，認證在 Keychain 中，並會轉移到乾淨的工作階段
如果問題在此消失，原因在於您的真實 ~/.claude 或專案 .claude 檔案中的某處。一次一個地重新引入它們，方法是將檔案複製到臨時目錄或從您的專案啟動，以找到哪一個。如果它在乾淨的工作階段中持續存在，原因在於您的使用者和專案設定之外。執行 /status 以檢查是否啟用了受管設定，查找影響 Claude Code 的 環境變數，然後參閱 Troubleshooting。
檢查常見原因
大多數設定意外可以追溯到一小組位置和語法規則。在假設有 bug 之前檢查這些：
| 症狀 | 原因 | 修正 |
|---|---|---|
| Hook 永遠不觸發 | matcher 是 JSON 陣列而不是字串 |
使用單一字串搭配 | 來匹配多個 tools，例如 "Edit|Write"。請參閱 matcher 模式。 |
| Hook 永遠不觸發 | matcher 值是小寫，例如 "bash" |
匹配區分大小寫。Tool 名稱是大寫的：Bash、Edit、Write、Read。 |
| Hook 永遠不觸發 | Hooks 在獨立的 .claude/hooks.json 檔案中 |
沒有獨立的 hooks 檔案。在 settings.json 中的 "hooks" 鍵下定義 hooks。請參閱 hook 設定。 |
| 全域設定的 Permissions、hooks 或 env 被忽略 | 設定已新增到 ~/.claude.json |
~/.claude.json 保存應用程式狀態和 UI 切換。permissions、hooks 和 env 屬於 ~/.claude/settings.json。這是兩個不同的檔案。 |
settings.json 值似乎被忽略 |
相同的鍵在 settings.local.json 中設定 |
settings.local.json 覆蓋 settings.json，兩者都覆蓋 ~/.claude/settings.json。請參閱 settings 優先順序。 |
Skill 不出現在 /skills 中 |
Skill 檔案位於 .claude/skills/name.md 而不是在資料夾中 |
使用包含 SKILL.md 的資料夾：.claude/skills/name/SKILL.md。 |
Skill 出現在 /skills 中但 Claude 永遠不呼叫它 |
Skill 在其 frontmatter 中有 disable-model-invocation: true，或其描述與您表述請求的方式不符 |
檢查 /skills 中的徽章：「user-only」標籤表示 Claude 不會自動觸發它。請參閱 skill 呼叫。 |
子目錄 CLAUDE.md 指令似乎被忽略 |
子目錄檔案按需載入，而不是在工作階段開始時載入 | 它們在 Claude 使用 Read 工具讀取該目錄中的檔案時載入，而不是在啟動時，也不是在寫入或建立檔案時。請參閱 CLAUDE.md 檔案如何載入。 |
子代理忽略 CLAUDE.md 指令 |
子代理不總是繼承專案記憶 | 將關鍵規則放在代理檔案主體中，該主體成為子代理的系統提示。請參閱 子代理設定。 |
| 清理邏輯在工作階段結束時永遠不執行 | 未設定 SessionEnd hook |
在 settings.json 中新增 SessionEnd hook。請參閱 hook 事件清單。 |
.mcp.json 中的 MCP servers 永遠不載入 |
檔案位於 .claude/ 下或使用 Claude Desktop 的設定格式 |
專案 MCP 設定位於儲存庫根目錄為 .mcp.json，而不是在 .claude/ 內。請參閱 MCP 設定。 |
新增在 settings.json 中的 mcpServers 下的 MCP servers 永遠不出現 |
settings.json 不讀取 mcpServers 鍵 |
在儲存庫根目錄的 .mcp.json 中定義專案 servers，或執行 claude mcp add --scope user 以取得使用者範圍的 servers。請參閱 MCP 設定。 |
| 新增的專案 MCP server 但不出現 | 一次性核准提示被關閉 | 專案範圍 servers 需要核准。執行 /mcp 以查看狀態並核准。 |
| MCP server 從某些目錄啟動失敗 | command 或 args 使用相對檔案路徑 |
對本機指令碼使用絕對路徑。您 PATH 上的可執行檔（如 npx 或 uvx）可以按原樣使用。 |
| MCP server 啟動時沒有預期的環境變數 | 變數在 settings.json env 中，不會傳播到 MCP 子程序 |
改為在 .mcp.json 內設定每個 server 的 env。 |
Bash(rm *) 拒絕規則不阻止 /bin/rm 或 find -delete |
前綴規則匹配字面命令字串，而不是基礎可執行檔 | 為每個變體新增明確模式，或使用 PreToolUse hook 或 sandbox 以獲得硬保證。 |
相關資源
如需每個設定表面的完整參考，請參閱專用頁面：
.claude目錄參考：每個設定檔案位置及其讀取方式- Settings：優先順序和完整鍵清單
- Hooks 參考：事件名稱、承載和
--debug hooks輸出格式 - MCP：server 設定、核准和
/mcp輸出 - Troubleshoot installation and login：
command not found、PATH 和身份驗證問題 - Troubleshooting：效能、掛起和搜尋問題