グループ

OpenClawはグループチャットを各プラットフォームで統一的に扱います：WhatsApp、Telegram、Discord、Slack、Signal、iMessage、Microsoft Teams、Zalo。

初心者向けイントロ（2分）

OpenClawはあなた自身のメッセージングアカウント上で「動作」します。別途WhatsApp Botユーザーは存在しません。 あなたがグループに参加していれば、OpenClawはそのグループを確認して応答できます。

デフォルトの動作：

  • グループは制限されています（groupPolicy: "allowlist"）。
  • メンションゲーティングを明示的に無効にしない限り、返信にはメンションが必要です。

つまり：許可リストに登録された送信者がメンションすることでOpenClawをトリガーできます。

TL;DR

  • DM アクセスは *.allowFrom で制御されます。
  • グループアクセスは *.groupPolicy + 許可リスト（*.groups、*.groupAllowFrom）で制御されます。
  • 返信トリガーはメンションゲーティング（requireMention、/activation）で制御されます。

クイックフロー（グループメッセージに何が起こるか）：

groupPolicy? disabled -> drop
groupPolicy? allowlist -> group allowed? no -> drop
requireMention? yes -> mentioned? no -> store for context only
otherwise -> reply

Group message flow

実現したい内容に応じた設定：

目標設定内容
すべてのグループを許可するが@メンション時のみ返信groups: { "*": { requireMention: true } }
すべてのグループ返信を無効化groupPolicy: "disabled"
特定のグループのみgroups: { "<group-id>": { ... } }（"*" キーなし）
グループで自分だけがトリガー可能groupPolicy: "allowlist", groupAllowFrom: ["+1555..."]

セッションキー

  • グループセッションは agent:<agentId>:<channel>:group:<id> セッションキーを使用します（ルーム/チャンネルは agent:<agentId>:<channel>:channel:<id> を使用）。
  • TelegramフォーラムトピックはグループIDに :topic:<threadId> を追加し、各トピックが独自のセッションを持ちます。
  • ダイレクトチャットはメインセッション（または設定されている場合はsender別）を使用します。
  • グループセッションではハートビートはスキップされます。

パターン：個人DM + 公開グループ（シングルエージェント）

はい — 「個人」トラフィックがDMで、「公開」トラフィックがグループであれば、うまく機能します。

理由：シングルエージェントモードでは、DMは通常メインセッションキー（agent:main:main）に到達し、グループは常に非メインセッションキー（agent:main:<channel>:group:<id>）を使用します。mode: "non-main" でサンドボックスを有効にすると、グループセッションはDocker内で実行され、メインDMセッションはホスト上に残ります。

これにより、1つのエージェント「ブレイン」（共有ワークスペース + メモリ）で2つの実行体制が得られます：

  • DM：フルツール（ホスト）
  • グループ：サンドボックス + 制限されたツール（Docker）

真に別々のワークスペース/ペルソナが必要な場合（「個人」と「公開」が混在してはいけない場合）は、2つ目のエージェント + バインディングを使用してください。マルチエージェントルーティングを参照してください。

例（DMはホスト上、グループはサンドボックス + メッセージングのみのツール）：

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // groups/channels are non-main -> sandboxed
        scope: "session", // strongest isolation (one container per group/channel)
        workspaceAccess: "none",
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        // If allow is non-empty, everything else is blocked (deny still wins).
        allow: ["group:messaging", "group:sessions"],
        deny: ["group:runtime", "group:fs", "group:ui", "nodes", "cron", "gateway"],
      },
    },
  },
}

「グループはフォルダXのみ参照可能」にしたい場合は、workspaceAccess: "none" のまま、許可されたパスのみをサンドボックスにマウントします：

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "session",
        workspaceAccess: "none",
        docker: {
          binds: [
            // hostPath:containerPath:mode
            "/home/user/FriendsShared:/data:ro",
          ],
        },
      },
    },
  },
}

関連：

表示ラベル

  • UIラベルは利用可能な場合 displayName を使用し、<channel>:<token> としてフォーマットされます。
  • #room はルーム/チャンネル用に予約されています。グループチャットは g-<slug>（小文字、スペース → -、#@+._- は保持）を使用します。

グループポリシー

チャンネルごとにグループ/ルームメッセージの処理方法を制御します：

