Skip to main content
このガイドは、CC Safety Net のインストールと動作に関する主な問題を扱います。まず status で判定を確認し、次に doctor で詳しいレポートを取得してください。

​
まず診断を実行する

status は、ランタイムの判定（ready または degraded）、有効な保護と安全レベル、ポリシーファイルのパス、未解決の問題を 1 件ずつ表示します。Claude Code のプラグインが無効な場合は、別の判定になるのではなく Not active の先頭項目として表示されます。status は情報表示専用で、終了コードは常に 0 です。
doctor は、対応するすべてのエージェントを検査します。対象は、hook の連携状態、ブロックが機能するかを確かめるセルフテスト、カスタムルールの検証、有効になっているモードフラグ、最近の実行履歴、システムのバージョン、更新の有無です。ルールの設定と policy.json の両方を報告するのは、このコマンドだけです。各チェックの内容は、doctor コマンドのリファレンスを参照してください。 個別の問題を調べる前に、この出力を確認してください。多くの問題はここで見つかります。
判定が degraded の場合、設定元のいずれかが拒否され、代わりに安全なものが適用されていることを意味します。コマンドがブロックされるという意味ではありません。設定が無効でも、通常の作業が拒否されることはありません。設定の復旧を参照してください。

​
よくある問題への対処

