找出 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，此命令不會報告。在這種情況下，您安裝的 mod 不會載入，並且訊息會說明原因。
mod 不載入
mod 新增的任何內容都不會出現：沒有命令、沒有繪圖，也沒有行為變化。您的版本早於 2.1.287
claude --version 列印的版本早於 2.1.287。您的版本早於預設開啟 mod 的時間。
更新 Claude Code。
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:。
來自內建防護的訊息
在具有受管設定的機器上，或對於使用 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 項目。
沒有 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，它在您儲存時重新載入。
模組重新載入時值重設
模組級變數在每次重新載入時重新初始化。 將值保留在$.state 或 $.store。
/clear、/resume 或 /branch 後值重設
值重設，或儲存的值被其預設值取代。這些命令中的每一個都將 $.state 重設為其預設值，並且 session.start 不會再次觸發。
在 classic.SessionStart hook 中再次載入儲存的值。
讀取偵錯日誌
偵錯日誌對 Claude Code 載入或拒絕的每個模組、失敗的每個 hook 和它拒絕的每個結果都有一行，因此當文字記錄顯示沒有內容時，這是要查看的地方。若要寫入一個，在您的 shell 中使用--debug 啟動 Claude Code，或使用 --debug-file <path> 選擇它的位置：
--plugin-dir 載入的 mod 出現在其名稱後跟 @inline 下：
$.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