OpenClawのメッセージフローとデバウンス設定を最適化する

複数のチャットプラットフォームを統合してAIエージェントを運用する際、メッセージの重複やユーザーによる連投、リアルタイムなレスポンスの制御など、開発者が直面する課題は少なくありません。OpenClawがこれらの複雑なメッセージ処理をどのように支えているのか、その仕組みを詳しく解説します。

OpenClawが受信メッセージ、セッション、キューイング、ストリーミング、そして推論プロセスの可視化をどのように処理しているか、全体像を見ていきましょう。

メッセージフロー（ハイレベル）

Inbound message
  -> routing/bindings -> session key
  -> queue (if a run is active)
  -> agent run (streaming + tools)
  -> outbound replies (channel limits + chunking)

主要な設定項目は configuration 内にあります：

• messages.*: プレフィックス、キューイング、グループの挙動設定。
• agents.defaults.*: ブロックストリーミングとチャンキングのデフォルト設定。
• Channel overrides (channels.whatsapp.*, channels.telegram.* など): 上限設定やストリーミングの切り替え。

詳細は Configuration のスキーマを確認してください。

受信メッセージの重複排除

再接続時などに、チャネル側から同じメッセージが再度送信されることがあります。OpenClawは、チャネル、アカウント、ピア、セッション、メッセージ IDをキーとした短期間のキャッシュを保持しています。これにより、重複したメッセージが届いても、エージェントが二重に実行されるのを防ぎます。

受信メッセージのデバウンス

同一の送信者から短時間に連続してメッセージが届いた場合、messages.inbound の設定によって、それらを1回のエージェント実行にまとめることができます。デバウンスはチャネルと会話ごとに適用され、リプライのスレッドやIDには最新のメッセージが使用されます。

設定例（グローバルデフォルト + チャネルごとの上書き）：

{
  messages: {
    inbound: {
      debounceMs: 2000,
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
        discord: 1500,
      },
    },
  },
}

注意点：

• デバウンスはテキストのみのメッセージに適用されます。メディアや添付ファイルは即座に処理されます。
• コントロールコマンドはデバウンスをバイパスし、常に単独で実行されます。

セッションとデバイス

セッションはクライアントではなく、Gateway が所有します。

• ダイレクトチャットは、エージェントのメインセッションキーに集約されます。
• グループやチャネルには、それぞれ独自のセッションキーが割り当てられます。
• セッションストアと履歴（transcripts）は Gateway ホスト上に保存されます。

複数のデバイスやチャネルを同じセッションに紐付けることができますが、履歴がすべてのクライアントに完全に同期されるわけではありません。コンテキストの不一致を避けるため、長い会話には1つのメインデバイスを使用することをお勧めします。Control UI と TUI は常に Gateway 側のセッション履歴を表示するため、これらが「信頼できる唯一の情報源（Source of Truth）」となります。

詳細は Session management を参照してください。

受信ボディと履歴コンテキスト

OpenClawは、プロンプトボディとコマンドボディを分けて管理しています。

• Body: エージェントに送信されるプロンプトテキスト。チャネルの情報やオプションの履歴ラッパーが含まれる場合があります。
• CommandBody: 指示やコマンドの解析に使用される、ユーザーからの生テキスト。
• RawBody: CommandBody の古いエイリアス（互換性のために維持）。

チャネルが履歴を提供する場合、以下の共有ラッパーが使用されます：

• [Chat messages since your last reply - for context]
• [Current message - respond to this]

ダイレクトチャット以外（グループ、チャネル、ルーム）では、現在のメッセージボディに送信者のラベルがプレフィックスとして付与されます（履歴エントリと同じスタイル）。これにより、リアルタイムのメッセージとキューイングされた履歴メッセージの間で、エージェントプロンプトの整合性が保たれます。

履歴バッファは未処理分のみを対象とします。これには、実行のトリガーにならなかったグループメッセージ（メンション待ちなど）が含まれ、すでにセッション履歴に含まれているメッセージは除外されます。

コマンドの除去は現在のメッセージセクションにのみ適用されるため、履歴はそのまま保持されます。履歴をラップするチャネルでは、CommandBody（または RawBody）に元のメッセージテキストを設定し、Body を結合されたプロンプトとして保持する必要があります。履歴バッファは messages.groupChat.historyLimit（グローバル設定）や、channels.slack.historyLimit、channels.telegram.accounts.<id>.historyLimit（0 で無効化）などのチャネルごとの設定で調整可能です。

キューイングとフォローアップ

エージェントが実行中のときに新しいメッセージを受信した場合、それらをキューに入れるか、現在の実行に割り込ませるか、あるいは次のターンとして収集するかを選択できます。

• messages.queue（および messages.queue.byChannel）で設定します。
• モード：interrupt, steer, followup, collect、およびバックログのバリエーション。

詳細は Queueing を参照してください。

ストリーミング、チャンキング、バッチ処理

ブロックストリーミングは、モデルがテキストブロックを生成するたびに部分的な返信を送信します。チャンキングはチャネルのテキスト制限を考慮し、コードブロックが途中で分割されないように処理します。

主な設定項目：

• agents.defaults.blockStreamingDefault (on|off, デフォルトは off)
• agents.defaults.blockStreamingBreak (text_end|message_end)
• agents.defaults.blockStreamingChunk (minChars|maxChars|breakPreference)
• agents.defaults.blockStreamingCoalesce (アイドル時間に基づくバッチ処理)
• agents.defaults.humanDelay (返信ブロック間の人間らしい一時停止)
• チャネルごとの上書き: *.blockStreaming および *.blockStreamingCoalesce (Telegram 以外のチャネルでは明示的に *.blockStreaming: true が必要です)

詳細は Streaming + chunking を参照してください。

推論プロセスの可視化とトークン

OpenClawでは、モデルの推論プロセス（Reasoning）を表示するか非表示にするかを制御できます。

• /reasoning on|off|stream コマンドで表示を切り替えます。
• 推論内容は、モデルによって生成される際にトークン消費としてカウントされます。
• Telegram では、ドラフトバブル内への推論ストリーミングをサポートしています。

詳細は Thinking + reasoning directives および Token use を参照してください。

プレフィックス、スレッド、リプライ

送信メッセージのフォーマットは messages で一元管理されています。

• messages.responsePrefix, channels.<channel>.responsePrefix, channels.<channel>.accounts.<id>.responsePrefix によるプレフィックスの階層管理。
• channels.whatsapp.messagePrefix (WhatsApp 受信プレフィックス)。
• replyToMode およびチャネルごとのデフォルト設定によるリプライスレッドの制御。

詳細は Configuration および各チャネルのドキュメントを参照してください。

関連情報

• Streaming — リアルタイムのメッセージ配信
• Retry — メッセージ配信の再試行挙動
• Queue — メッセージ処理キュー
• Channels — メッセージングプラットフォームの統合

次のステップ

• セッション管理の詳細
• キューイング設定のガイド

AI Setup Assistant