フック、MCP、およびプラグインの問題

本ページでは、フック、MCP サーバー、およびプラグインに関連する問題のトラブルシューティングについて説明します。

最初に確認すべき2つの項目

具体的なコンポーネントの詳細に入る前に、最も一般的な2つの原因を除外します。

ディレクトリが信頼されているか：信頼されていないワークスペースでは、プロジェクトレベル設定、フック、MCP、およびプロジェクトレベルのエージェントが読み込まれません（インタラクティブセッションではフックが直接ブロックされます）。ディレクトリに初めて入るときに信頼の選択ダイアログが表示され、「現在のセッションのみ」または「覚える」（settings.local.json に書き込み）を選択できます。また、permissions.trustDirectories を使用して頻繁に使用するディレクトリを永続的に信頼することもできます。権限を参照してください。
構成変更後に再読み込みしたか：ほとんどの拡張機能はホットリロードをサポートしており、再起動よりも高速です（/mcp reload、/plugins reload、/skills reload、/agents reload）。「再起動が必要」と記載されている構成項目については、引き続き CLI を再起動する必要があります。

フックがトリガーされない、または異常な動作をする場合：

イベントとマッチング：フックにバインドされているイベント名が正しいこと、および matcher がターゲットにマッチすることを確認します（空または * はすべてにマッチ、正確な値、| による複数値、または正規表現）。
終了コード：command タイプのフックは終了コードを使用してフローを制御します。0 は成功、2 はブロック（stderr がエージェントにフィードバックされる）、その他は非ブロックエラーです。フックが予期せず操作をブロックした場合は、2 が返されていないか確認してください。
入力の解析：フックは stdin から JSON（session_id、cwd、hook_event_name などを含む）を受信します。スクリプトが正しく読み取っていることを確認してください。
実行権限：command が指すスクリプトには実行権限が必要であり、パスが正しいことを確認してください。
/hooks を使用して、登録済みのフックを確認します。
完全なリファレンスはフックリファレンスを参照してください。

MCP サーバーが接続されていない、またはツールが利用できない場合：

/mcp を使用して、サーバーの接続状態を確認します。
コマンドとパス：stdio タイプの場合、command、args、cwd が正しく、サーバーが単独で起動できることを確認します。
プロジェクトレベルの承認：プロジェクトレベルの MCP サーバーは、デフォルトで個別に承認する必要があります。mcp.enableAllProjectMcpServers または mcp.enabledProjectMcpServers を使用して承認します。
許可リストの制限：mcp.allowed / mcp.excluded、--allowed-mcp-server-names、または --strict-mcp-config によってフィルタリングされていないか確認します。
認証：HTTP/SSE タイプの場合、headers 内の認証情報が正しいことを確認します。
タイムアウト：接続が遅い場合は、timeout フィールドを調整できます。
MCP 構成項目に「再起動が必要」と記載されている場合、変更後はまず /mcp reload を試し、それでも反映されない場合は再起動します。
完全なリファレンスは MCP リファレンスを参照してください。

プラグインが読み込まれない、またはコンポーネントが欠落している場合：

/plugins を使用して、インストール済みのプラグインを確認します。
マニフェスト：マニフェストは .qoder-plugin/plugin.json に配置されます（省略可能）。宣言されている場合は、name が有効（kebab-case、スペースなし）であることを確認します。
ディレクトリ構造：コンポーネントは、約束されたディレクトリ（commands/、agents/、skills/、hooks/hooks.json、.mcp.json など）に配置するか、マニフェストでパスを明示的に宣言する必要があります。
セキュリティ制限：security.blockGitExtensions が true の場合、Git からのプラグインの読み込みがブロックされます。security.allowedExtensions が空でない場合、マッチするソースのみが許可されます。
完全なリファレンスはプラグインリファレンスを参照してください。