SpyBara
Go Premium

plugins/mods/troubleshoot.md 2026-10-19 23:58 UTC to 2026-10-20 23:00 UTC

This page contains 49 additions and 121 deletions.

2026
Thu 1 23:59 Fri 2 22:59 Tue 6 23:59 Thu 8 22:58 Fri 9 23:02 Sat 10 23:01 Thu 15 23:58 Fri 16 22:59 Mon 19 23:58 Tue 20 23:00 Thu 22 22:58 Fri 23 22:59 Sat 24 22:59 Sun 25 23:58 Mon 26 22:57 Tue 27 22:59

排除 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 的目錄執行。您不需要工作階段。它列印的訊息會告訴您狀態：

訊息包含 這表示什麼
no hooks module to load Mod 可以載入。該命令在此目錄中找不到要測試的 mod。
hooks modules are turned off here 設定正在阻止您的 mod：您自己設定中的 disableAllHooks，或您的組織的原則
hooks modules are turned off in this process: the rollout switch served off Anthropic 已遠端關閉已安裝的 mod。
hooks modules are turned off in this process: the rollout switch was saved off by an earlier session 該命令使用了先前工作階段儲存的值，該值可能已過時。請啟動 claude 一次以重新整理它，然後再次執行該命令。

組織也可以設定 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:。

訊息開頭為 這表示什麼
hooks modules are turned off for installed plugins in this process: the rollout switch served off Anthropic 已遠端關閉已安裝的 mod。
hooks modules are turned off for installed plugins in this process: the rollout switch was saved off by an earlier session 該工作階段使用了先前工作階段儲存的值，該值可能已過時。請重新啟動 Claude Code 以重新整理它。
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 另一個已啟用的外掛與您的 mod 同名，並佔有該名稱，因此您的 hook 模組不會載入

來自內建防護的訊息

在具有受管設定的機器上，或在憑證為 Team 或 Enterprise /login 的工作階段中，內建防護可以拒絕 mod 或其中一個答案。每條訊息都命名您的組織管理員設定以變更規則的選項。

訊息包含 這表示什麼 它出現在哪裡
mods are limited to your organization's by policy (allowManagedModsOnly) 您的組織僅允許其自己的 mod，因此您的 mod 被拒絕 偵錯日誌，以及熱重新載入外掛目錄的工作階段中的逐字稿
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 項目。

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 都來自內建防護。

在來自內建防護的訊息中查詢它們。

回合停止後出現提示訊息

Stopped: type a message to continue; a mod cannot resume work after Stop

此提示訊息表示在您停止回合之後（例如按下 Esc），某個 mod 嘗試自行開始工作，而 Claude Code 未允許它這麼做。無需修正任何問題。在您傳送下一則訊息後，mod 即可再次開始工作，而部分工作會自行恢復。如果您預期該 mod 產生的結果沒有恢復，請再次提出要求，或再次執行該 mod 的命令。

如果您是該 mod 的作者，請參閱使用者中斷回合後的呼叫與背景工作。

繪圖不出現或不回應

mod 已載入，其窗格、帶狀、toast 或控制項的行為不符合您的預期。

顯示的是另一個 mod 的帶狀，而不是您的

提示詞上方只有一個帶狀，所有 mod 共用。在您的 mod 之前執行的 mod，若返回的樹中不包含 next(e) 的結果，就會取代您的帶狀。若要同時顯示兩個帶狀，請修改該 mod 的 hook，或請其作者修改：

  • 保留其後的帶狀：將 await next(e) 的結果放在其樹中某個 Box 的子元素之間，如選擇繪製位置中「提示詞上方的帶狀」分頁所示
  • 保持樹有效：不要為該 Box 或其外圍的任何 Box 指定 width、height、minWidth、minHeight、position、top、left、right、bottom、display 或 overflow prop

若要找出該 mod，請寫入偵錯日誌，並在其中搜尋 answered ui.render without next()。像 other-mod (user) answered ui.render without next() 這樣的行會指出某個未呼叫 next(e) 就返回其樹的 mod。該行不會指出轉譯位置，因此僅使用窗格的 mod 也可能出現。呼叫了 next(e) 但捨棄其結果的 mod 不會產生任何行，因此也請檢查在您之前的 hook。

變更之後，若任何 mod 返回未通過驗證的樹，帶狀中將不會顯示任何內容。若要讀取原因，請在 --plugin-dir 工作階段的逐字稿中尋找 ui.render (AbovePrompt) refused: 行，或在偵錯日誌中搜尋 does not validate。當帶狀中有多個 mod 時，這兩行都不會指出是哪個 mod，因此請檢查每個 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.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。

快捷鍵沒有作用

您的窗格沒有鍵盤焦點，或繪圖位於 VS Code 擴充功能中，而該處的按鈕沒有快捷鍵。請執行相符的操作：

  • 沒有鍵盤焦點：按 Ctrl+X 然後 Tab，或按一下窗格。若要讓窗格在開啟時取得焦點，請從命令以 focus: true 開啟它。
  • 在 VS Code 擴充功能中：按一下按鈕，或在按鈕取得焦點後按 Enter

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

可能是該應用程式不繪製該位置或元素，或是該工作階段屬於 VS Code 擴充功能不會為 mod 繪製任何內容的情況。mod 的其他 hook 仍會執行。請檢查以下原因：

  • 該位置或元素未在該應用程式中繪製：在轉譯位置表中查詢您的位置，並在元素表中查詢您的元素。對於該應用程式缺少的元素，請在 hook 中檢查 e.surface，並返回該應用程式可繪製的樹。
  • VS Code 擴充功能版本早於 2.1.299：聊天面板從擴充功能版本 2.1.299 起會為 mod 繪製內容。請在 VS Code 的 Extensions 檢視中檢查版本，並在該處更新擴充功能。
  • 擴充功能版本早於 2.1.304 且工作階段不擷取功能旗標：請更新擴充功能，或改為在 VS Code 的整合式終端機中執行 claude。在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上的工作階段會略過此擷取。對於其他會略過擷取的工作階段，例如 Claude apps 閘道工作階段，請參閱需要擷取功能旗標的功能。

編輯或值遺失

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 時。

後續步驟