Monitor ツール (monitor)

このドキュメントでは、Qwen Code の monitor ツールについて説明します。

説明

monitor を使用すると、長時間実行されるシェルコマンドを起動し、stdout および stderr の各行をバックグラウンドタスク通知としてエージェントにストリーミングで返します。ログの tail 、ビルド出力の監視、ヘルスエンドポイントのポーリング、ファイル変更の監視など、 時間の経過とともに新しい出力が重要になるウォッチ型コマンドを想定しています。

モニターはバックグラウンドで実行されるため、イベントが届いている間もエージェントは作業を 継続できます。空でない各出力行は、スロットリングの対象となる通知イベントになります。

引数

monitor は以下の引数を取ります。

• command (string, 必須): 実行して監視するシェルコマンド。
• description (string, 省略可能): モニターが何を監視しているかの簡単な説明。表示テキストは 80 文字に切り詰められます。
• max_events (number, 省略可能): この数の通知イベントが発生したら停止します。 正の整数でなければなりません。デフォルトは 1000、最大は 10000（この範囲外の値は 黙って丸められるのではなく、拒否されます）。
• idle_timeout_ms (number, 省略可能): コマンドがこのミリ秒数の間出力を生成しない場合に 停止します。正の整数でなければなりません。デフォルトは 300000（5 分）、最大は 600000（10 分）で、この範囲外の値は拒否されます。
• directory (string, 省略可能): コマンドを実行する絶対パス。シンボリックリンクの 正規化後に登録済みワークスペースディレクトリのいずれかの内部に解決され、 user-skills ディレクトリの内部であってはなりません。省略した場合、Qwen Code は プロジェクトルートを使用します。

Qwen Code での monitor の使い方

モデルは、単一のコマンド結果を収集するのではなく、プロセスを時間をかけて観察する必要がある 場合に monitor ツールを選択します。正常に起動すると、モニター ID、コマンド、 イベント上限、アイドルタイムアウトが返されます。

使用例:

monitor(command="tail -f logs/app.log", description="app log stream")

モニターの出力は、タスク通知としてカンバセーションに表示されます。実行中および 完了済みのモニターは、/tasks またはインタラクティブな「Background tasks」ダイアログで 確認することもできます。

実行中のモニターを停止するには、モニター ID を指定して task_stop ツールを使用します。

task_stop(task_id="mon_abc123def4567890")

monitor の使用例

アプリケーションログを監視する:

monitor(
  command="tail -f logs/app.log",
  description="application log stream",
  max_events=200
)

開発サーバーまたはビルドウォッチャーを監視する:

monitor(
  command="npm run build -- --watch",
  description="watch build output",
  idle_timeout_ms=600000
)

ローカルのヘルスエンドポイントをポーリングする:

monitor(
  command="while true; do curl -s http://localhost:8080/health; sleep 5; done",
  description="local health check",
  max_events=120
)

特定のワークスペースディレクトリで実行する:

monitor(
  command="npm run dev",
  description="frontend dev server",
  directory="/absolute/path/to/workspace/packages/web"
)

Monitor とバックグラウンドシェルコマンドの比較

コマンドが実行し続けている間、エージェントがストリーミング出力に反応する必要がある場合は monitor を使用してください。一度きりの結果やコマンド出力の全体が必要な場合は、 代わりに run_shell_command を使用してください。

monitor コマンドに & を追加しないでください。tail -f log & のように末尾に & が ある場合は除去されます。monitor はバックグラウンド化を自分で管理するためです。 cmd1 & cmd2 のように末尾以外に & がある場合は直ちに拒否されます。そのような コマンドはバックグラウンド化なしで再構成してください。

重要な注意事項

• 自動停止の動作: モニターは max_events に達したとき、出力なしに idle_timeout_ms が経過したとき、または基盤となるコマンドが自ら終了したときに自動的に停止します。 モニターのステータスはツールエラーではなくコマンドの結果を反映します。正常終了（code 0） は completed になり、ゼロ以外の終了コードはメッセージ Exit code N とともに failed になり、シグナルによる終了はメッセージ Killed by signal SIG とともに failed になります。コマンドは stdin がクローズされているため、インタラクティブに 使用できません。モニターが停止すると、Qwen Code はコマンドのプロセスグループに SIGTERM を送信し、約 200 ms 後に SIGKILL にエスカレートします。Windows では taskkill /f /t を使用します。Qwen Code プロセス自体がハードキルされたり、クラッシュ したり、メモリ不足になったりした場合、デタッチされたプロセスグループは自動的に クリーンアップされません。終了前に task_stop でモニターを停止するか、 手動でプロセスグループを終了してください。
• 同時実行数の制限: Qwen Code は CLI セッションごとに最大 16 個の実行中モニターを 1 つの共有プールとして許可します。サブエージェントが起動したモニターも、メインエージェントが 起動したモニターと同じ上限にカウントされます。上限に達した場合は、新しいモニターを 起動する前に既存のモニターを停止してください。
• 出力処理: stdout と stderr はストリームプレフィックスなしで 1 つの通知ストリームに マージされます。空行は無視され、ANSI カラーおよびコントロール文字は除去され、 2000 文字を超える行は切り詰められます。大量出力はバースト 5 イベント、その後毎秒 約 1 イベントのレート制限が適用されます。レート制限を超えた行はバッファリングされずに 破棄されます。モニター出力はエージェントのコンテキストに <task-notification> コンテンツ として流れ込みます。構造的な通知タグは無害化されますが、モデルは各行のテキストを 読み取るため、外部の当事者が書き込める可能性のあるストリームを監視する場合は、 埋め込まれた指示をモデルが無視することを信頼できない限り避けてください。
• パーミッション: monitor には独自のパーミッション境界とパーミッションルールがあります （例: Monitor(git status)）。読み取り専用コマンドは自動的に許可されます。 状態を変更するコマンドはユーザーの承認が必要です。コマンド置換（$(...), バッククォート, <(...), >(...)）を含むコマンドは直ちに拒否されます。 run_shell_command に対する tools.core および tools.exclude 設定は monitor には適用されません。
• ワークスペース制限: オプションの directory は、登録済みワークスペースディレクトリの 内部かつ user-skills ディレクトリの外部に解決される絶対パスでなければなりません。 ワークスペース外を指すシンボリックリンクは拒否されます。