ブロックされるはずのコマンドが、何の介入もなく実行されてしまう場合、hook がエージェントに正しく登録されていません。対処手順：
  1. npx cc-safety-net doctor を実行します。対応するすべてのエージェントについて hook の連携状態を確認し、設定に問題があれば該当する設定ファイルのパスを示します。
  2. そのエージェント用のインストールコマンドを実行し直します。正常な管理下のインストールであればこの操作は冪等で、欠けている管理対象エントリや壊れたエントリを修復します。インストーラーが「認識できない」「シンボリックリンクである」「別の所有者の設定やファイルである」と報告した場合は上書きせず、表示された手動復旧の手順に従ってください。エージェントごとのコマンド一覧はインストールにあります。
  3. Amp Code：amp plugins list を実行し、cc-safety-net (User Plugins) の行の状態が active であることを確認します。それ以外の状態であれば、Amp で plugins: reload を実行するか、install --amp で再インストールしてください。~/.config/amp/plugins/cc-safety-net.ts にローカルファイルが残っていると、personal plugin が覆い隠されます。install --amp は、それが管理対象のコピーであれば削除し、管理対象外のファイルであれば対処方法を示すエラーで失敗します。Amp は起動時にプラグインを読み込むため、変更後は Amp を再起動するか plugins: reload を実行してください。
  4. Antigravity CLI：~/.gemini/config/hooks.json に、npx -y cc-safety-net hook --agy-cli を実行する管理対象の PreToolUse エントリがあることを確認します。
  5. Claude Code：Claude Code 内で /plugin を実行し、インストール済みプラグインの一覧に cc-safety-net があり、有効になっていることを確認します。見当たらない場合は /plugin install cc-safety-net@cc-marketplace で再インストールし、/reload-plugins を実行してください。
  6. Codex：codex plugin list を実行し、cc-safety-net@cc-marketplace の行が installed, enabled になっていることを確認します。次に TUI で /hooks を実行し、cc-safety-net PreToolUse hook を選択して t を押し、信頼済みにします。この信頼操作を行わないと hook は動作しません。
  7. Cursor：~/.cursor/hooks.json に、npx -y cc-safety-net hook --cursor を実行する管理対象の preToolUse エントリがあることを確認します。この設定はグローバルなので、エントリ 1 つですべてのプロジェクトの Cursor IDE と Cursor CLI が対象になります。
  8. Gemini CLI：gemini extensions list を実行し、https://github.com/kenryu42/gemini-safety-net を取得元とする拡張機能がインストールされ、有効になっていることを確認します。User と Workspace の両方のスコープを確認してください。両方に設定がある場合は Workspace が優先されます。必要であれば gemini extensions install https://github.com/kenryu42/gemini-safety-net で再インストールし、新しい Gemini のセッションを開始します。
  9. GitHub Copilot CLI：cc-safety-net@cc-marketplace プラグインがインストール済み（/plugin）で、~/.copilot/settings.json の enabledPlugins で有効になっていることを確認します。Copilot CLI 1.0.8 以降では、インラインの hook 設定と disableAllHooks を次の優先順で確認します。.github/copilot/settings.local.json、.github/copilot/settings.json、.claude/settings.local.json、.claude/settings.json、~/.copilot/settings.json、~/.copilot/config.json の順です。disableAllHooks を最初に定義しているファイルが結果を決めます。true はすべての hook を無効にし、false は優先度の低い設定の適用を止めます。.claude 側の hook は cc-safety-net hook --copilot-cli または cc-safety-net hook -cp を実行する必要があります。通常の Claude Code の hook が Copilot に登録されることはありません。~/.copilot/hooks/ に置くユーザー hook ファイルには、Copilot CLI 0.0.422 以降が必要です。
  10. Grok Build：~/.grok/hooks/cc-safety-net.json（または $GROK_HOME/hooks/cc-safety-net.json）に、npx -y cc-safety-net hook --grok-build を実行する管理対象の PreToolUse エントリがあることを確認します。なければ npx -y cc-safety-net@latest install --grok-build を実行し直してください。
  11. Hermes Agent：管理対象のプラグインファイルが $HERMES_HOME/plugins/cc-safety-net（HERMES_HOME が未設定の場合は ~/.hermes/plugins/cc-safety-net）にあること、および hermes plugins enable cc-safety-net --no-allow-tool-override によってプラグインが有効になっていることを確認します。Hermes は config.yaml に記載されたユーザープラグインしか読み込みません。確認できたら Hermes を再起動してください。doctor はプラグインファイルと Hermes の設定を読むだけで、実行中の Hermes に実際に読み込まれたかまでは確認しません。変更後は再起動してから、もう一度試してください。
  12. Kimi Code：~/.kimi-code/config.toml（または $KIMI_CODE_HOME/config.toml）に、PreToolUse の Bash で npx -y cc-safety-net hook --kimi-code を実行する [[hooks]] ブロックがあることを確認します。なければ npx -y cc-safety-net@latest install --kimi-code を実行し直してください。
  13. OpenClaw：プラグインは OpenClaw 自身の CLI でインストールして有効にします。npx -y cc-safety-net@latest install --openclaw を実行し直すと、openclaw plugins install <plugin dir> --force と openclaw plugins enable cc-safety-net が実行され、プラグインが読み込まれたことまで確認します。詳細は openclaw plugins inspect cc-safety-net --runtime で確認できます。その後、OpenClaw Gateway を再起動してください。openclaw.json に plugins.allow を設定している場合は、そこに cc-safety-net も記載する必要があります。なお doctor はプラグインのディレクトリと openclaw.json を読むだけで、実行中の Gateway に読み込まれたかは確認しないため、Gateway が停止していても失敗としては報告しません。
  14. OpenCode：XDG_CONFIG_HOME が設定されていれば $XDG_CONFIG_HOME/opencode/opencode.json（または .jsonc）を、設定されていなければ ~/.config/opencode/opencode.json（または .jsonc）を確認し、plugin[] の配列に cc-safety-net があることを確かめます。OpenCode は古いバージョンをキャッシュしていることがあります。キャッシュの消去手順はインストールを参照してください。
  15. Pi：pi install npm:cc-safety-net が完了していることを確認し、拡張機能を読み込むために Pi を再起動します。Pi は CC Safety Net をプロセス内の拡張機能として実行します。確認には、Pi を直接起動して調べる npx cc-safety-net doctor を使ってください。
  16. 変更が終わったら、エージェントのセッションを再読み込みするか再起動します。
