排除 mod 的故障

找出 Claude Code mod 為什麼沒有作用：將症狀或訊息與其原因相符，查詢拒絕訊息，並閱讀偵錯日誌。

當 mod 的模組或其中一個 hook 失敗時，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 的目錄執行。您不需要工作階段。它列印的訊息會告訴您狀態：

組織也可以設定 allowManagedModsOnly 以僅允許其自己的 mod，此命令不會報告。在這種情況下，Claude Code 會拒絕您安裝的 mod，並且訊息會說明原因。

mod 不載入

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。

讀取冒號後的原因。拒絕訊息部分列出每一個。如果日誌沒有這樣的行，請逐一檢查此群組中的其他項目。

部分設定會停用 mod，但讓其外掛的其餘部分繼續運作。開啟或關閉 mod 列出了這些設定。

`claude -p` 執行列印 `hooks module not loaded`

該行以 mod 的名稱開頭，並進入 stderr。hooks 模組被拒絕。非互動式執行沒有文字記錄，因此訊息進入 stderr。

讀取冒號後的原因。拒絕訊息部分列出每一個。

拒絕訊息

每一個都遵循偵錯日誌中的 hooks module、mod 的名稱和 not loaded:。

來自內建防護的訊息

在具有受管設定的機器上，或對於使用 Team 或 Enterprise 方案登入的使用者，內建防護可以拒絕 mod 或其中一個答案。每條訊息都命名您的組織管理員設定以變更規則的選項。

`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 項目。

`code nested too deep to scan: more than 2000 scopes`

該行以 mod 的名稱開頭，然後是 hooks module did not load:、檔案，以及 code nested too deep to scan: more than 2000 scopes。hook 模組中的檔案不能將作用域（例如函式、區塊和迴圈）巢狀超過 2,000 層。claude plugin validate 會回報相同的原因。

重寫程式碼，以減少其作用域的巢狀深度。

沒有 mod 在您首次開啟的目錄中載入

您尚未回答該目錄的信任提示。

使用 claude 在該目錄中啟動互動式工作階段，並接受它開啟的信任提示。

沒有已安裝的 plugin 載入

您使用 --safe-mode 啟動了 Claude Code。

啟動時不使用該旗標。

Claude Code 不再詢問是否啟用熱重新載入

Claude 在互動式工作階段中撰寫 mod，但沒有任何內容載入，而且 Claude Code 不再詢問是否啟用熱重新載入。如果該問題有三次在未選擇答案的情況下結束，熱重新載入會保持關閉。例如，當您設定了 askUserQuestionTimeout，且在您回答之前時間已到，問題就會以這種方式結束。該設定在此適用，是因為 Claude Code 是在與 AskUserQuestion 相同的問題對話框中詢問。您自行關閉的問題不計入這三次。

若要執行該 mod，請將其目錄從 mods 資料夾複製出來，然後在 shell 中使用 --plugin-dir 啟動新的工作階段，例如 claude --plugin-dir ~/mods/git-branch。

hook 被跳過或 mod 被卸載

mod 已載入，然後 Claude Code 跳過了其中一個 hook 或卸載了它。

`hook skipped`

該行命名 mod 和事件，然後說 hook skipped: 和一個原因，例如 first-mod: tool.call hook skipped: threw Error: boom。hook 拋出、執行超過其時間限制，或返回了錯誤形狀的結果。該行針對每個事件和失敗類型出現一次，直到 mod 重新載入。

修復錯誤。偵錯日誌對每次發生都有一行。

`no command.run hook answered it`

您執行 mod 新增的命令，回覆命名 mod 和命令，例如 first-mod registered /tally but no command.run hook answered it，然後告訴您新增 hook。Claude Code 在命令到達鏈的末端且沒有答案時列印該回覆，這在兩種情況下發生：

• 沒有 hook 回答命令：模組沒有 command.run hook、hook 的篩選器命名不同的命令，或 hook 返回 next(e)
• Claude Code 跳過了 hook：hook skipped 列出了原因。將 focus: false 傳遞給 $.ui.open 是到達那裡的一種方式。

如果模組已經有回覆描述的 hook，請尋找命名 command.run 的 hook skipped 行，它會給出原因。執行命令的測試會因相同原因失敗。

`it crashed the hooks worker`

該行以 mod 的名稱開頭，例如 first-mod was unloaded: it crashed the hooks worker。已安裝的 mod 共享一個工作執行緒。工作執行緒停止回應或崩潰，Claude Code 將其追蹤到此 mod 並卸載了它。阻止執行緒的 hook（例如永不等待的迴圈）是一個原因。

修復 hook。

`its session.start ran again in a fresh copy`

該行以 mod 的名稱開頭，並命名一個 $.prompt.submit、$.command.run 或 $.agent.spawn 呼叫，例如 first-mod: its session.start ran again in a fresh copy; the $.prompt.submit call it had already made was not made again。Claude Code 再次載入了 mod 的模組，例如在 hook 工作執行緒崩潰並被取代之後，而新副本的 session.start hook 執行了。該行命名的呼叫以其第一次執行的結果解析，而不是再次執行，因此您的 mod 不會重複提交提示詞、執行命令或啟動 subagent。hook 的其餘部分照常執行。

無需修復任何內容。

在 v2.1.292 之前，該呼叫會執行第二次，因此提示詞會被提交兩次、命令會被執行兩次，或 subagent 會被啟動兩次。

`$.agent.register refused: the hooks module that made the call is no longer loaded`

該行以您的 mod 名稱開頭，例如 first-mod: $.agent.register refused: the hooks module that made the call is no longer loaded (it was reloaded or removed)，且該 agent 不會被註冊。您的 mod 在此呼叫之前已被重新載入或卸載。重新載入會載入 hook 模組的新副本，而此呼叫來自仍在舊副本中執行的程式碼，例如尚未返回的 hook。

如果該 hook 未捕捉此拒絕，它會失敗，Claude Code 會跳過它。若要讓保持載入的副本註冊該 agent，請在您的 session.start 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 已載入，其窗格、帶狀、toast 或控制項的行為不符合您的預期。

窗格或帶狀為空或顯示 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.render` 行顯示 `threw while drawn`

