> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 排除 mod 的故障

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

當 mod 的模組或其中一個 hooks 失敗時，Claude Code 會跳過它，工作階段會繼續進行，因此損壞的 mod 看起來可能像沒有作用的 mod。首先檢查 Claude Code 從您的 mod 讀取了什麼，以及它在哪裡報告問題，然後找到您遇到的症狀或訊息。

<h2 id="find-out-why-a-mod-does-nothing">
  找出 mod 為什麼沒有作用
</h2>

當 mod 沒有作用時，兩項檢查可以找到原因：Claude Code 從 mod 的檔案讀取的內容，以及它在跳過某些內容時寫入的行。對於第一項，在您的 shell 中執行 [`claude plugin validate`](/docs/zh-TW/plugins/mods/create#check-what-claude-code-reads-from-your-mod)，並使用 mod 的目錄，例如 `claude plugin validate ./first-mod`。它會捕捉拼寫錯誤的事件、不良的資訊清單和 Claude Code 無法讀取的模組，而無需啟動工作階段。

當模組未載入、hook 被跳過或另一個 mod 拒絕您的 mod 時，Claude Code 會寫入一行，其中命名您的 mod。您讀取該行的位置取決於工作階段：

* **熱重新載入 plugin 目錄的工作階段**：文字記錄中的暗淡行。這是您使用 `--plugin-dir` 啟動的互動式工作階段，或您[為 Claude 編寫的 mod 啟用熱重新載入](/docs/zh-TW/plugins/mods/create#ask-claude-for-a-mod)的工作階段。
* **任何其他互動式工作階段，例如執行您從市場安裝的 mod 的工作階段**：[偵錯日誌](#read-the-debug-log)只有。若要取得一個，請使用 `claude --debug` 啟動工作階段。
* **`claude -p` 執行 `--plugin-dir`**：stderr，採用預設文字輸出格式。另一個 mod 的拒絕只會進入偵錯日誌。

<h2 id="check-whether-mods-can-load">
  檢查 mod 是否可以載入
</h2>

若要檢查您的設定是否允許 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 不會載入，並且[訊息會說明原因](/docs/zh-TW/plugins/mods/troubleshoot#messages-from-the-built-in-guard)。

<h2 id="the-mod-doesn’t-load">
  mod 不載入
</h2>

mod 新增的任何內容都不會出現：沒有命令、沒有繪圖，也沒有行為變化。

<h3 id="your-version-is-older-than-2-1-287">
  您的版本早於 2.1.287
</h3>

`claude --version` 列印的版本早於 2.1.287。您的版本早於預設開啟 mod 的時間。

[更新 Claude Code](/docs/zh-TW/setup#update-claude-code)。

<h3 id="the-mods-active-line-doesn’t-name-the-mod">
  `mods active` 行不命名 mod
</h3>

mod 新增的任何內容都不會出現，並且 `/plugin` 中的 [`mods active` 行](/docs/zh-TW/plugins/mods/overview#see-which-mods-a-session-loaded)不命名它。hooks 模組未載入。當 Claude Code 拒絕它時，偵錯日誌有一行以 `hooks module`、mod 的名稱和 `not loaded:` 開頭，例如 `hooks module first-mod@inline not loaded: disableAllHooks in managed settings`，用於使用 `--plugin-dir` 載入的 mod。

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

<h3 id="a-claude-p-run-prints-hooks-module-not-loaded">
  `claude -p` 執行列印 `hooks module not loaded`
</h3>

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

讀取冒號後的原因。[拒絕訊息](#refusal-messages)部分列出每一個。

<h3 id="refusal-messages">
  拒絕訊息
</h3>

每一個都遵循偵錯日誌中的 `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 共享一個名稱。使用受管的或首先載入的。 |

<h3 id="messages-from-the-built-in-guard">
  來自內建防護的訊息
</h3>

在具有受管設定的機器上，或對於使用 Team 或 Enterprise 方案登入的使用者，[內建防護](/docs/zh-TW/plugins/mods/admin#know-what-happens-by-default)可以拒絕 mod 或其中一個答案。每條訊息都命名您的組織管理員設定以變更規則的選項。

| 訊息包含 | 這表示什麼 | 它出現在哪裡 |
| :- | :- | :- |
| `mods are limited to your organization's by policy (allowManagedModsOnly)` | 您的組織僅允許[其自己的 mod](/docs/zh-TW/plugins/mods/admin#install-your-organizations-mods)，因此您的 mod 未被載入 | 偵錯日誌，以及[熱重新載入 plugin 目錄的工作階段](#find-out-why-a-mod-does-nothing)中的文字記錄 |
| `tried to lift a deny rule in your settings` | 您的 mod 的 [`tool.check`](/docs/zh-TW/plugins/mods/reference#tools) hook 批准了 `deny` 規則拒絕的呼叫。呼叫保持被拒絕。 | 文字記錄和偵錯日誌，每個工作階段中的每個 mod 一次。在 `claude -p` 執行中，僅偵錯日誌。 |
| `the deny rules in your settings could not be checked for this call, so it is refused` | 防護在檢查 mod 批准的呼叫時失敗，因此它拒絕了呼叫 | Claude 為被拒絕的呼叫讀取的原因 |

<h3 id="validate-passes-and-lists-no-hooks-line">
  `validate` 通過且不列出 `hooks` 行
</h3>

`hooks/hooks.json` 沒有 `modules` 鍵，或鍵拼寫錯誤。

新增 `"modules": ["./register.js"]`。

<h3 id="hooks-module-did-not-load">
  `hooks module did not load`
</h3>

該行以 mod 的名稱開頭，然後是 `hooks module did not load:` 和一個原因，當問題在您的程式碼中時，該原因會給出檔案和行。Claude Code 無法載入模組，例如因為其頂級程式碼拋出。

修復原因命名的錯誤。

<h3 id="options-do-not-fit-plugin-json-userconfig">
  `options do not fit plugin.json userConfig`
</h3>

該行以 mod 的名稱開頭，然後是 `hooks module did not load: options do not fit plugin.json userConfig:` 和一個原因。選項不符合其 [`userConfig`](/docs/zh-TW/plugins/components#user-configuration) 欄位，例如高於欄位 `max` 的數字，或必填欄位沒有值。

設定或變更值。該行的末尾命名其在 `settings.json` 中的 `pluginConfigs` 項目。

<h3 id="no-mod-loads-in-a-directory-you-opened-for-the-first-time">
  沒有 mod 在您首次開啟的目錄中載入
</h3>

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

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

<h3 id="no-installed-plugin-loads-at-all">
  沒有已安裝的 plugin 載入
</h3>

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

啟動時不使用該旗標。

<h2 id="a-hook-is-skipped-or-a-mod-is-unloaded">
  hook 被跳過或 mod 被卸載
</h2>

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

<h3 id="hook-skipped">
  `hook skipped`
</h3>

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

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

<h3 id="it-crashed-the-hooks-worker">
  `it crashed the hooks worker`
</h3>

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

修復 hook。

<h3 id="mods-that-run-in-the-hooks-worker-are-off-for-this-session">
  `mods that run in the hooks worker are off for this session`
</h3>

該行讀取 `hooks: mods that run in the hooks worker are off for this session: it crashed 3 times`。工作執行緒停止了三次，Claude Code 無法將停止追蹤到一個 mod，因此它卸載了每個不是內建的 mod，包括您的組織安裝的 mod。此行到達每個互動式工作階段中的文字記錄。

執行 `/reload-plugins` 以再次載入它們。

<h2 id="a-tool-call-is-denied">
  工具呼叫被拒絕
</h2>

mod 已載入，其 hook 執行，它接觸的工具呼叫被拒絕。

<h3 id="a-hook-changed-this-call’s-input-after-the-model-wrote-it">
  `a hook changed this call's input after the model wrote it`
</h3>

在自動模式中，被拒絕的工具呼叫會給出此原因。hook 在[伺服器端分類器](/docs/zh-TW/permission-modes#server-side-classifier-review)檢查後變更了工具呼叫的輸入，因此該檢查不涵蓋將執行的內容。hook 可以是 mod 的 [`tool.call`](/docs/zh-TW/plugins/mods/reference#tools) 或 [`turn.step`](/docs/zh-TW/plugins/mods/reference#turns) hook，或 [`PreToolUse`](/docs/zh-TW/hooks#pretooluse) 設定 hook。訊息不會說明是哪一個。

訊息告訴 Claude 再次發出記錄的呼叫。如果也被拒絕，hook 每次都會變更輸入，因此關閉 mod 或 hook，或離開自動模式並自己批准呼叫。

<h3 id="a-message-about-the-deny-rules-in-your-settings">
  關於您設定中的拒絕規則的訊息
</h3>

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

在[來自內建防護的訊息](#messages-from-the-built-in-guard)中查詢它們。

<h2 id="a-drawing-doesn’t-appear-or-respond">
  繪圖不出現或不回應
</h2>

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

<h3 id="a-pane-or-band-is-empty-or-shows-claude-code’s-usual-content">
  窗格或帶狀為空或顯示 Claude Code 的常見內容
</h3>

您的 hook 返回的[樹](/docs/zh-TW/plugins/mods/interface#build-a-tree-from-elements)未驗證。使用 `--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 和應用程式沒有的元素。

<h3 id="ui-open-runs-and-no-pane-appears">
  `$.ui.open` 執行且沒有窗格出現
</h3>

呼叫不是來自使用者所做的事情，並且終端機的寬度小於 144 列。

從命令或按鈕開啟窗格，或檢查呼叫的 `isPlaced` 結果。請參閱[在正確的時間開啟窗格](/docs/zh-TW/plugins/mods/interface#open-a-pane-at-the-right-time)。

<h3 id="hotkeys-do-nothing">
  快捷鍵沒有作用
</h3>

您的窗格沒有鍵盤焦點。

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

<h3 id="a-drawing-works-in-the-terminal-and-not-in-the-desktop-app">
  繪圖在終端機中有效，但在 Desktop 應用程式中無效
</h3>

該網站或元素在那裡不可用。

檢查[呈現網站](/docs/zh-TW/plugins/mods/reference#render-sites)和[元素](/docs/zh-TW/plugins/mods/reference#elements)表。

<h2 id="an-edit-or-a-value-is-lost">
  編輯或值遺失
</h2>

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

<h3 id="your-edits-don’t-take-effect">
  您的編輯不生效
</h3>

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

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

<h3 id="a-value-resets-when-the-module-reloads">
  模組重新載入時值重設
</h3>

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

[將值保留在 `$.state` 或 `$.store`](/docs/zh-TW/plugins/mods/interface#keep-state)。

<h3 id="a-value-resets-after-/clear-/resume-or-/branch">
  `/clear`、`/resume` 或 `/branch` 後值重設
</h3>

值重設，或儲存的值被其預設值取代。這些命令中的每一個都將 `$.state` 重設為其預設值，並且 `session.start` 不會再次觸發。

[在 `classic.SessionStart` hook 中再次載入儲存的值](/docs/zh-TW/plugins/mods/interface#load-a-saved-value-again-after-clear)。

<h2 id="read-the-debug-log">
  讀取偵錯日誌
</h2>

偵錯日誌對 Claude Code 載入或拒絕的每個模組、失敗的每個 hook 和它拒絕的每個結果都有一行，因此當文字記錄顯示沒有內容時，這是要查看的地方。若要寫入一個，在您的 shell 中使用 `--debug` 啟動 Claude Code，或使用 `--debug-file <path>` 選擇它的位置：

```bash theme={null}
claude --debug-file ./mod-debug.log --plugin-dir ./first-mod
```

在另一個終端機中，跟蹤檔案並篩選您的 mod 的名稱：

```bash theme={null}
tail -f ./mod-debug.log | grep first-mod
```

已載入的 mod 有一行，其命名它並列出它掛接的事件。使用 `--plugin-dir` 載入的 mod 出現在其名稱後跟 `@inline` 下：

```text theme={null}
hooks module first-mod@inline loaded (worker, environment 2, tier user); events: session.start,tool.call,command.run,ui.render
```

未驗證的繪圖計為被拒絕的結果，也會得到一行。若要在日誌中寫入您自己的行，請呼叫 [`$.ui.log`](/docs/zh-TW/plugins/mods/api#show-something-without-starting-a-turn)，並帶有第二個引數，例如 `$.ui.log('message', { to: 'debug' })`。沒有第二個引數，`$.ui.log` 會在文字記錄中新增暗淡行。

當您編輯使用 `--plugin-dir` 載入的 mod 時，文字記錄會為每次重新載入顯示一行，其命名 mod 並列出其 hook。如果儲存破壞了模組，該行說 `reload failed, the previous version stays loaded:` 並帶有原因，最後一個工作版本保持執行。

<h2 id="next-steps">
  後續步驟
</h2>

* [測試 mod](/docs/zh-TW/plugins/mods/test)：在問題到達工作階段之前捕捉它們
* [排除 plugin 的故障](/docs/zh-TW/plugins/troubleshooting)：安裝和載入 plugin 的問題，不特定於 mod