OpenClawグループ設定ガイド：権限管理とメンション制御

グループの概要

OpenClawは、Discord、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp、Zaloといった様々なプラットフォームにおいて、グループチャットを一貫して扱います。

初心者向けイントロダクション（2分）

OpenClawは、あなたが普段利用しているメッセージングアカウント上で「動作」します。WhatsAppのボットユーザーが別途作成されるわけではありません。あなたがグループに参加していれば、OpenClawはそのグループを認識し、そこで応答することが可能です。

デフォルトの動作は以下の通りです。

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

翻訳すると、許可リスト（allowlist）に含まれる送信者のみが、メンションを送ることでOpenClawを起動できます。

要約

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

コンテキストの可視性と許可リスト

グループの安全性を管理するために、以下の2つの異なる制御が行われます。

トリガーの承認: エージェントを起動できるユーザーの制御（groupPolicy、groups、groupAllowFrom、チャネル固有の許可リスト）。
コンテキストの可視性: モデルに注入される補足的なコンテキスト（返信テキスト、引用、スレッド履歴、転送されたメタデータ）の制御。

デフォルトでは、OpenClawは通常のチャット動作を優先し、コンテキストを基本的に受信したまま保持します。つまり、許可リストは主に誰がアクションをトリガーできるかを決定するものであり、引用や履歴のすべての断片に対する普遍的な削除境界線ではありません。

現在の動作はチャネルごとに異なります。

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

強化の方向性（計画中）：

contextVisibility: "all"（デフォルト）は、現在の受信したままの動作を維持します。
contextVisibility: "allowlist"は、補足コンテキストを許可リストの送信者にのみフィルタリングします。
contextVisibility: "allowlist_quote"は、allowlistに加えて、1つの明示的な引用/返信の例外を許可します。

この強化モデルがすべてのチャネルで一貫して実装されるまでは、プラットフォームごとに動作が異なる可能性がある点にご留意ください。

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>を追加するため、各トピックが独自のセッションを持ちます。
ダイレクトチャットはメインセッション（設定されている場合は送信者ごとのセッション）を使用します。
グループセッションではハートビートはスキップされます。

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

はい、あなたの「個人的な」トラフィックがDMであり、「公開」トラフィックがグループである場合、この構成は非常にうまく機能します。

理由：シングルエージェントモードでは、DMは通常メインセッションキー（agent:main:main）に格納されますが、グループは常にメイン以外のセッションキー（agent:main:<channel>:group:<id>）を使用します。mode: "non-main"でサンドボックスを有効にすると、グループセッションは設定されたサンドボックスバックエンドで実行され、メインのDMセッションはホスト上で維持されます。バックエンドを選択しない場合、デフォルトでDockerが使用されます。

これにより、1つのエージェント「脳」（共有ワークスペースとメモリ）を持ちながら、2つの実行姿勢を使い分けることができます。

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

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

例（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: ["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 },
      },
    },
  },
}