使っているエージェントがどの方式かが分からない場合は、連携アーキテクチャを参照してください。
正常なチェックは 1 秒未満で終わります。すべてのコマンドが数秒待たされる場合、遅いのは解析ではなく cc-safety-net パッケージの解決です。対処手順：
  1. エージェントが hook をどう実行しているかを確認します。Claude Code のプラグインは同梱されたコピーを直接実行するため、パッケージの解決が原因になることはありません。Antigravity CLI、Cursor、Grok Build、Hermes Agent、Kimi Code の hook はコマンドのたびに npx -y cc-safety-net を実行するため、npm のキャッシュが正常でも数百ミリ秒が加わります。
  2. エージェントの外で、解決にかかる時間を計測します。
    2〜3 回続けて実行してください。リリース後の初回はパッケージをダウンロードするため、一度だけ遅くなります。2 回目以降は数百ミリ秒に収まるはずです。
  3. レジストリの遅延かどうかを切り分けます。
    --prefer-offline では速いのに通常の実行が遅いままなら、npx は npm レジストリの応答を待っています。これはネットワークまたはプロキシの問題で、CC Safety Net の問題ではありません。
  4. npm のキャッシュを修復します。
    肥大化または破損したキャッシュは、2 回目以降の実行を含むすべての npx の解決を遅くします。npm cache verify はキャッシュをガベージコレクションして修復します。このセクションのきっかけになった報告（issue #16）では、5 GB 以上を回収して hook を 1 秒未満に戻しました。
対処が終わったら、手順 2 の計測コマンドを再実行してください。2 回目以降が数百ミリ秒に収まっていれば、npx を経由する連携としては最速の状態です。
ブロックされると思っていたコマンドが許可された場合は、次の順に確認してください。多くの場合、対応漏れではなく、文書化された許可か、想定より低い安全レベルが原因です。対処手順：
  1. npx cc-safety-net explain "<the command>" を実行し、CC Safety Net がそのコマンドをどう評価したかを最初から確認します。出力には、確認されたルール、実際に適用されている安全レベル、そしてルールは存在するが現在のレベルでは無効な場合にその旨を示す行が含まれます。
    トレースがそのまま安全に共有できるわけではありません。マスク処理の対象は、認識できる資格情報の形式だけです。コマンド文字列、解析後のトークン、ホームディレクトリを含む絶対パス、ポリシーファイルのパスはそのまま残ります。ダミーの資格情報を使って再現し、貼り付ける前に出力を確認してください。
  2. 出力に表示される有効なレベルを確認します。standard モードはベストエフォートで、動的な実行ファイル、コマンド置換で組み立てられたコマンド構造、rm -rf "$target" のような検証できない再帰削除の対象、組み込みの機密パスに対するメタデータのみのチェックを意図的に許可します。コマンドがプロンプトインジェクションなど敵対的な文脈から来る可能性がある場合は、これらすべてが fail closed になる strict または paranoid に引き上げてください。
  3. そのコマンドが、明示的に許可されている分類に該当することもあります。たとえばカレントディレクトリ配下の rm -rf は、プロジェクト内に閉じているため既定で許可されます。全一覧は許可されるコマンドを参照してください。
  4. npx cc-safety-net status を実行します。判定が degraded の場合、ルールの設定元が破棄されており、その設定元が提供していた拒否は適用されていません。設定の復旧を参照してください。
  5. 同じ status の出力に Project policy のブロックがないか確認します。このブロックは、プロジェクトの .cc-safety-net/policy.json がユーザーポリシーを緩和したときに表示され、緩和された項目ごとに 1 行ずつ、project policy lowers level: strict -> standard、project policy disables rule <id>、project policy adds destructive allow path: <path> のように示されます。このプロジェクトだけルールが働かず、他では働くという状況は、いずれかの行で説明できます。ステータスラインは同じ状態を 🔻 で示し、doctor は同じ行を Project policy deltas: の下に出力します。
  6. CC Safety Net が解析しないプロキシ経由でコマンドを実行している場合は、npx -y cc-safety-net rule wrapper add <command> で登録し、実際の子コマンドを解析できるようにしてください。
  7. 自分の環境ではそのコマンドをブロックしたい場合は、npx -y cc-safety-net rule init でカスタムの rulebook を作成し、.cc-safety-net/rules/project-rules/rulebook.json にルールを追加します。スキーマはカスタムルールを参照してください。
  8. 以上のどれにも当てはまらない場合、ルールがまだブロックしないコマンド形式は対応漏れであり、このプロジェクトの方針では公開のバグとして扱います。そのまま貼り付けて実行できる攻撃コードではなく、コマンドの形式を説明した GitHub Issue を作成してください。シークレットの漏えい、意図したディレクトリの外への書き込み、サプライチェーンやパッケージの完全性に関わる問題は、非公開の開示経路を使います。両方の手順と切り分けの基準はセキュリティポリシーにあります。 報告には、手順 1 で内容を確認した explain のトレースを添えてください。未確認のトレースや本物の資格情報は添付しないでください。文書化された境界に該当する場合は、既知の制限に説明と、代わりに使える対策があります。
