Claude Codeを始めたばかりの方へ: hookを設定したけど動いている気配がない、という方のためのトラブルシューティングガイドです。1つずつ確認すれば、ほとんどの問題は解決します。
「hookを設定したのに動かない」。Claude Code hookの一番よくある問題だ。
この記事では、hookが動かない原因を5分以内に特定する方法を紹介する。
まず試す: --doctor
npx 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 cc-safe-setup --uninstall
npx 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 cc-safe-setup --doctor
# 2. 問題なければ再起動
# Claude Codeを終了して再起動
# 3. それでもダメなら再インストール
npx cc-safe-setup --uninstall
npx cc-safe-setup
hookが動く状態を確認してから設定を追加していくのが確実。
- Anthropic公式「Skills完全ガイド」を読んだら、SKILL.mdのトークン消費を40%減らせた
- Claude CodeのPreToolUseフックで危険な操作を自動ブロックする
-
Claude Codeを108時間無人で走らせて起きた全事故と、そこから作った安全装置
📘 Anthropic公式ガイドにない事故防止——Claude Code 800+時間で19点→85点にした全記録
関連記事
- 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 cc-safe-setup（ユーザーレベル設定で免疫）→ 詳細
📚 主張と実態の乖離の事例の整理と防衛の手順 (2026 年 5 月 22 日発売)
本記事の「hook を設定したのに動かない」 は、 利用者の意図 (防衛の発火) と実態 (hook の沈黙) の乖離の中核の系統。 設定の場所、 文体、 マッチャの不一致、 失敗の沈黙化の4件の原因の整理は、 本書の第8章の防衛の手順の前提と整合。 本書は同型の「設定したのに発火しない」 系統の事例を、 settings.json、 CLAUDE.md、 /config、 子の代理の前段、 memory の5つの場所に分散する形で整理。
5/22 発売の Claude Code Claim-Verify Handbook で、 同型の主張と実態の乖離の事例を 130 件 (本文 15 件 + 付録 D 115 件) に整理した試し読み (無料、 約 9,900 字、 日本語) を公開済。 14 件の防衛の手順と 5 件の自動の点検の道具 (4 件は cc-safe-setup の枝で取り込み待機、 1 件は本書の付録の標準の道具、 合計 165 件以上の試験が全件通過) も収録。
購入の検討の判断の助け (Should I buy the Claim-Verify Handbook?) の対話型の道具で、 無料の hook の解説で十分の場合の判定の経路も整理しています。