排除 mod 的故障
找出 Claude Code mod 為什麼沒有作用：將症狀或訊息與其原因相符，查詢拒絕訊息，並閱讀偵錯日誌。
當 mod 的模組或其中一個 hooks 失敗時，Claude Code 會跳過它，工作階段會繼續進行，因此損壞的 mod 看起來可能像沒有作用的 mod。首先檢查 Claude Code 從您的 mod 讀取了什麼，以及它在哪裡報告問題，然後找到您遇到的症狀或訊息。
找出 mod 為什麼沒有作用
當 mod 沒有作用時，兩項檢查可以找到原因：Claude Code 從 mod 的檔案讀取的內容，以及它在跳過某些內容時寫入的行。對於第一項，在您的 shell 中執行 claude plugin validate，並使用 mod 的目錄，例如 claude plugin validate ./first-mod。它會捕捉拼寫錯誤的事件、不良的資訊清單和 Claude Code 無法讀取的模組，而無需啟動工作階段。
當模組未載入、hook 被跳過或另一個 mod 拒絕您的 mod 時，Claude Code 會寫入一行，其中命名您的 mod。您讀取該行的位置取決於工作階段：
- 熱重新載入 plugin 目錄的工作階段：文字記錄中的暗淡行。這是您使用
--plugin-dir啟動的互動式工作階段，或您為 Claude 編寫的 mod 啟用熱重新載入的工作階段。 - 任何其他互動式工作階段，例如執行您從市場安裝的 mod 的工作階段：偵錯日誌只有。若要取得一個，請使用
claude --debug啟動工作階段。 claude -p執行--plugin-dir：stderr，採用預設文字輸出格式。另一個 mod 的拒絕只會進入偵錯日誌。
檢查 mod 是否可以載入
若要檢查您的設定是否允許 mod 載入，而無需安裝一個，請在您的 shell 中執行 claude plugin test，從不包含 mod 的目錄執行。您不需要工作階段。它列印的訊息會告訴您狀態：
| 訊息包含 | 這表示什麼 |
|---|---|
no hooks module to load |
Mod 可以載入。該命令在此目錄中找不到要測試的 mod。 |
hooks modules are turned off here |
設定正在阻止您的 mod：您自己設定中的 disableAllHooks，或您的組織的原則 |
hooks modules are turned off in this process |
Anthropic 已遠端關閉已安裝的 mod。您機器上的任何設定都無法將其重新開啟。 |
組織也可以設定 allowManagedModsOnly 以僅允許其自己的 mod，此命令不會報告。在這種情況下，您安裝的 mod 不會載入，並且訊息會說明原因。
mod 不載入
mod 新增的任何內容都不會出現：沒有命令、沒有繪圖，也沒有行為變化。
您的版本早於 2.1.287
claude --version 列印的版本早於 2.1.287。您的版本早於預設開啟 mod 的時間。
`mods active` 行不命名 mod
mod 新增的任何內容都不會出現，並且 /plugin 中的 mods active 行不命名它。hooks 模組未載入。當 Claude Code 拒絕它時，偵錯日誌有一行以 hooks module、mod 的名稱和 not loaded: 開頭，例如 hooks module first-mod@inline not loaded: disableAllHooks in managed settings，用於使用 --plugin-dir 載入的 mod。
讀取冒號後的原因。拒絕訊息部分列出每一個。如果日誌沒有這樣的行，請逐一檢查此群組中的其他項目。
`claude -p` 執行列印 `hooks module not loaded`
該行以 mod 的名稱開頭，並進入 stderr。hooks 模組被拒絕。非互動式執行沒有文字記錄，因此訊息進入 stderr。
讀取冒號後的原因。拒絕訊息部分列出每一個。
拒絕訊息
每一個都遵循偵錯日誌中的 hooks module、mod 的名稱和 not loaded:。
| 訊息開頭為 | 這表示什麼 |
|---|---|
hooks modules are turned off for installed plugins in this process |
Anthropic 已遠端關閉已安裝的 mod。您機器上的任何設定都無法將其重新開啟。 |
disableAllHooks in managed settings |
您的組織關閉了已安裝 plugin 的 hooks |
only managed plugins and built-in plugins run |
設定了 allowManagedHooksOnly，或在受管設定以外的設定檔中設定了 disableAllHooks |
installed plugins that are not managed load no hooks module in this mode (--bare) |
您使用 --bare 啟動了 Claude Code |
another plugin of that name loads first |
兩個 plugin 共享一個名稱。使用受管的或首先載入的。 |
來自內建防護的訊息
在具有受管設定的機器上，或對於使用 Team 或 Enterprise 方案登入的使用者，內建防護可以拒絕 mod 或其中一個答案。每條訊息都命名您的組織管理員設定以變更規則的選項。
| 訊息包含 | 這表示什麼 | 它出現在哪裡 |
|---|---|---|
mods are limited to your organization's by policy (allowManagedModsOnly) |
您的組織僅允許其自己的 mod，因此您的 mod 未被載入 | 偵錯日誌，以及熱重新載入 plugin 目錄的工作階段中的文字記錄 |
tried to lift a deny rule in your settings |
您的 mod 的 tool.check hook 批准了 deny 規則拒絕的呼叫。呼叫保持被拒絕。 |
文字記錄和偵錯日誌，每個工作階段中的每個 mod 一次。在 claude -p 執行中，僅偵錯日誌。 |
the deny rules in your settings could not be checked for this call, so it is refused |
防護在檢查 mod 批准的呼叫時失敗，因此它拒絕了呼叫 | Claude 為被拒絕的呼叫讀取的原因 |
`validate` 通過且不列出 `hooks` 行
hooks/hooks.json 沒有 modules 鍵，或鍵拼寫錯誤。
新增 "modules": ["./register.js"]。
`hooks module did not load`
該行以 mod 的名稱開頭，然後是 hooks module did not load: 和一個原因，當問題在您的程式碼中時，該原因會給出檔案和行。Claude Code 無法載入模組，例如因為其頂級程式碼拋出。
修復原因命名的錯誤。
`options do not fit plugin.json userConfig`
該行以 mod 的名稱開頭，然後是 hooks module did not load: options do not fit plugin.json userConfig: 和一個原因。選項不符合其 userConfig 欄位，例如高於欄位 max 的數字，或必填欄位沒有值。
設定或變更值。該行的末尾命名其在 settings.json 中的 pluginConfigs 項目。
沒有 mod 在您首次開啟的目錄中載入
您尚未回答該目錄的信任提示。
使用 claude 在該目錄中啟動互動式工作階段，並接受它開啟的信任提示。
沒有已安裝的 plugin 載入
您使用 --safe-mode 啟動了 Claude Code。
啟動時不使用該旗標。
hook 被跳過或 mod 被卸載
mod 已載入，然後 Claude Code 跳過了其中一個 hook 或卸載了它。
`hook skipped`
該行命名 mod 和事件，然後說 hook skipped: 和一個原因，例如 first-mod: tool.call hook skipped: threw Error: boom。hook 拋出、執行超過其10 秒時間限制，或返回了錯誤形狀的結果。該行針對每個事件和失敗類型出現一次，直到 mod 重新載入。
修復錯誤。偵錯日誌對每次發生都有一行。
`it crashed the hooks worker`
該行以 mod 的名稱開頭，例如 first-mod was unloaded: it crashed the hooks worker。已安裝的 mod 共享一個工作執行緒。工作執行緒停止回應或崩潰，Claude Code 將其追蹤到此 mod 並卸載了它。阻止執行緒的 hook（例如永不等待的迴圈）是一個原因。
修復 hook。
`mods that run in the hooks worker are off for this session`
該行讀取 hooks: mods that run in the hooks worker are off for this session: it crashed 3 times。工作執行緒停止了三次，Claude Code 無法將停止追蹤到一個 mod，因此它卸載了每個不是內建的 mod，包括您的組織安裝的 mod。此行到達每個互動式工作階段中的文字記錄。
執行 /reload-plugins 以再次載入它們。
工具呼叫被拒絕
mod 已載入，其 hook 執行，它接觸的工具呼叫被拒絕。
`a hook changed this call's input after the model wrote it`
在自動模式中，被拒絕的工具呼叫會給出此原因。hook 在伺服器端分類器檢查後變更了工具呼叫的輸入，因此該檢查不涵蓋將執行的內容。hook 可以是 mod 的 tool.call 或 turn.step hook，或 PreToolUse 設定 hook。訊息不會說明是哪一個。
訊息告訴 Claude 再次發出記錄的呼叫。如果也被拒絕，hook 每次都會變更輸入，因此關閉 mod 或 hook，或離開自動模式並自己批准呼叫。
關於您設定中的拒絕規則的訊息
tried to lift a deny rule in your settings 和 the deny rules in your settings could not be checked for this call, so it is refused 都來自內建防護。
在來自內建防護的訊息中查詢它們。
繪圖不出現或不回應
mod 已載入，其窗格、帶狀或控制項的行為不符合您的預期。
窗格或帶狀為空或顯示 Claude Code 的常見內容
您的 hook 返回的樹未驗證。使用 --plugin-dir，文字記錄說 ui.render (Pane) refused: 並帶有原因，例如 first-mod: ui.render (Pane) refused: Box prop "flexDirection" must be one of row, column, row-reverse, column-reverse; the engine drew its own。偵錯日誌有 a hook returned a tree that does not validate 並帶有相同的原因。
讀取該行上的原因。常見原因是元素不接受的 prop 和應用程式沒有的元素。
`$.ui.open` 執行且沒有窗格出現
呼叫不是來自使用者所做的事情，並且終端機的寬度小於 144 列。
從命令或按鈕開啟窗格，或檢查呼叫的 isPlaced 結果。請參閱在正確的時間開啟窗格。
快捷鍵沒有作用
您的窗格沒有鍵盤焦點。
按 Ctrl+X 然後 Tab，或按一下窗格。使用 focus: true 從命令開啟它。
繪圖在終端機中有效，但在 Desktop 應用程式中無效
該網站或元素在那裡不可用。
編輯或值遺失
mod 執行，您所做的變更或它保留的值不存在。
您的編輯不生效
您正在編輯您安裝的 plugin。Claude Code 執行已安裝版本的快取副本。
使用指向您的工作副本的 --plugin-dir 進行開發，例如 claude --plugin-dir ./first-mod，它在您儲存時重新載入。
模組重新載入時值重設
模組級變數在每次重新載入時重新初始化。
`/clear`、`/resume` 或 `/branch` 後值重設
值重設，或儲存的值被其預設值取代。這些命令中的每一個都將 $.state 重設為其預設值，並且 session.start 不會再次觸發。
在 classic.SessionStart hook 中再次載入儲存的值。
讀取偵錯日誌
偵錯日誌對 Claude Code 載入或拒絕的每個模組、失敗的每個 hook 和它拒絕的每個結果都有一行，因此當文字記錄顯示沒有內容時，這是要查看的地方。若要寫入一個，在您的 shell 中使用 --debug 啟動 Claude Code，或使用 --debug-file <path> 選擇它的位置：
claude --debug-file ./mod-debug.log --plugin-dir ./first-mod
在另一個終端機中，跟蹤檔案並篩選您的 mod 的名稱：
tail -f ./mod-debug.log | grep first-mod
已載入的 mod 有一行，其命名它並列出它掛接的事件。使用 --plugin-dir 載入的 mod 出現在其名稱後跟 @inline 下：
hooks module first-mod@inline loaded (worker, environment 2, tier user); events: session.start,tool.call,command.run,ui.render
未驗證的繪圖計為被拒絕的結果，也會得到一行。若要在日誌中寫入您自己的行，請呼叫 $.ui.log，並帶有第二個引數，例如 $.ui.log('message', { to: 'debug' })。沒有第二個引數，$.ui.log 會在文字記錄中新增暗淡行。
當您編輯使用 --plugin-dir 載入的 mod 時，文字記錄會為每次重新載入顯示一行，其命名 mod 並列出其 hook。如果儲存破壞了模組，該行說 reload failed, the previous version stays loaded: 並帶有原因，最後一個工作版本保持執行。
後續步驟
- 測試 mod：在問題到達工作階段之前捕捉它們
- 排除 plugin 的故障：安裝和載入 plugin 的問題，不特定於 mod