組み込みのルールは意図的に保守的です。必要なコマンドがブロックされた場合は、いくつかの選択肢があります。対処手順：
  1. npx cc-safety-net explain "<the command>" を実行し、ブロックの正確な理由と、一致したルールを確認します。
  2. 拒否の理由が “Command analysis exceeds CC Safety Net’s derived-command work limit. Reduce nested or embedded command complexity and retry.” の場合、ルールに一致したわけではありません。アナライザーがそのコマンドから派生させる処理量の上限を使い切っています。find -exec、xargs、parallel の中のシェル 1 行コード、ラッパーの背後に埋め込まれたコマンド、同様の入れ子構造が該当します。この上限はコンパイル時の定数で、設定では引き上げられません。コマンドを単純な複数のコマンドに分けて実行し直してください。
  3. 拒否の理由が “CC Safety Net could not analyze the command because it exceeds safe analysis limits. Simplify or split the command and retry.” の場合も、ルールに一致したわけではありません。パス正規化またはシェル構造の固定された上限を超えています。該当するのは、パス正規化の上限を使い切るほど多くのパスらしきトークンを含むコマンド、シェル関数のインライン展開が呼び出し位置 256 個という上限を超えるコマンド、heredoc の本文をパーサーが許す深さより深くネストさせたコマンドです。この上限もコンパイル時の定数で、設定では引き上げられません。コマンドを単純にするか分割して実行し直してください。
  4. 拒否の理由が “CC Safety Net failed closed because command analysis failed unexpectedly. This is not caused by your command. Report it to the user.” の場合は、上限の超過ではなく内部的な不具合です。コマンドを書き直しても解決しません。理由の文面どおり、そのまま報告してください。
  5. 拒否の理由が “CC Safety Net could not use the requested working directory because it does not exist, is inaccessible, is not a directory, or uses an unsupported path form. Use an existing accessible working directory. If the requested directory is missing, create it from an accessible location before retrying the command.” の場合、コマンドは解析されていません。Amp Code のシェル呼び出しで dir を解決できなかったときに出ます。すでに存在するディレクトリを指定するか、存在しないディレクトリをアクセスできる場所から作成したうえで、実行し直してください。
  6. 拒否の理由が次の文面の場合、エージェントが cc-safety-net policy apply を実行しようとしています。
    提案の適用はガードが強制しているポリシー自体を書き換えるため、このブロックは意図的なもので、解除する手段はありません。npx cc-safety-net policy apply <file> はターミナルで自分で実行してください。policy check は許可されたままなので、エージェントは提案による変更内容を提示できます。この判定は意図的に広めに一致するため、同じコマンドの npx、bunx、pnpm dlx、npm exec、bun/node 経由の形式でも発生します。
  7. 状況に応じて、次の選択肢を検討してください。
    • linked worktree で作業していませんか？ policy.json の workflow.worktree_mode か CC_SAFETY_NET_WORKTREE=1 で worktree モードを有効にします。使い捨ての独立した作業環境である linked worktree 内での実行だと確認できた場合にかぎり、ローカル破棄のルールが緩和されます。
    • より安全な書き方はありませんか？ たとえば git push --force-with-lease は許可されており、追加の安全確認付きで --force と同じ結果を得られます。git clean -n（ドライラン）も許可されており、何が削除されるかを事前に確認できます。
    • 本当にそのコマンドが必要ですか？ エージェントの外で自分で実行するという選択肢は、常に残されています。ブロック時にも、CC Safety Net はユーザーに実行を依頼するようエージェントに指示します。