該行會指出轉譯位置，接著顯示 threw while drawn: 與錯誤，例如 first-mod: ui.render (ToolUse) threw while drawn: <error>; the engine drew its own。Claude Code 在繪製您的 ui.render hook 返回的樹時，或在根據您的 hook 傳給 next 的 props 繪製該位置時，遇到了該錯誤。結尾的 the engine drew its own 表示該位置顯示 Claude Code 的常見內容。

讀取該錯誤，並修正您的 hook 中導致錯誤的值。

在 v2.1.289 之前，逐字稿列中的此錯誤會以 Claude Code exited after an unrecoverable interface error 結束工作階段。

`the module failed without a message`

某個 Client 因沒有訊息的錯誤而失敗，例如 throw new Error()。在其位置顯示的那一行類似 my-mod: Client client/spinner.js: the module failed without a message。

在您的 Client 程式碼中找到該 throw，並為錯誤加上訊息。該行隨後便會顯示該訊息。

在 v2.1.289 之前，該行會改為顯示 Error 作為原因。

`$.ui.open` 執行且沒有窗格出現

呼叫不是來自使用者所做的操作，並且終端機的寬度小於該窗格所需的寬度。

從命令或按鈕開啟窗格，或檢查呼叫的 isPlaced 結果。請參閱在正確的時間開啟窗格。

toast 未出現

您的 mod 在互動式終端機工作階段中呼叫 $.ui.toast，但您沒有看到 toast。若要確認該呼叫已執行，請在偵錯日誌中尋找包含您的 mod 名稱與 toast 文字的行，例如 $.ui.toast (first-mod): build finished。接著檢查以下可能原因：

• 缺少該呼叫的行：尋找說明 Claude Code 拒絕該呼叫原因的行，例如 first-mod: $.ui.toast dropped: timeoutMs is a whole number of ms, 1 to 60000。
• 有窗格正在保留 toast：您的 mod 或其他 mod 在開啟目前顯示的窗格時傳入了 holdToasts。關閉該窗格即可結束保留。如果該窗格是您的，且應保持開啟，請從其 $.ui.open 呼叫中移除 holdToasts，然後重新開啟窗格。
• toast 位於提示詞下方：在傳統轉譯器中，請查看提示詞下方的右側。該處的 toast 是以 mod 名稱開頭的一行文字，而不是右上角的方框。
• 您的 mod 發出了較新的 toast：在傳統轉譯器中，您的 mod 發出的較新 toast 可能會取代正在顯示或等待顯示的 toast。偵錯日誌中會有較舊 toast 的另一行，若該 toast 正在顯示，結尾為 gave way, cut short；若從未出現，結尾為 gave way, unseen。若要同時顯示兩則訊息，請將它們放在同一個 toast 中。
• toast 在繪製前逾時：在全螢幕轉譯中，Claude Code 一次最多繪製三個 toast，因此 toast 可能在繪製前就已逾時。偵錯日誌中會有該 toast 的另一行，結尾為 left the stack, never drawn。當您的 mod 同時發出多個 toast 時，請將訊息放在同一個 toast 中。

在 v2.1.290 之前，Claude Code 會捨棄在其為您的 mod 顯示上一個 toast 後兩秒內發出的 toast，且被捨棄 toast 的偵錯日誌行會顯示 within 2000ms of the last; dropped。

快捷鍵沒有作用

您的窗格沒有鍵盤焦點。

按 Ctrl+X 然後 Tab，或按一下窗格。使用 focus: true 從命令開啟它。

繪圖在終端機中有效，但在 Desktop 應用程式中無效

該位置或元素在那裡不可用。

檢查轉譯位置和元素表。

編輯或值遺失

mod 執行，您所做的變更或它保留的值不存在。

您的編輯不生效

您正在編輯您安裝的 plugin。Claude Code 執行已安裝版本的快取副本。

使用指向您的工作副本的 --plugin-dir 進行開發，例如 claude --plugin-dir ./first-mod，它在您儲存時重新載入。

模組重新載入時值重設

模組級變數在每次重新載入時重新初始化。

將值保留在 $.state 或 $.store。

`/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: 並帶有原因，最後一個可運作的版本會保持執行，直到 Claude Code 下次重新載入外掛為止，例如當您執行 /reload-plugins 時。

後續步驟

• 測試 mod：在問題到達工作階段之前捕捉它們
• 排除 plugin 的故障：安裝和載入 plugin 的問題，不特定於 mod