{
  channels: {
    whatsapp: {
      groupPolicy: "disabled", // "open" | "disabled" | "allowlist"
      groupAllowFrom: ["+15551234567"],
    },
    telegram: {
      groupPolicy: "disabled",
      groupAllowFrom: ["123456789"], // numeric Telegram user id (wizard can resolve @username)
    },
    signal: {
      groupPolicy: "disabled",
      groupAllowFrom: ["+15551234567"],
    },
    imessage: {
      groupPolicy: "disabled",
      groupAllowFrom: ["chat_id:123"],
    },
    msteams: {
      groupPolicy: "disabled",
      groupAllowFrom: ["[email protected]"],
    },
    discord: {
      groupPolicy: "allowlist",
      guilds: {
        GUILD_ID: { channels: { help: { allow: true } } },
      },
    },
    slack: {
      groupPolicy: "allowlist",
      channels: { "#general": { allow: true } },
    },
    matrix: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["@owner:example.org"],
      groups: {
        "!roomId:example.org": { allow: true },
        "#alias:example.org": { allow: true },
      },
    },
  },
}
ポリシー動作
"open"グループは許可リストをバイパスしますが、メンションゲーティングは適用されます。
"disabled"すべてのグループメッセージを完全にブロックします。
"allowlist"設定された許可リストに一致するグループ/ルームのみ許可します。

注意事項：

  • groupPolicy はメンションゲーティング（@メンションが必要）とは別です。
  • WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo：groupAllowFrom（フォールバック：明示的な allowFrom）を使用します。
  • DMペアリング承認（*-allowFrom ストアエントリ）はDMアクセスにのみ適用されます。グループ送信者の認証はグループ許可リストに明示的に依存します。
  • Discord：許可リストは channels.discord.guilds.<id>.channels を使用します。
  • Slack：許可リストは channels.slack.channels を使用します。
  • Matrix：許可リストは channels.matrix.groups（ルームID、エイリアス、または名前）を使用します。channels.matrix.groupAllowFrom で送信者を制限できます。ルームごとの users 許可リストもサポートされています。
  • グループDMは別途制御されます（channels.discord.dm.*、channels.slack.dm.*）。
  • Telegram許可リストはユーザーID（"123456789"、"telegram:123456789"、"tg:123456789"）またはユーザー名（"@alice" または "alice"）にマッチできます。プレフィックスは大文字小文字を区別しません。
  • デフォルトは groupPolicy: "allowlist" です。グループ許可リストが空の場合、グループメッセージはブロックされます。
  • ランタイム安全性：プロバイダーブロックが完全に欠落している場合（channels.<provider> が存在しない）、グループポリシーは channels.defaults.groupPolicy を継承する代わりにフェイルクローズモード（通常 allowlist）にフォールバックします。

クイックメンタルモデル（グループメッセージの評価順序）：

  1. groupPolicy（open/disabled/allowlist）
  2. グループ許可リスト（*.groups、*.groupAllowFrom、チャンネル固有の許可リスト）
  3. メンションゲーティング（requireMention、/activation）

メンションゲーティング（デフォルト）

グループメッセージは、グループごとに上書きされない限りメンションが必要です。デフォルトは *.groups."*" 下のサブシステムごとに設定されます。

ボットメッセージへの返信は暗黙のメンションとしてカウントされます（チャンネルが返信メタデータをサポートしている場合）。これはTelegram、WhatsApp、Slack、Discord、Microsoft Teamsに適用されます。

{
  channels: {
    whatsapp: {
      groups: {
        "*": { requireMention: true },
        "[email protected]": { requireMention: false },
      },
    },
    telegram: {
      groups: {
        "*": { requireMention: true },
        "123456789": { requireMention: false },
      },
    },
    imessage: {
      groups: {
        "*": { requireMention: true },
        "123": { requireMention: false },
      },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw", "\\+15555550123"],
          historyLimit: 50,
        },
      },
    ],
  },
}