検証できないルールの設定元は破棄されます。コマンド自体は動き続けますが、その設定元のルールは適用されず、ランタイムは degraded を報告します。この種の失敗は問題のないセッションでは気づきにくいため、ルール設定を変更したときとアップグレードのたびに確認してください。検証に成功した他のスコープと、組み込みの保護はすべて適用され続けます。失敗とフォールバックの詳細は、設定の復旧にあります。対処手順：
  1. npx cc-safety-net status で判定を確認し、npx cc-safety-net doctor で理由の全文を確認します。拒否された設定元とその条件が示されます。
  2. npx -y cc-safety-net rule list を実行し、実際に有効な設定元とルール、および Issues と Warnings を確認します。続けて npx -y cc-safety-net rule verify で rulebook の構造を検証します。
  3. ファイルの置き場所が正しいか確認します。
    • ユーザースコープ：~/.cc-safety-net/rules/rule.json（rule init --global で作成）
    • プロジェクトスコープ：プロジェクトルートの .cc-safety-net/rules/rule.json
  4. rule.json と rulebook の JSON ファイルが、有効な JSON になっているか確認します。よくある間違いは、末尾の余分なカンマと、引用符で囲まれていないキーです。rule.json が読み取れないと、transparent_wrappers を含めてそのスコープ全体が破棄されます。
  5. rule.json に "version": 1、各 rulebook.json に "rulebook_version": 1 があることを確認します。どちらも必須です。
  6. rulebook を編集しても以前の動作が続く場合、そのスコープが読み込まないファイルを編集しています。どの設定元も <rules dir>/<rulebook name>/rulebook.json から読み込まれます。この名前は rule.json の設定元の記述に由来し、このファイルへの編集は保存した時点で、次のツール呼び出しから適用されます。別途反映させる手順はありません。npx -y cc-safety-net rule list で各スコープが実際に読み込んだ設定元と rulebook 名を確認し、編集したファイルがその名前の下にあるか確かめてください。あわせて、rule.json の overrides でそのルールが無効になっていないかも確認します。別の設定元がすでに使っている rulebook 名は警告付きで無視されるため、そのルールはまったく読み込まれません。
  7. 以前のインライン設定（.safety-net.json または ~/.cc-safety-net/config.json）を使っていた場合は、npx -y cc-safety-net rule migrate を実行して新しい構成に変換します。未移行の旧ファイルにあるルールは、移行するまで何も保護しません。
  8. rulebook の設定元を変更した後は、npx -y cc-safety-net rule verify を実行して検証し直します。再構築の手順はありません。rule verify はガードと同じ方法で各スコープを読み込み直すため、誤って成功と報告することはなく、問題が残っていればその診断とともに失敗します。リモートの設定元については、npx -y cc-safety-net rule update が取得し直して取り込み済みの rulebook.json を上書きするため、そのファイルへのローカルの編集は失われます。
これらの操作は、ランタイムが degraded の間もすべて実行できます。設定できないことを理由にブロックされるものはありません。
degraded は、候補となった設定が拒否され、代わりに安全なものが適用されていることを示します。破棄されたルールの設定元、rulebook 名の重複、無効な policy.json が救済後の値や安全側の既定値に戻った場合などが該当します。これを理由に通常の作業が拒否されることはありません。対処手順：
  1. npx cc-safety-net doctor を実行します。config.runtime-degraded の項目に、拒否されたファイルと条件を示す理由の全文があります。
  2. ルールの設定元が原因の場合は、理由が示す修復をそのまま実施します。config.runtime-degraded の fix hint は次のとおりです。
    rulebook が無効、または名前が一致しない場合、理由は fix that file で終わります。ローカルの rulebook が見つからない場合は create that file or remove that source from the rules config で終わります。リモートの rulebook が見つからない場合は、cc-safety-net rule update を実行してその設定元を取り込むよう指示して終わります。修正後は npx -y cc-safety-net rule verify で確認してください。
  3. policy.json が原因の場合は、自分でファイルを修正してください。ランタイムが書き換えることはありません。拒否されたセクションは安全側の既定値に戻るため、通常は設定したつもりより拒否が増えることはあっても減ることはありません。例外は無効な safety.level で、この場合は standard に戻るため保護が弱くなります。
  4. npx cc-safety-net status を実行し直し、判定が ready になったことを確認します。
