Claude Code HooksがリモートMacで実行されない場合は？2026年版トラブルシューティングガイド

Hookを設定したのに、SSH接続したリモートMacでClaude Codeのチェック処理が走らない。
まずイベントとmatcherの一致を確かめ、次にスクリプトの実行権限、SSH環境変数と作業ディレクトリ、最後に終了状態とHook出力を確認してください。

【適している人】SSH経由でClaude Codeを使い、Hookが動かない原因を実行経路に沿って調べたい開発者向けです。
プロジェクト共通のHook設定を管理するエンジニアや、macOS上でフォーマット・テスト・ビルドを自動実行したい担当者にも役立ちます。
設定変更の前に、使用中のClaude Codeのバージョン、接続方法、再現操作を記録してください。

Claude Code HooksがリモートMacで動かないときは、実行段階を分けて調べる

「Hookが動かない」は、イベントが起きていない、イベントは起きたがmatcherが一致しない、コマンドを起動できない、起動したものの期待した結果にならない、という別々の状態を含みます。最初に、Hookが書き込むだけの目印を用意し、該当操作を一度だけ行って、どの段階まで進んだかを確認します。

printf 'hook-start\n' >> /tmp/claude-hook-check.log
pwd
command -v sh

この確認では、Hookから参照できる作業ディレクトリとシェルの位置を記録できます。目印ファイルが作られない場合はイベント・matcher・起動を調べ、作られる場合はスクリプトの出力や処理結果に進みます。プロジェクト設定とユーザー設定の適用範囲も分けて確認してください。設定形式と有効なHookイベントは、Claude CodeのHookリファレンスで照合できます。

イベントとmatcherが操作に合っているか確認する

Claude Code Hooksが呼び出されるのは、設定したイベントが発生し、必要な条件に一致した場合です。たとえばツール実行に関係するHookでは、選んだイベントとmatcherの組み合わせが実際のツール操作に合っているかを見ます。ファイルを保存したつもりでも、設定したイベントがその操作を対象にしていなければ起動しません。

Hook設定を小さくし、副作用のない記録だけを行うコマンドで切り分けてください。設定の構造やイベントごとの入力・出力は、公式Hookガイドとイベントの詳細を参照し、現在の設定と照合します。

matcherの値を広げるだけで済ませず、まず実際に発生したイベントと対象ツールを確認してください。範囲を無制限に広げると、意図しない操作までHook対象になる可能性があります。

注意：原因が特定できるまでは、ファイル削除や外部送信を含む処理をテスト用Hookに入れないでください。診断には記録や読み取りだけの処理を使います。

スクリプトのパス、shebang、実行権限をリモート側で確認する

設定に書かれたパスが、SSH先のMacにも存在するとは限りません。ローカル端末では動く相対パスや、ログインシェルで補われるコマンド名が、Hookの実行時には解決できないことがあります。

ls -l /absolute/path/to/hook.sh
head -n 1 /absolute/path/to/hook.sh
test -x /absolute/path/to/hook.sh && echo executable || echo not-executable

確認するのは、対象ファイルの存在、shebangが指すインタープリターの有無、実行権限です。実行権限がない場合は、対象ファイルだけに必要な権限を付与し、広い範囲への一括変更は避けます。コマンドHookの設定例や入力方式は、公式のHook設定例と現在の設定ファイルを見比べてください。

SSH環境変数と作業ディレクトリの差を確認する

SSH接続後の対話型ターミナルで成功しても、Claude CodeがHookを起動する条件まで同じとは限りません。特にPATH、必要な環境変数、カレントディレクトリ、パッケージ管理ツールやプロジェクト内スクリプトの実際の配置を確認します。SSH環境変数の差を疑う場合は、端末とHookの両方で必要最小限の値を記録し、秘密情報を含む環境全体の出力は避けてください。

printf 'PATH=%s\n' "$PATH"
printf 'PWD=%s\n' "$PWD"
command -v xcodebuild

command -vが空なら、Hook側のPATHからそのコマンドを見つけられていません。診断結果に合わせて、Hook内で必要な実行ファイルの絶対パスを使うか、必要なPATHだけを設定します。シェル起動時に読み込まれる設定がHookでも使われると決めつけず、実行時の値を確かめてください。

なお、Claude Codeの環境変数の扱いは公式環境変数リファレンスを、設定の置き場所と適用範囲は公式設定ガイドを確認します。遠隔Mac開発環境では、接続ユーザーや起動経路によって作業ディレクトリが異なる場合もあるため、スクリプト内でpwdを記録すると見分けやすくなります。

終了状態とデバッグログで、実行後の不一致を調べる

Hookの開始を確認できたら、標準出力、標準エラー、終了コードを分けて記録します。スクリプト内部のエラーと、Claude CodeがHookの返却内容を扱う段階の不一致は、ログを分けないと混同しやすいためです。

/path/to/hook.sh
printf 'exit=%s\n' "$?"

Hookが返す内容が会話に表示されるか、ログだけに記録されるかは、イベントと返却形式によって確認が必要です。出力先やデバッグ方法は、設定デバッグの公式説明とHookリファレンスを参照してください。必要に応じてClaude Codeのデバッグ表示を有効にし、対象操作の直後にログを確認します。

設定変更後は、まず読み取り中心の診断を再実行し、その後にプロジェクトのフォーマット、テスト、ビルドなど実際の処理で確認します。フックが意図しないファイルを変更しないか、失敗時に処理がどう終わるかも確認してください。権限を広げて回避するのではなく、Hookに必要な範囲を限定する方法は公式セキュリティガイドと権限設定の説明に沿って判断します。

手元のSSH環境で問題が解消するなら、まずその設定を記録して再現性を確保してください。一方、macOS専用のツールチェーンを安定して使える実行先が必要なら、ローカルMacへの依存は端末の稼働状況や個別のPATH設定、作業場所の違いが運用上の負担になります。実際のmacOS環境が必要な開発では、リモートMacを選ぶとその環境を離れた場所から利用できます。OakVMのリモートMacの比較情報と日本向けMac環境の案内を確認し、常時運用の要否やチームの設定管理に合うかを検討してください。 Hookの安全な設定と保守は、利用する環境にかかわらずプロジェクト側で続ける必要があります。