Claude Code Monitorツールの使い方 — WebSocketとログの監視
MonitorツールはClaudeが会話を止めずにログやコマンド出力、WebSocketの受信を監視するツールです。WebSocketソースの仕様、権限・メモリー上限、監視が終わる原因の切り分けを解説します。
Claude CodeのMonitorツールは、コマンドを裏で動かして出力を1行ずつ受け取り、会話を止めずに変化を知らせるツールです。スラッシュコマンドではなく、依頼を受けたClaudeが自分で呼び出します。Bedrock・Vertex・Foundry経由では使えず、WindowsではGit Bashが必要です。
ログの監視やCIステータスのポーリングだけでなく、WebSocketで届くイベントをそのまま受け取ることもできます。サーバー側がすでにイベントを配信している場合、Claudeはポーリング用スクリプトを書かずに直接つなぎに行けます。
Monitorツールは何を監視できるか
基本形は、Claudeが小さなスクリプトを書いてバックグラウンドで実行し、出力される行を1行ずつ受け取る使い方です。次のような依頼に使えます。
- ログファイルをtailしてエラー行が出たら知らせる
- PRやCIジョブのステータスをポーリングし、変化したときだけ報告する
- ディレクトリの変更を監視する
- 実行に時間がかかるスクリプトの出力を追い続ける
- WebSocketのフィードに接続し、届いたメッセージをそのまま報告する
会話は止まりません。監視中も普段通り作業を続けられ、イベントが来たタイミングでClaudeが割り込んで知らせます。依頼は自然文で足ります。
このログファイルを監視して、ERRORという行が出たらすぐ教えて監視を止めたいときは、Claudeに解除を頼むかセッションを終了します。サブエージェントが起動した監視は、/tasksなどからそのサブエージェントを止めたときに一緒に止まります。v2.1.257より前は、バックグラウンドのサブエージェントを止めても監視が残るバグがありました。
WebSocketソースは受信をどう扱うか
サーバーがすでにイベントをプッシュしている場合、Claudeはポーリングスクリプトの代わりにWebSocketを直接開けます。ソケット上の出来事は、イベントになるものと監視を終わらせるものに分かれます。
ソケットで起きることと扱い
テキストメッセージ
1件が1イベントです。複数行にまたがるメッセージでも1件として届きます。
バイナリメッセージ
中身は渡されません。
[binary frame, 512 bytes]のようなプレースホルダー行に置き換わります。1MiB超のメッセージ
監視が終了します。大きなペイロードが想定されるフィードは、絞り込まれた小さいフィードを購読する必要があります。
ソケットのクローズ
監視が終了し、Claudeはクローズコードを受け取ります。
WebSocketを使うときはcommandの代わりにwsパラメータを渡します。1回のMonitor呼び出しでcommandとwsは同時に指定できません。wsは次の2つのフィールドを持ちます。
| フィールド | 必須 | 内容 |
|---|---|---|
url | 必須必須 | 内容接続先。ws://またはwss://で、認証情報や空白を含まないASCII文字のみのURL |
protocols | 必須任意 | 内容ハンドシェイク時に提示するサブプロトコル名。各要素は有効なサブプロトコルのトークンで、重複不可 |
protocolsはサーバー側がサブプロトコルを求めるときだけ指定すれば足り、省略した接続もできます。
WebSocketを開く操作は専用の承認プロンプトの対象です。auto modeが有効なときは分類器が代わりに判断します。このプロンプトには「同じホストへの以後の確認を省略する」という選択肢がなく、接続のたびに確認が入ります。
監視が途中で終わるときの切り分け
Monitorは「ずっと見てくれる」ツールに見えて、実際にはどの監視にも終わる条件があります。途中で通知が止まったときは、症状から次のように当たりをつけます。
| 症状 | 当たる先 |
|---|---|
5分・30分(-pでは最長10分)ほどで止まった | 当たる先デッドライン(次節) |
| WebSocketで1件も受け取らずに終わった | 当たる先接続自体が、接続先のアドレス・ドメイン制限で拒否された(前節の注意書き) |
| 受信の途中で突然終わった | 当たる先1MiB超のメッセージ、またはソケットのクローズ |
| 何も出力せずに終了した | 当たる先v2.1.221以降は「出力なしで終了した」と通知され、以前の「stream ended」とは表示が変わる |
| Linuxでビルドを見ていたら強制終了された | 当たる先メモリー上限(後述) |
デッドラインはコマンド版もWebSocket版も共通で、既定5分・最長30分です。-pで単発のプロンプトを渡す非対話実行では最長10分になります。期限が来ると監視は終了し、Claudeは通知を1回受け取るので、まだ必要なら監視を張り直せます。TaskStopを使えば期限前でも早期にキャンセルできます。
persistentオプション(期限なしの監視)はv2.1.271で廃止され、今は必ずデッドラインが付きます。廃止の経緯とスキーマ上の食い違いはMonitorのpersistentが廃止され30分で監視が切れる理由にまとめています。
-p実行では、Claudeが張った監視が動いている間は最終結果が出ても終了を待ちます。v2.1.257より前は、結果を出した約5秒後に監視を残したまま終了するバグがありました。監視を張るスクリプトをCIで-p実行するときは、この待ちが実行時間に乗ります。
コマンド実行の権限はBashと同じ
Monitorがコマンドを実行するときは、Bashと同じ権限ルールが適用されます。Bash用に設定したallow/denyパターンはMonitorにもそのまま効きます。ルールの書き方自体はClaude Codeの/permissionsコマンドで扱っている内容と変わりません。たとえばBash(npm run *)という許可ルールは、npm run buildの出力をMonitorで監視する場面でもそのまま使えます。
ルールの書式は手元のclaudeでも確認できます(v2.1.287)。--allowedToolsのヘルプ文に、Bashのパターンをそのまま並べる例が出ています。
claude --version
# 2.1.287 (Claude Code)
claude --help
# --allowedTools, --allowed-tools <tools...>
# Comma or space-separated list of tool names to allow (e.g. "Bash(git *)
# Edit")auto modeが有効なときの扱いには注意が必要です。Monitorという名前そのものを対象にした広い許可ルールは、auto modeが他の広い許可ルールと同様に一時的に外します(v2.1.236以降)。結果として、分類器はMonitorのコマンドもBashのコマンドと同じ基準で審査します。「Monitorを全部許可」というルールを書いても、auto mode下では素通りにはなりません。分類器の評価の仕組みはClaude Codeのauto mode分類器は何を止めているかで詳しく扱っています。
承認プロンプトの見た目は、v2.1.286でBash・PowerShellと揃いました。コマンドが破線で挟まれて表示され、ファイル編集の承認画面と同じ見せ方になっています。
サンドボックスと組み合わせたauto modeでは、v2.1.271からallowed_domainsをコマンドごとに付けられます。そのコマンドが必要とするホストはコマンドと一緒に審査され、そのコマンドに限って開きます。それ以外のホストへの接続は拒否されます。ネットワークを使う監視スクリプトでも、ドメインの許可を全体に広げずに済みます。ただしdeniedDomainsに載ったホストは引き続き拒否されます。strictAllowlistやallowManagedDomainsOnlyで許可リストが固定されている環境では、コマンドごとのリストは受け付けられません。
メモリー上限はいつからMonitorにも及ぶか
Linux・WSLではCLAUDE_CODE_TOOL_MEMORY_LIMIT(v2.1.233以降)でBash・PowerShellが使えるメモリーの上限を設定できます。Monitorのコマンドがこの上限に含まれるようになったのはv2.1.246からで、それより前のバージョンではMonitorのコマンドは上限の外で動いていました。暴走したビルドが1つ、セッション全体のメモリーを食いつぶす事故を防ぐ仕組みで、いまはMonitorも同じセッションの1コマンドとして数えられます。上限は1コマンドごとではなく、セッション内のBash・PowerShell・Monitorのコマンドをまとめて数える1つの枠です。
CLAUDE_CODE_TOOL_MEMORY_CGROUP_EXCLUDE(v2.1.246以降)を使うと、上限から除外するプロセスの種類をカンマ区切りで指定できます。all-newを指定すると、Bash・PowerShell・Monitorのコマンドだけが上限の対象になり、それ以外の種類(MCPサーバーやLSPプロセスなど)は対象外になります。逆にnoneを指定すればすべての種類が上限の対象です。この3つのツールについては、除外リストに何を書いても上限の対象から外れません。
Monitorが使えない環境
Windowsでは、Git Bashがインストールされている場合に限りMonitorを使えます。Monitorツールは、Amazon Bedrock・Google Cloud's Agent Platform(旧Vertex AI)・Microsoft Foundry経由のセッションでは利用できません。DISABLE_TELEMETRYまたはCLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFICを設定している場合も同様に使えなくなります。
プラグインの側からMonitorを起動する経路もあります。プラグインが監視をあらかじめ宣言しておくと、プラグインが有効なあいだ自動的に監視が始まります。ユーザーが都度Claudeに頼まなくても、導入時点で監視が立ち上がる運用です。
Ctrl+Bのバックグラウンド実行とは何が違うか
Claude CodeにはCtrl+Bで実行中のBashコマンドを裏に回す、別のバックグラウンド実行の仕組みもあります。どちらも会話を止めずに何かを走らせ続けますが、始める人と時間制限の考え方が違います。使い分けはClaude Codeバックグラウンド実行の内容と合わせて見ると分かりやすくなります。
Monitorとバックグラウンド実行の違い
Monitorツール
Claudeが監視の必要性を判断して開始し、出力の行ごとに会話へ割り込みます。WebSocketも扱えます。期限が切れると通知が届き、必要なら張り直せます。
Ctrl+Bのバックグラウンド実行
ユーザーが実行中のBashコマンドを裏に送ります。Ctrl+Bで裏に移したコマンドは、移した時点から30分で止まります。最大2時間まで延ばせるtimeoutは、Claudeが最初からバックグラウンドで起動したコマンドにだけ効きます。
エラーを待って自動的に次の作業へ移りたいならMonitor、処理を裏に逃がして自分のペースで確認したいならCtrl+Bです。
仕様が変わった時期の一覧
Monitorまわりは2026年8月以降に挙動が何度か変わっています。以前のバージョンの記事や記憶で運用していると食い違うので、変更を版番号でたどれる形にしておきます。
Monitorまわりの変更(changelogと公式ドキュメントより)
- v2.1.236auto modeでMonitorの許可ルールを一時的に外す
Monitorのコマンドが、Bashと同じ基準で審査されるようになりました。
- v2.1.246メモリー上限の対象にMonitorが入る
それまでMonitorのコマンドは上限の外で動いていました。
- v2.1.257`-p`の待ちとサブエージェント停止を修正
-pが監視を残して早く終わる問題と、サブエージェントを止めても監視が残る問題が直りました。 - v2.1.271`persistent`廃止・デッドライン必須化
あわせてauto modeのコマンド単位の
allowed_domainsが入りました。 - v2.1.274終了時の通知を1回にまとめる
スクリプトの最終出力と終了が1つの通知で届き、モデルの1ターンぶんが節約されます。
- v2.1.286承認プロンプトの表示を統一
Bash・PowerShell・Monitorで、コマンドが破線に挟まれて表示されます。
まとめ
30分を超えて見張り続ける用途と、人が承認を挟まずに回し続けたいWebSocket監視は、Monitor単体では組めません。短い区間の異常検知を任せる使い方なら、会話を止めずに収まります。