mod が何もしない理由を調べる
mod が何もしない場合、2 つのチェックで理由が分かります。Claude Code が mod のファイルから読み込んだ内容と、何かをスキップするときに書く行です。最初のチェックについては、シェルでclaude plugin validate を mod のディレクトリで実行します。例えば claude plugin validate ./first-mod のようにします。セッションを開始せずに、スペルが間違ったイベント、不正なマニフェスト、Claude Code が読み込めないモジュールをキャッチします。
モジュールが読み込まれない場合、hooks がスキップされる場合、または別の mod があなたの mod を拒否する場合、Claude Code は mod の名前を付けた 1 行を書きます。その行を読む場所はセッションによって異なります。
- プラグインディレクトリをホットリロードするセッション: トランスクリプト内の薄い行。これは
--plugin-dirで開始した対話型セッション、または Claude が書いた mod の ホットリロードを有効にした セッションです。 - マーケットプレイスからインストールした mod を実行するセッションなど、その他の対話型セッション: デバッグログ のみ。取得するには、セッションを
claude --debugで開始します。 --plugin-dirを使用したclaude -p実行: stderr、デフォルトのテキスト出力形式で。別の mod による拒否はデバッグログのみに移動します。
mod が読み込めるかどうかを確認する
mod が読み込めるかどうかを確認するには、mod をインストールせずに、シェルから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: で始まる行があります。例えば --plugin-dir で読み込まれた mod の場合 hooks module first-mod@inline not loaded: disableAllHooks in managed settings のようになります。
コロンの後の理由を読んでください。拒否メッセージ セクションに各メッセージが記載されています。ログにそのような行がない場合は、このグループの他のエントリを確認してください。
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 でそのディレクトリで対話型セッションを開始し、開かれる信頼プロンプトを受け入れます。
インストール済みプラグインが読み込まれない
Claude Code を--safe-mode で開始しました。
フラグなしで開始します。
hooks がスキップされるか mod がアンロードされる
mod が読み込まれ、その後 Claude Code がそのいずれかの hooks をスキップするか、アンロードしました。hook skipped
行は mod とイベントの名前を示し、hook skipped: と理由を示します。例えば first-mod: tool.call hook skipped: threw Error: boom のようになります。hooks が例外をスロー、10 秒のタイムリミット を超過、または間違った形状の結果を返しました。行は mod がリロードされるまで、イベントと失敗の種類ごとに 1 回表示されます。
エラーを修正します。デバッグログには発生するたびに行があります。
it crashed the hooks worker
行は mod の名前で始まります。例えば first-mod was unloaded: it crashed the hooks worker のようになります。インストール済み mod は 1 つのワーカースレッドを共有します。ワーカーが応答を停止するか、クラッシュし、Claude Code がそれをこの mod に追跡して、アンロードしました。スレッドをブロックする hooks。例えば、await しないループが 1 つの原因です。
hooks を修正します。
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 と読みます。ワーカーが 3 回停止し、Claude Code が停止を 1 つの mod に追跡できなかったため、組み込みでない mod をすべてアンロードしました。組織がインストールする mod を含みます。この行はすべての対話型セッションのトランスクリプトに到達します。
/reload-plugins を実行してそれらを再度読み込みます。
ツール呼び出しが拒否される
mod が読み込まれ、その hooks が実行され、それが触れたツール呼び出しが拒否されます。a hook changed this call's input after the model wrote it
自動モードでは、拒否されたツール呼び出しはこの理由を示します。hooks が サーバー側分類器 がレビューした後、ツール呼び出しの入力を変更したため、そのレビューは実行される内容をカバーしません。hooks は mod の tool.call または turn.step hooks、または PreToolUse 設定 hooks である可能性があります。メッセージはどれかを示しません。
メッセージは Claude に記録されたとおりに呼び出しを再度発行するよう指示します。それも拒否された場合、hooks は毎回入力を変更するため、mod または hooks をオフにするか、自動モードを離れて呼び出しを自分で承認します。
設定の拒否ルールに関するメッセージ
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 の通常のコンテンツを表示する
ツリー が hooks から返されたものが検証されませんでした。--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 と同じ理由があります。
その行の理由を読んでください。一般的な原因は、要素が取らないプロップと、アプリが持たない要素です。
$.ui.open が実行され、ペインが表示されない
呼び出しはユーザーが行ったものから来ておらず、ターミナルは 144 列より狭いです。
コマンドまたはボタンからペインを開くか、呼び出しの isPlaced 結果を確認します。適切なタイミングでペインを開く を参照してください。
ホットキーが何もしない
ペインにキーボードフォーカスがありません。 Ctrl+X を押してから Tab を押すか、ペインをクリックします。focus: true を使用してコマンドから開きます。
描画がターミナルで機能し、Desktop アプリでは機能しない
サイトまたは要素はそこで利用できません。 レンダリングサイト と 要素 テーブルを確認してください。編集または値が失われる
mod が実行され、行った変更または保持していた値がありません。編集が有効にならない
インストールした plugin を編集しています。Claude Code はインストール済みバージョンのキャッシュされたコピーを実行します。claude --plugin-dir ./first-mod のように、作業コピーを指す --plugin-dir で開発します。保存時にリロードされます。
モジュールがリロードされるときに値がリセットされる
モジュールレベルの変数は各リロード時に再初期化されます。 値を$.state または $.store に保持します。
/clear、/resume、または /branch の後に値がリセットされる
値がリセットされるか、保存された値がデフォルトに置き換わります。これらのコマンドはそれぞれ $.state をデフォルトにリセットし、session.start は再度発火しません。
classic.SessionStart hooks で保存された値を再度読み込みます。
デバッグログを読む
デバッグログには、Claude Code が読み込むまたは拒否するすべてのモジュール、失敗するすべての hooks、拒否するすべての結果の行があります。トランスクリプトに何も表示されない場合は、ここを確認してください。書き込むには、シェルで Claude Code を--debug で開始するか、--debug-file <path> で場所を選択します。
--plugin-dir で読み込まれた mod は、その名前の後に @inline が続く形で表示されます。
$.ui.log を 2 番目の引数で呼び出します。例えば $.ui.log('message', { to: 'debug' }) のようにします。2 番目の引数がない場合、$.ui.log はトランスクリプトに薄い行を追加します。
--plugin-dir で読み込まれた mod を編集している間、トランスクリプトは mod の名前を示し、その hooks をリストする各リロードの行を表示します。保存がモジュールを破損する場合、行は reload failed, the previous version stays loaded: と理由を示し、最後に機能したバージョンが実行され続けます。
次のステップ
- mod をテストする: セッションに到達する前に問題をキャッチします
- プラグインのトラブルシューティング: mod に固有ではないプラグインのインストールと読み込みに関する問題