Command Queue を使ったエージェント実行の効率化

ユーザーからメッセージが立て続けに届いたとき、エージェントが同時に複数のレスポンスを返そうとして混乱したことはありませんか？LLMの呼び出しが重なると、レート制限にかかったり、セッションファイルが衝突したりと、予期せぬトラブルの原因になります。

こうした競合を避け、安定した動作を実現するために、インバウンドの実行をシリアライズ（直列化）して管理する仕組みが重要です。

必要なもの

この機能を利用するには、以下の環境が必要です。

runEmbeddedPiAgent を使用している環境
Gateway リプライパイプライン（WhatsApp web, Telegram, Slack, Discord, Signal, iMessage, webchat など）を利用するインバウンドチャンネル

クイックスタート

デフォルトでは、すべてのチャンネルで collect モードが有効になっており、特別な設定なしですぐに利用できます。設定をカスタマイズしたい場合は、messages.queue セクションを編集してください。

{
  messages: {
    queue: {
      mode: "collect",
      debounceMs: 1000,
      cap: 20,
      drop: "summarize",
      byChannel: { discord: "collect" },
    },
  },
}

特定のセッションで動作を一時的に変更したい場合は、チャット上で直接コマンドを送信することも可能です。

/queue collect を送信してモードを切り替える
/queue reset でデフォルト設定に戻す

仕組みとおすすめの設定

このシステムは、lane-aware（レーン認識型）の FIFO キューとして動作します。各セッションは個別のレーン（session:<key>）に割り当てられるため、同一セッション内では一度に一つのエージェント実行のみが許可されます。

キューモードの選択

メッセージが届いた際の挙動を制御するモードがいくつか用意されています。

collect (推奨): キューに入っているすべてのメッセージを、一つの followup ターンにまとめて処理します。
steer: 現在の実行に割り込み、即座に内容を注入します。ストリーミング中でない場合は followup にフォールバックします。
followup: 現在の実行が終わった後、次のターンとしてキューに入れます。
steer-backlog: 割り込み（steer）を行いつつ、そのメッセージを次回の followup 用にも保持します。

1つのメッセージに対して1つのレスポンスを返したい場合は、collect か steer を選ぶのがベストな選択です。

細かな制御オプション

キューの挙動をさらに最適化するためのオプションが用意されています。

debounceMs: メッセージが途切れるのを待ってから処理を開始します。これにより「続けて送信」された際の無駄な実行を防ぎます。
drop: キューが上限（cap）に達した際の処理を決めます。summarize を選択すると、破棄されたメッセージの要約を箇条書きで次のプロンプトに挿入してくれます。

トラブルシューティング

キューに関連して動作が不安定だと感じたときは、以下の手順を試してください。

コマンドが反応しない場合: verbose ログを有効にしてください。ログの中に “queued for …ms” という行があれば、キューが順番待ちをしている状態だと確認できます。
待ち時間を知りたい場合: 同じく verbose ログを確認することで、実行までにどれくらいの時間キューに滞留していたかを把握できます。

AI Setup Assistant

次のステップ

OpenClaw Expert

まだ解決しませんか？

このページで解決しない場合は、OpenClaw Expertに直接質問してください。