グループメッセージ（WhatsApp Webチャンネル）

目的：OpenClawをWhatsAppグループに参加させ、メンションされたときだけ起動し、個人DMセッションとは別のスレッドで管理します。

注意：agents.list[].groupChat.mentionPatternsは現在Telegram/Discord/Slack/iMessageでも使用されています。このドキュメントではWhatsApp固有の動作に焦点を当てます。マルチエージェント構成では、エージェントごとにagents.list[].groupChat.mentionPatternsを設定してください（またはmessages.groupChat.mentionPatternsをグローバルフォールバックとして使用）。

実装済みの機能（2025-12-03）

  • アクティベーションモード：mention（デフォルト）またはalways。mentionではピン（WhatsAppのmentionedJidsによるリアル@メンション、正規表現パターン、またはボットのE.164番号がテキスト内にある場合）が必要です。alwaysではすべてのメッセージでエージェントが起動しますが、意味のある価値を提供できる場合のみ返信し、それ以外はサイレントトークンNO_REPLYを返します。デフォルトは設定（channels.whatsapp.groups）で指定でき、/activationでグループごとに上書きできます。channels.whatsapp.groupsが設定されている場合、グループの許可リストとしても機能します（すべてを許可するには"*"を含めてください）。
  • グループポリシー：channels.whatsapp.groupPolicyはグループメッセージの受け入れを制御します（open|disabled|allowlist）。allowlistはchannels.whatsapp.groupAllowFromを使用します（フォールバック：明示的なchannels.whatsapp.allowFrom）。デフォルトはallowlist（送信者を追加するまでブロック）です。
  • グループごとのセッション：セッションキーはagent:<agentId>:whatsapp:group:<jid>の形式で、/verbose onや/think high（スタンドアロンメッセージとして送信）などのコマンドはそのグループにスコープされます。個人DMの状態には影響しません。グループスレッドではハートビートはスキップされます。
  • コンテキスト注入：実行をトリガーしなかった保留中のみのグループメッセージ（デフォルト50件）は[Chat messages since your last reply - for context]の下にプレフィックスされ、トリガーとなった行は[Current message - respond to this]の下に表示されます。セッション内に既にあるメッセージは再注入されません。
  • 送信者の表示：すべてのグループバッチの末尾に[from: Sender Name (+E164)]が付与され、誰が話しているかがわかります。
  • エフェメラル/一度限りの表示：テキスト/メンションの抽出前にアンラップされるため、その中のメンションもトリガーとして機能します。
  • グループシステムプロンプト：グループセッションの最初のターン（および/activationでモードが変更されたとき）に、短い説明がシステムプロンプトに注入されます。例：You are replying inside the WhatsApp group "<subject>". Group members: Alice (+44...), Bob (+43...), … Activation: trigger-only … Address the specific sender noted in the message context. メタデータが利用できない場合でも、グループチャットであることをエージェントに伝えます。

設定例（WhatsApp）

~/.openclaw/openclaw.jsonにgroupChatブロックを追加して、WhatsAppがテキスト本文のビジュアル@を削除した場合でも表示名メンションが機能するようにします：

{
  channels: {
    whatsapp: {
      groups: {
        "*": { requireMention: true },
      },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          historyLimit: 50,
          mentionPatterns: ["@?openclaw", "\\+?15555550123"],
        },
      },
    ],
  },
}

注意事項：

  • 正規表現は大文字小文字を区別しません。@openclawのような表示名メンションと、+/スペースの有無に関わらない生の番号をカバーします。
  • WhatsAppはユーザーが連絡先をタップした際にmentionedJids経由でカノニカルメンションを送信するため、番号フォールバックが必要になることはまれですが、セーフティネットとして有用です。

アクティベーションコマンド（オーナー専用）

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

  • /activation mention
  • /activation always

オーナー番号（channels.whatsapp.allowFromから、または未設定の場合はボット自身のE.164）のみがこれを変更できます。グループでスタンドアロンメッセージとして/statusを送信すると、現在のアクティベーションモードを確認できます。

使い方

  1. あなたのWhatsAppアカウント（OpenClawを実行しているアカウント）をグループに追加します。
  2. @openclaw …と入力（または番号を含めます）。groupPolicy: "open"を設定しない限り、許可リストの送信者のみがトリガーできます。
  3. エージェントプロンプトには最近のグループコンテキストと末尾の[from: …]マーカーが含まれるため、適切な相手に返信できます。
  4. セッションレベルのディレクティブ（/verbose on、/think high、/newまたは/reset、/compact）はそのグループのセッションにのみ適用されます。スタンドアロンメッセージとして送信してください。個人DMセッションは独立しています。

テスト/検証

  • 手動スモークテスト：
    • グループで@openclawメンションを送信し、送信者名を参照した返信を確認します。
    • 2回目のメンションを送信し、履歴ブロックが含まれ、次のターンでクリアされることを確認します。
  • ゲートウェイログ（--verboseで実行）を確認して、inbound web messageエントリにfrom: <groupJid>と[from: …]サフィックスが表示されていることを確認します。

既知の注意事項

  • グループではノイズのあるブロードキャストを避けるため、ハートビートは意図的にスキップされます。
  • エコー抑制は結合されたバッチ文字列を使用します。メンションなしで同一テキストを2回送信した場合、最初のメッセージのみが応答を受けます。
  • セッションストアのエントリはagent:<agentId>:whatsapp:group:<jid>としてセッションストア（デフォルト~/.openclaw/agents/<agentId>/sessions/sessions.json）に表示されます。エントリがない場合は、そのグループがまだ実行をトリガーしていないことを意味します。
  • グループでのタイピングインジケーターはagents.defaults.typingModeに従います（デフォルト：メンションなしの場合はmessage）。
arrow_back
前へ
Pairing
次へ
Groups
arrow_forward