​

グループ

​

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

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

要点

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

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

​

コンテキストの可視性と allowlist

• トリガー認可: 誰がエージェントをトリガーできるか（groupPolicy、groups、groupAllowFrom、チャネル固有の allowlist）。
• コンテキストの可視性: どの補足コンテキストがモデルに注入されるか（返信テキスト、引用、スレッド履歴、転送メタデータ）。

• 一部のチャネルでは、特定の経路で補足コンテキストに対して送信者ベースのフィルタリングがすでに適用されています（たとえば Slack のスレッドシード、Matrix の返信/スレッド参照）。
• 他のチャネルでは、引用/返信/転送コンテキストが受信したまま渡されます。

• contextVisibility: "all"（デフォルト）は、現在の受信したままの動作を維持します。
• contextVisibility: "allowlist" は、補足コンテキストを allowlist に登録された送信者に絞り込みます。
• contextVisibility: "allowlist_quote" は、allowlist に 1 つの明示的な引用/返信例外を加えたものです。

​

セッションキー

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

​

パターン: 個人 DM + 公開グループ（単一エージェント）

• DM: フルツール（ホスト）
• グループ: サンドボックス + 制限付きツール（Docker）

本当に分離されたワークスペース/ペルソナ（「個人」と「公開」を決して混在させてはいけない）が必要な場合は、2 つ目のエージェント + バインディングを使用してください。Multi-Agent Routing を参照してください。

{
  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"],
      },
    },
  },
}

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

• 設定キーとデフォルト: Gateway configuration
• ツールがブロックされる理由のデバッグ: Sandbox vs Tool Policy vs Elevated
• バインドマウントの詳細: Sandboxing

​

表示ラベル

• 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: ["user@org.com"],
    },
    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": { enabled: true },
        "#alias:example.org": { enabled: true },
      },
    },
  },
}

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

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

​

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

{
  channels: {
    whatsapp: {
      groups: {
        "*": { requireMention: true },
        "123@g.us": { 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."*" 配下にあります（guild/channel ごとに上書き可能）。
• グループ履歴コンテキストは、チャネル間で一貫した形でラップされ、保留中のみ です（メンションゲーティングのためにスキップされたメッセージ）。グローバルデフォルトには 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

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

• グループ/チャネルのツール制限は、グローバル/エージェントのツールポリシーに加えて適用されます（deny が引き続き優先されます）。
• チャネルによって、ルーム/チャネルに異なるネストを使用するものがあります（例: Discord guilds.*.channels.*、Slack channels.*、Microsoft Teams teams.*.channels.*）。

​

グループ allowlist

1. すべてのグループ返信を無効にする

{
  channels: { whatsapp: { groupPolicy: "disabled" } },
}

2. 特定のグループのみ許可する（WhatsApp）

{
  channels: {
    whatsapp: {
      groups: {
        "123@g.us": { requireMention: true },
        "456@g.us": { requireMention: false },
      },
    },
  },
}

3. すべてのグループを許可するが、メンションを必須にする（明示的）

{
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}

4. グループ内でトリガーできるのはオーナーだけ（WhatsApp）

{
  channels: {
    whatsapp: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
      groups: { "*": { requireMention: true } },
    },
  },
}

​

Activation（owner-only）

• /activation mention
• /activation always

​

コンテキストフィールド

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

• BlueBubbles は、GroupMembers を設定する前に、名前のない macOS グループ参加者をローカル Contacts データベースから任意で補完できます。これはデフォルトでオフであり、通常のグループゲーティングを通過した後にのみ実行されます。

​

iMessage 固有事項

• ルーティングや allowlist には chat_id:<id> を優先してください。
• チャット一覧: imsg chats --limit 20
• グループ返信は常に同じ chat_id に返されます。

​

WhatsApp 固有事項