モニターツール (monitor)

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

説明

monitor を使用すると、長時間実行されるシェルコマンドを起動し、その stdout と stderr の行をバックグラウンドタスク通知としてエージェントにストリーミングできます。これは、ログの tail、ビルド出力の監視、ヘルスエンドポイントのポーリング、ファイル変更の監視など、新しい出力が時間とともに重要になる watch スタイルのコマンドを対象としています。

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

引数

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

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

Qwen Code で monitor を使用する方法

モデルは、単一のコマンド結果を収集するのではなく、プロセスを時間をかけて監視する必要がある場合に monitor ツールを選択します。呼び出しが成功すると、モニター ID、コマンド、イベント制限、およびアイドルタイムアウトが返されます。

使用例:

monitor(command="tail -f logs/app.log", description="アプリログストリーム")

モニターの出力は、会話内でタスク通知として表示されます。また、/tasks またはインタラクティブな「バックグラウンドタスク」ダイアログを使用して、実行中および完了したモニターを確認できます。

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

task_stop(task_id="mon_abc123def4567890")

monitor の例

アプリケーションログの監視:

monitor(
  command="tail -f logs/app.log",
  description="アプリケーションログストリーム",
  max_events=200
)

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

monitor(
  command="npm run build -- --watch",
  description="ビルド出力の監視",
  idle_timeout_ms=600000
)

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

monitor(
  command="while true; do curl -s http://localhost:8080/health; sleep 5; done",
  description="ローカルヘルスチェック",
  max_events=120
)

特定のワークスペースディレクトリから実行:

monitor(
  command="npm run dev",
  description="フロントエンド開発サーバー",
  directory="/absolute/path/to/workspace/packages/web"
)

モニター vs. バックグラウンドシェルコマンド

monitor は、コマンドが実行を継続している間にエージェントがストリーミング出力に反応する必要がある場合に使用します。単発の結果や完全なコマンド出力が必要な場合は、代わりに run_shell_command を使用します。

モニターコマンドに & を追加しないでください。tail -f log & のような末尾の & は、モニター自体がバックグラウンド実行を管理するため削除されます。cmd1 & cmd2 のような途中の & は完全に拒否されます。代わりにバックグラウンド実行を使用せずにコマンドを再構築してください。

重要な注意事項

• 自動停止の動作: モニターは、max_events に達した場合、idle_timeout_ms が経過しても出力がない場合、または基になるコマンドが自身で終了した場合に自動的に停止します。モニターのステータスはツールエラーではなくコマンドの結果を反映します。正常終了（終了コード0）は completed に、0以外の終了コードはメッセージ 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個の実行中モニターを単一の共有プールとして許可します。サブエージェントによって開始されたモニターも、メインエージェントによって開始されたモニターと同じ上限にカウントされます。制限に達した場合は、別のモニターを開始する前に既存のモニターを停止してください。
• 出力処理: stdout と stderr はストリームプレフィックスなしで単一の通知ストリームにマージされます。空行は無視され、ANSI カラーおよび制御文字は除去され、2000文字を超える個々の行は切り詰められます。大量の出力は、5イベントのバーストとその後1秒あたり約1イベントでレート制限されます。レート制限を超えた行はドロップされ、バッファリングされません。モニター出力は <task-notification> コンテンツとしてエージェントコンテキストに流れ込みます。構造化通知タグは無害化されますが、モデルは各行のテキストを読み取るため、外部の第三者が書き込み可能なストリームを監視することは、埋め込まれた指示をモデルが無視することを信頼できる場合を除き避けてください。
• 権限: monitor には独自の権限境界と権限ルール（例: Monitor(git status)）があります。読み取り専用コマンドは自動的に許可されます。状態を変更するコマンドはユーザーの承認が必要です。コマンド置換（$(...)、バッククォート、<(...)、>(...)）を含むコマンドは完全に拒否されます。run_shell_command の tools.core および tools.exclude 設定は monitor には適用されません。
• ワークスペース制限: オプションの directory は、登録されたワークスペースディレクトリ内にあり、かつ user-skills ディレクトリ外にある絶対パスである必要があります。ワークスペース外を指すシンボリックリンクは拒否されます。