失敗とフォールバックの一覧は、設定の復旧を参照してください。
以前のバージョンが作成した rule.lock ファイルや cache ディレクトリがいずれかのスコープに残っていると、doctor は info 重大度の finding config.v2-leftovers（タイトルは Rulebook lock and cache leftovers detected）を報告します。detail には見つかったパスが並びます。これらのファイルはもう読み込まれません。ランタイムは各 rulebook.json を直接読み込むため、この finding は情報提供にとどまります。判定は ready のままで、設定したルールはすべて適用され続けます。fix hint は次のとおりです。
rule sync は非推奨で、これ以外の働きはありません。ネットワークにはアクセスせず、記録されたダイジェストと一致するキャッシュ済みの rulebook を、その設定元が読み込むライブファイルの位置にコピーしたうえで、ロックとキャッシュを削除します。残りの出力内容と、実行を中止する条件は rule sync を参照してください。
ステータスラインを表示するには、~/.claude/settings.json に設定が必要です。表示されない場合、その設定がない、内容が誤っている、あるいは誤った実行方法を指している可能性があります。対処手順：
  1. ~/.claude/settings.json を開き、statusLine の項目があることを確認します。形式は次のいずれかです。
  2. このファイルの変更は即座に反映されます。Claude Code を再起動する必要はありません。
  3. claude x の形式は、ネイティブ版の Claude Code でのみ動作します。Claude Code を npm でインストールした場合は、代わりに npx か bunx を使ってください。
  4. ステータスラインのコマンドをターミナルで直接実行し、出力を確認します。
    このコマンドが失敗すると、Claude Code 内のステータスラインは空になります。
  5. ステータスラインが反映するのは、~/.claude/settings.json の enabledPlugins["cc-safety-net@cc-marketplace"] の項目だけです。CC Safety Net を手動の hook として、あるいは別のエージェントで動かしている場合は、保護が有効でも ❌ と表示されることがあります。各インジケーターの意味は、ステータスラインを参照してください。
最新のブロックルールとバグ修正を取り込むため、CC Safety Net は最新の状態に保ってください。インストール済みの連携をすべて更新する：
update は、マシンにインストール済みの連携を無効化されたものも含めて検出し、その場で更新します。対象のエージェントの CLI が見つからない連携は、スキップとして報告されます。@latest の指定は重要です。バージョンを指定しない cc-safety-net では、最新リリースではなく npx キャッシュに残った古いコピーが再実行されることがあります。対話式インストーラーで u を押した場合も、同じ更新処理が動きます。Claude Code（プラグインマーケットプレイス）：自動更新にする場合は、/plugin を開いて Marketplaces を選び、cc-marketplace を選択して auto-update を有効にします。グローバルにインストールしている場合は、パッケージマネージャーで更新してください。現在のバージョンを確認する：

​
診断情報を集めて報告する

上記の手順で解決しない場合は、報告する前に診断出力を一式そろえてください。
--json を付けると、環境、インストール済みのバージョン、hook の設定、セルフテストの結果を 1 つのスナップショットにまとめた構造化出力が得られます。
診断出力や explain の出力は、共有する前に必ず確認してください。ホームディレクトリを含む絶対パス、プロジェクト名やディレクトリ名、設定ファイルのパスが含まれます。マスク処理の対象は認識できる資格情報の形式だけなので、本物の資格情報ではなくダミーの資格情報を使って問題を再現し、貼り付ける前に内容を読んでください。
バグ（対応漏れ、誤検知、インストールの問題、ドキュメントの誤り）は、公開の GitHub Issue で報告してください。シークレットの漏えい、意図したディレクトリの外への書き込み、サプライチェーンやパッケージの完全性に関わる問題は、セキュリティポリシーに記載した非公開の経路を使ってください。
最終更新日 2026年9月1日