Claude Codeのhookが動かない——5分で原因を特定する診断ガイド

Last updated at 2026-08-27Posted at 2026-03-27

Claude Codeを始めたばかりの方へ: hookを設定したけど動いている気配がない、という方のためのトラブルシューティングガイドです。1つずつ確認すれば、ほとんどの問題は解決します。

「hookを設定したのに動かない」。Claude Code hookの一番よくある問題だ。

この記事では、hookが動かない原因を5分以内に特定する方法を紹介する。

まず試す: --doctor

npx github:yurukusa/cc-safe-setup --doctor

13項目を自動チェックする:

jqがインストールされているか
settings.jsonが存在し、有効なJSONか
hooks セクションが設定されているか
各hookスクリプトが存在するか
実行権限があるか
shebangがあるか（スクリプト先頭の#!/bin/bashのこと。OSに「このファイルをどのプログラムで実行するか」を伝える行）
空入力でエラーにならないか

ほとんどの問題はこれで見つかる。

よくある原因ベスト5

1. jqがない

:::details 初心者向け: jqとは
jqは、JSON形式のデータを読み取り・加工するためのコマンドラインツールです。hookはClaude Codeから「今から何をしようとしているか」という情報をJSON形式で受け取ります。jqがないとその情報を読めないので、hookは何もできません。
:::

:::details 初心者向け: stdinとは
stdin（標準入力）とは、プログラムが外部からデータを受け取る入り口のことです。郵便受けのようなもので、Claude Codeが「今からこのコマンドを実行しようとしています」という情報をJSON形式で郵便受けに入れ、hookスクリプトがそれを取り出して中身を確認します。
:::

hookはstdinからJSONを受け取り、jqでパースする。jqがないと何も動かない。

# 確認
which jq

# インストール
brew install jq      # macOS
apt install jq       # Ubuntu/Debian
choco install jq     # Windows

2. スクリプトに実行権限がない

:::details 初心者向け: 実行権限とは
Linux/macOSでは、ファイルに「このファイルはプログラムとして実行できます」という許可（実行権限）を明示的に付ける必要があります。実行権限がないと、スクリプトの中身が正しくても「Permission denied」で動きません。
:::

# 確認
ls -la ~/.claude/hooks/

# 修正
chmod +x ~/.claude/hooks/*.sh

3. settings.jsonのJSON構文エラー

手動で編集してカンマを忘れた、など。JSONは文法に厳格で、カンマ1つ忘れただけでファイル全体が読めなくなる。日本語の文章で句読点を忘れても意味は通じるが、JSONではそうはいかない。

# 確認
python3 -m json.tool ~/.claude/settings.json

# エラーが出たら
npx github:yurukusa/cc-safe-setup --uninstall
npx github:yurukusa/cc-safe-setup

4. Claude Codeを再起動していない

hookはClaude Code起動時に読み込まれる。settings.jsonを変更したら再起動が必要。

5. Windowsでの起動オーバーヘッド

Windows環境でPythonスクリプトのhookを使っている場合、Pythonの起動に200-500msかかる。hookにタイムアウトがあるため、軽いスクリプト（bash）は100%発火するのに、重いスクリプト（Python）は18%しか発火しないという現象が起きる。

対策: Pythonの代わりにbashを使う。

#!/bin/bash
# Pythonの代わり
INPUT=$(cat)
VALUE=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
# ... bashで処理

hookの発火を確認する方法

#!/bin/bash
# hook-test.sh — hookに追加して発火を記録
echo "[$(date)] Hook fired: $0" >> /tmp/hook-fire.log

これをhookの先頭に追加して、Claude Codeでコマンドを実行し、/tmp/hook-fire.logを確認する。

正しいsettings.json構造

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/my-hook.sh"
          }
        ]
      }
    ]
  }
}

よくある間違い:

"type": "command" を忘れる
"matcher" のスペルミス
hookの配列構造が間違っている（hooks内にhooks）

まとめ

# 1. 診断
npx github:yurukusa/cc-safe-setup --doctor

# 2. 問題なければ再起動
# Claude Codeを終了して再起動

# 3. それでもダメなら再インストール
npx github:yurukusa/cc-safe-setup --uninstall
npx github:yurukusa/cc-safe-setup

hookが動く状態を確認してから設定を追加していくのが確実。

Anthropic公式「Skills完全ガイド」 — SKILL.mdの設計パターン
PreToolUseフックで危険な操作を自動ブロックする — hookの具体的な実装
108時間無人で走らせて起きた全事故と安全装置 — 長時間運用の実事故

「AIに任せて大丈夫なのか」という不安を持ったまま800時間使い続けた記録は非エンジニアがClaude Codeを800時間走らせた——失敗と学びの全記録（¥800・第2章まで無料）に書いた。

📖 トークン消費に困っているなら → Claude Codeのトークン消費を半分にする——800時間の運用データから見つけた実践テクニック（¥2,500・はじめに+第1章無料）

⚠ Opus 4.7緊急情報（2026年4月）
auto modeの安全分類器がOpus 4.6にハードコードされており、Opus 4.7では正常に機能しない（#49618）。hookはモデル非依存で動作するため、分類器の故障に関係なく防御が機能する。→ Opus 4.7 Survival Guide / Safety Scanner

⚠️ CVE-2026-21852（2026年4月公開）: プロジェクト内.claude/settings.json経由でAPIキー窃盗。対策: npx github:yurukusa/cc-safe-setup（ユーザーレベル設定で免疫）→ 詳細

📚 主張と実態の乖離の事例の整理と防衛の手順 (2026 年 5 月 22 日発売)

本記事の「hook を設定したのに動かない」は、利用者の意図 (防衛の発火) と実態 (hook の沈黙) の乖離の中核の系統。設定の場所、文体、マッチャの不一致、失敗の沈黙化の4件の原因の整理は、本書の第8章の防衛の手順の前提と整合。本書は同型の「設定したのに発火しない」系統の事例を、 settings.json、 CLAUDE.md、 /config、子の代理の前段、 memory の5つの場所に分散する形で整理。

📚 関連の参考資料 (2026年5月28日追加)

本記事の内容と関連する整理を、公開済の素材で articulate しています。

6月15日に予定された課金分離(当日に一時停止・再実施に備える)の判定の枠組み: Migration Playbook v2 (Gumroad、 $19) ——14日後の決定の整理、 9集積の文脈、 130件の claim-verify divergence の事例。 60秒の購入判定の道具で事前判定が可能
月次の追補の継続: Claude Code 事故まとめ(無料・月次) ——5月から12月の8ヶ月の章本文 (cache_control / 副の作業者 / AGENTS.md / Pro Max / 権限 / Skills / v2.1.150 / AUP false-positive)
9集積の枠組みの英語の長編 Gist: The 9-Cluster Framework: Mapping the Structural Failure Surface of Claude Code Operator Defense ——約3,300単語、全件の集積の mechanism / symptom family / defense path の整理。 cluster 9 (Usage Policy classifier over-trigger on Opus、 25+件の起票) の対話型診断道具: 4問の質問→推奨経路の道具
約800件の MIT ライセンスの hook: cc-safe-setup (GitHub) ——9集積に対応する hook を整備した累計

ほかにも、800時間の運用データから、トークン消費の削減・複数ベンダー(Claude / Codex / Gemini / Copilot)の並行運用・サブエージェントの沈黙の失敗対策など、テーマ別の手引きを公開しています。気になる人は著者の本の一覧から、価格と評価を見て選べます。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up