ポリシー	動作
`"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）にフォールバックします。

グループメッセージの評価順序のクイックメンタルモデルは以下の通りです：

groupPolicy (open/disabled/allowlist)
グループ許可リスト (*.groups, *.groupAllowFrom, チャンネル固有の許可リスト)
メンション制限 (requireMention, /activation)

メンションによる制限（デフォルト）

OpenClawのメンション機能を使用すると、グループメッセージにおいて特定のメンションを必須とすることができます。この設定は、サブシステムごとに *.groups."*" でデフォルト値を定義可能です。

ボットのメッセージに対して返信を行うと、チャンネルが返信メタデータをサポートしている場合に暗黙的なメンションとしてカウントされます。また、引用メタデータを公開しているチャンネルでは、ボットのメッセージを引用することも暗黙的なメンションとして扱われます。現在、Telegram、WhatsApp、Slack、Discord、Microsoft Teams、および ZaloUser がこの組み込み機能に対応しています。

{
  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."*" に存在し、ギルドやチャンネルごとに上書き可能です。
グループ履歴のコンテキストはチャンネル全体で一貫してラップされており、pending-only（メンション制限によりスキップされたメッセージ）となります。グローバルなデフォルト値には messages.groupChat.historyLimit を使用し、上書きには channels.<channel>.historyLimit（または channels.<channel>.accounts.*.historyLimit）を使用してください。0 を設定すると無効になります。

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

特定のグループ、ルーム、またはチャンネル内で利用可能なツールを制限する設定が可能です。

tools: グループ全体に対してツールの許可または拒否を設定します。
toolsBySender: グループ内の送信者ごとに上書き設定を行います。明示的なキープレフィックスとして id:<senderId>、e164:<phone>、username:<handle>、name:<displayName>、およびワイルドカードの "*" を使用してください。プレフィックスのない従来のキーも引き続き受け付けられ、id: として照合されます。

解決順序（より具体的な設定が優先されます）：

グループ/チャンネルの toolsBySender 一致
グループ/チャンネルの tools
デフォルト ("*") の toolsBySender 一致
デフォルト ("*") の tools

設定例（Telegram）：

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

注意点：

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

AI Setup Assistant

グループの許可リスト (Group allowlists)

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

よくある混乱として、DMペアリングの承認とグループの承認は別物であるという点に注意してください。DMペアリングをサポートするチャネルの場合、ペアリングストアはDMのみを許可します。グループでのコマンド実行には、groupAllowFrom や各チャネルで定義された設定のフォールバックなど、設定ファイルによる明示的なグループ送信者の承認が引き続き必要です。

以下はよく利用される設定例です（コピー＆ペーストしてご利用ください）。

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

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

特定のグループのみを許可する (WhatsApp)

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

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

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

グループ内ではオーナーのみが実行可能にする (WhatsApp)

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

アクティベーション (オーナー限定)

グループのオーナーは、グループごとにアクティベーションを切り替えることができます。

グループのオーナーは、以下のコマンドを使用して設定を変更します。

/activation mention
/activation always

オーナーは channels.whatsapp.allowFrom（設定されていない場合はボット自身のE.164番号）によって決定されます。コマンドは単独のメッセージとして送信してください。現在、他のインターフェースでは /activation コマンドは無視されます。

コンテキストフィールド

受信したペイロードのセットには、OpenClawが処理を行うための重要な情報が含まれています。グループチャットやスレッド形式のメッセージを正確に扱うために、以下のフィールドが利用されます。

ChatType=group
GroupSubject (判明している場合)
GroupMembers (判明している場合)
WasMentioned (メンション制限の結果)
Telegramのフォーラムトピックには、MessageThreadIdおよびIsForumが含まれます。

チャンネル固有の注意点として、BlueBubblesでは、ローカルの連絡先データベースから名前のないmacOSグループ参加者を補完する機能があります。これはデフォルトではオフになっており、通常のグループフィルタリングが完了した後にのみ実行されます。

エージェントのシステムプロンプトには、新しいグループセッションの最初のターンでグループ紹介が含まれます。モデルに対して、人間らしく応答すること、Markdownの表を避けること、空行を最小限に抑えて通常のチャット間隔に従うこと、そしてリテラルな \n シーケンスを入力しないように指示しています。

iMessageの仕様

ルーティングや許可リストの設定を行う際は、chat_id:<id>を使用することを推奨します。

チャットの一覧を表示するには、以下のCLIコマンドを実行します。

imsg chats --limit 20

グループへの返信は、常に同じ chat_id に対して行われます。

WhatsAppの仕様

WhatsApp特有の動作（履歴の注入やメンション処理の詳細など）については、グループメッセージのドキュメントを参照してください。

OpenClaw Expert

まだ解決しませんか？

このページで解決しない場合は、OpenClaw Expertに直接質問してください。