注意事項：

  • mentionPatterns は大文字小文字を区別しない正規表現です。
  • 明示的なメンションを提供するプラットフォームでは引き続きパスします。パターンはフォールバックです。
  • エージェントごとのオーバーライド：agents.list[].groupChat.mentionPatterns（複数のエージェントがグループを共有する場合に有用）。
  • メンションゲーティングはメンション検出が可能な場合（ネイティブメンションまたは mentionPatterns が設定されている場合）にのみ適用されます。
  • Discordのデフォルトは channels.discord.guilds."*" にあります（ギルド/チャンネルごとにオーバーライド可能）。
  • グループ履歴コンテキストはチャンネル間で統一的にラップされ、保留中のみ（メンションゲーティングによりスキップされたメッセージ）です。グローバルデフォルトには messages.groupChat.historyLimit を、オーバーライドには channels.<channel>.historyLimit（または channels.<channel>.accounts.*.historyLimit）を使用してください。0 に設定すると無効になります。

グループ/チャンネルのツール制限（オプション）

一部のチャンネル設定では、特定のグループ/ルーム/チャンネル内で使用可能なツールを制限できます。

  • tools：グループ全体のツールを許可/拒否します。
  • toolsBySender：グループ内の送信者ごとのオーバーライド。 明示的なキープレフィックスを使用してください： id:<senderId>、e164:<phone>、username:<handle>、name:<displayName>、および "*" ワイルドカード。 レガシーのプレフィックスなしキーも受け付けられ、id: としてのみマッチします。

解決順序（最も具体的なものが優先）：

  1. グループ/チャンネル toolsBySender マッチ
  2. グループ/チャンネル tools
  3. デフォルト（"*"）toolsBySender マッチ
  4. デフォルト（"*"）tools

例（Telegram）：

{
  channels: {
    telegram: {
      groups: {
        "*": { tools: { deny: ["exec"] } },
        "-1001234567890": {
          tools: { deny: ["exec", "read", "write"] },
          toolsBySender: {
            "id:123456789": { alsoAllow: ["exec"] },
          },
        },
      },
    },
  },
}

注意事項：

  • グループ/チャンネルのツール制限はグローバル/エージェントのツールポリシーに加えて適用されます（denyが優先）。
  • 一部のチャンネルではルーム/チャンネルに異なるネスト構造を使用します（例：Discord guilds.*.channels.*、Slack channels.*、MS Teams teams.*.channels.*）。

グループ許可リスト

channels.whatsapp.groups、channels.telegram.groups、または channels.imessage.groups が設定されている場合、キーはグループ許可リストとして機能します。"*" を使用すると、デフォルトのメンション動作を設定しつつすべてのグループを許可できます。

一般的な設定パターン（コピー＆ペースト用）：

  1. すべてのグループ返信を無効化
{
  channels: { whatsapp: { groupPolicy: "disabled" } },
}
  1. 特定のグループのみ許可（WhatsApp）
{
  channels: {
    whatsapp: {
      groups: {
        "[email protected]": { requireMention: true },
        "[email protected]": { requireMention: false },
      },
    },
  },
}
  1. すべてのグループを許可するがメンション必須（明示的）
{
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}
  1. グループでオーナーのみトリガー可能（WhatsApp）
{
  channels: {
    whatsapp: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
      groups: { "*": { requireMention: true } },
    },
  },
}

アクティベーション（オーナーのみ）

グループオーナーはグループごとにアクティベーションを切り替えできます：

  • /activation mention
  • /activation always

オーナーは channels.whatsapp.allowFrom（未設定の場合はBotのself E.164）によって判定されます。コマンドは単独のメッセージとして送信してください。他のプラットフォームでは現在 /activation は無視されます。

コンテキストフィールド

グループインバウンドペイロードは以下を設定します：

  • ChatType=group
  • GroupSubject（判明している場合）
  • GroupMembers（判明している場合）
  • WasMentioned（メンションゲーティング結果）
  • Telegramフォーラムトピックには MessageThreadId と IsForum も含まれます。

エージェントシステムプロンプトは、新しいグループセッションの最初のターンでグループイントロを含みます。モデルに人間のように応答し、Markdownテーブルを避け、リテラルの \n シーケンスを入力しないよう注意喚起します。

iMessage固有の情報

  • ルーティングまたは許可リスト設定時は chat_id:<id> を推奨します。
  • チャット一覧表示：imsg chats --limit 20。
  • グループ返信は常に同じ chat_id に返されます。

WhatsApp固有の情報

WhatsApp固有の動作（履歴インジェクション、メンション処理の詳細）については、グループメッセージを参照してください。

arrow_back
前へ
Group Messages
次へ
Broadcast Groups
arrow_forward