Configuration

WhatsAppグループメッセージ

クロスチャネルのグループモデル（Discord、iMessage、Matrix、Microsoft Teams、QQBot、Signal、Slack、Telegram、WhatsApp、Zalo）については、グループを参照してください。このページでは、そのモデルに加えて、アクティベーション、グループ許可リスト、グループごとのセッションキー、保留中メッセージのコンテキスト注入といった、WhatsApp固有の動作について説明します。

目標: OpenClawをWhatsAppグループに参加させ、呼びかけられたときだけ起動し、そのスレッドを個人DMセッションとは分離して維持します。

動作

アクティベーションモード: mention（デフォルト）またはalways。mentionでは呼びかけが必要です。具体的には、実際のWhatsAppの@メンション（mentionedJids）、設定済みの正規表現パターン、テキスト内の任意の場所にあるボットのE.164形式の数字、またはボットのメッセージに対する引用返信（共有番号を使用した自分自身とのチャット構成を除く）のいずれかです。alwaysではメッセージごとにエージェントが起動しますが、注入されるグループプロンプトにより、価値を付加できる場合にのみ返信し、それ以外の場合は正確な無応答トークンNO_REPLY（大文字と小文字を区別しない）を返すよう指示されます。デフォルト値は設定（channels.whatsapp.groupsのrequireMention）から取得され、グループごとに/activationで上書きできます。
グループ許可リスト: channels.whatsapp.groupsが設定されている場合、一覧に含まれるグループJIDのみが許可されます（すべて許可するには"*"を含めます）。一覧にないグループからのメッセージは、ログにヒントを残して破棄されます。
グループポリシー: channels.whatsapp.groupPolicyは、グループメッセージを受け入れるかどうか（open|disabled|allowlist）を制御します。allowlistはchannels.whatsapp.groupAllowFrom（フォールバック: 明示的なchannels.whatsapp.allowFrom）を使用します。デフォルトはallowlistです（送信者を追加するまでブロックされます）。
グループごとのセッション: セッションキーはagent:<agentId>:whatsapp:group:<jid>のような形式です（デフォルト以外のアカウントでは:thread:whatsapp-account-<accountId>が付加されます）。そのため、/verbose on、/trace on、/think highなどのディレクティブ（単独のメッセージとして送信）は、そのグループに限定され、個人DMの状態には影響しません。
コンテキスト注入: 実行をトリガーしなかった保留中のみのグループメッセージ（デフォルト50件）が[Chat messages since your last reply - for context]の下に前置され、トリガーとなった行は[Current message - respond to this]の下に配置されます。保留ウィンドウは実行後にクリアされ、すでにセッション内にあるメッセージは再注入されません。
送信者の帰属情報: 各グループ行には、メッセージエンベロープ内に送信者ラベルが含まれます。例: [WhatsApp <groupJid> <timestamp>] Alice (+447700900123): text。また、送信者の識別情報とグループの件名/メンバー情報が、信頼されていない会話メタデータブロックに付随します。
一時的/一度だけ表示: テキスト/メンションを抽出する前にラッパーが解除されるため、その中の呼びかけも引き続きトリガーになります。
グループシステムプロンプト: グループセッションの最初のターン（および/activationでモードを変更した後の各ターン）では、アクティベーションのガイダンスがシステムプロンプトに注入されます（Activation: trigger-only ...またはActivation: always-on ...に加え、「特定の送信者に呼びかける」という指示）。永続的なグループチャット配信ガイダンス（「WhatsAppグループチャットに参加しています...」）は常に含まれます。

設定例（WhatsApp）

WhatsAppがテキスト本文から視覚的な@を取り除いた場合でも、表示名による呼びかけが機能するようにします。

json5

{  channels: {    whatsapp: {      groups: {        "*": { requireMention: true },      },      historyLimit: 50, // 保留中のグループコンテキストウィンドウ（デフォルト50）    },  },  agents: {    list: [      {        id: "main",        groupChat: {          mentionPatterns: ["@?openclaw", "\\+?15555550123"],        },      },    ],  },}

注記:

正規表現では大文字と小文字が区別されず、他の設定の正規表現サーフェスと同じ安全な正規表現のガードレールが使用されます。無効なパターンや安全でないネストされた繰り返しは無視されます。
誰かが連絡先をタップした場合、WhatsAppは引き続きmentionedJidsを通じて正規のメンションを送信するため、番号によるフォールバックが必要になることはほとんどありませんが、有用な安全策になります。
保留中コンテキストウィンドウは、channels.whatsapp.accounts.<id>.historyLimit → channels.whatsapp.historyLimit → messages.groupChat.historyLimit → 50の順で解決されます。

アクティベーションコマンド（所有者のみ）

グループチャットコマンドを使用します。

/activation mention
/activation always

この設定を変更できるのは、所有者の番号（channels.whatsapp.allowFrom で指定された番号、未設定の場合はボット自身の E.164 番号）のみです。それ以外のユーザーからの /activation は無視され、コンテキストとしてのみ保存されます。現在のアクティベーションモードを確認するには、グループ内で /status を単独のメッセージとして送信します。

使用方法

OpenClaw を実行している WhatsApp アカウントをグループに追加します。
@openclaw ... と発言します（または番号を含めます）。groupPolicy: "open" を設定しない限り、許可リストに登録された送信者のみが起動できます。
エージェントのプロンプトには、保留中のグループコンテキストと送信者ラベル付きの行が含まれるため、適切な相手に応答できます。
セッションディレクティブ（/verbose on、/trace on、/think high、/new または /reset、/compact）は、そのグループのセッションにのみ適用されます。認識されるよう、単独のメッセージとして送信してください。個人の DM セッションは独立したままです。

テスト / 検証

手動スモークテスト：
- グループ内で @openclaw へのメンションを送信し、送信者名を参照する返信が届くことを確認します。
- 2 回目のメンションを送信し、履歴ブロックが含まれていること、その次のターンで消去されることを確認します。
Gateway のログ（--verbose を指定して実行）で、from: <groupJid> と送信者ラベル付きの本文が表示される inbound web message エントリを確認します。

既知の考慮事項

Heartbeat はエージェントのメインセッションで実行されます。グループセッションでは Heartbeat が実行されることはありません。
エコー抑制では、ボット自身が配信したメッセージによって再起動されないように、セッションごとに結合されたプロンプト（履歴 + 現在のメッセージ）が記憶されます。同一のバッチが繰り返された場合は、エコーとしてスキップされることがあります。
セッションストアのエントリは、エージェントごとの SQLite セッションストアに agent:<agentId>:whatsapp:group:<jid> として表示されます。エントリが存在しない場合は、そのグループがまだ実行を起動していないことを意味するだけです。
入力中インジケーターは session.typingMode / agents.defaults.typingMode に従います。表示される返信でメッセージツールのみのモードを選択した場合、デフォルトでは入力中表示が直ちに開始されるため、自動的な最終返信が投稿されなくても、グループメンバーはエージェントが処理中であることを確認できます。入力モードを明示的に設定している場合は、その設定が引き続き優先されます。