グループ

OpenClaw は、Discord、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp、Zalo の各サーフェスで、グループチャットを一貫して扱います。

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

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

デフォルトの動作:

• グループは制限されます（groupPolicy: "allowlist"）。
• 明示的にメンションゲートを無効化しない限り、返信にはメンションが必要です。
• グループ/チャンネルでの通常の最終返信は、デフォルトでは非公開です。ルームに見える出力には message ツールを使います。

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

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

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

# 見える返信

グループ/チャンネルルームでは、OpenClaw のデフォルトは messages.groupChat.visibleReplies: "message_tool" です。 openclaw doctor --fix は、これを省略している設定済みチャンネル設定にこのデフォルトを書き込みます。 つまり、エージェントは引き続きターンを処理し、メモリ/セッション状態を更新できますが、通常の最終回答はルームに自動投稿されません。見える形で発言するには、エージェントが message(action=send) を使います。

このデフォルトは、ツールを確実に呼び出すモデル/ランタイムに依存します。ログにアシスタントテキストが表示されているのに didSendViaMessagingTool: false の場合、モデルはメッセージツールを呼び出さず、非公開で回答しています。これは Discord/Slack/Telegram の送信失敗ではありません。グループ/チャンネルセッションにはツール呼び出しが信頼できるモデルを使うか、messages.groupChat.visibleReplies: "automatic" を設定して、従来の見える最終返信を復元してください。

アクティブなツールポリシーでメッセージツールが利用できない場合、OpenClaw は応答を黙って抑制するのではなく、自動の見える返信にフォールバックします。 openclaw doctor はこの不一致について警告します。

ダイレクトチャットおよびその他の送信元ターンでは、messages.visibleReplies: "message_tool" を使って、同じツール専用の見える返信動作をグローバルに適用します。ハーネスもこれを未設定時のデフォルトとして選べます。Codex ハーネスは、Codex モードのダイレクトチャットでこれを行います。messages.groupChat.visibleReplies は、グループ/チャンネルルーム向けのより具体的なオーバーライドとして残ります。

これは、ほとんどの潜伏モードのターンでモデルに NO_REPLY と回答させる古いパターンを置き換えます。ツール専用モードでは、見える動作を何もしないことは、単にメッセージツールを呼び出さないことを意味します。

エージェントがツール専用モードで作業している間も、入力中インジケーターは送信されます。これらのターンでは、エージェントがメッセージツールを呼び出すかどうかを決める前に通常のアシスタントメッセージテキストが一切存在しない可能性があるため、デフォルトのグループ入力中モードは "message" から "instant" にアップグレードされます。明示的な入力中モード設定は引き続き優先されます。

グループ/チャンネルルームで従来の自動最終返信を復元するには:

{
  messages: {
    groupChat: {
      visibleReplies: "automatic",
    },
  },
}

Gateway はファイル保存後に messages 設定をホットリロードします。再起動が必要なのは、デプロイでファイル監視または設定リロードが無効になっている場合だけです。

すべての送信元チャットで、見える出力にメッセージツールの経由を必須にするには:

{
  messages: {
    visibleReplies: "message_tool",
  },
}

ネイティブスラッシュコマンド（Discord、Telegram、およびネイティブコマンド対応のその他のサーフェス）は visibleReplies: "message_tool" をバイパスし、チャンネルネイティブのコマンド UI が期待する応答を受け取れるよう、常に見える形で返信します。これは検証済みのネイティブコマンドターンにのみ適用されます。テキスト入力された /... コマンドと通常のチャットターンは、引き続き設定済みのグループデフォルトに従います。

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

グループの安全性には、2 つの異なる制御が関係します。

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

デフォルトでは、OpenClaw は通常のチャット動作を優先し、コンテキストをほぼ受信時のまま保ちます。つまり、許可リストは主に誰がアクションをトリガーできるかを決めるものであり、引用や履歴のあらゆるスニペットに対する普遍的な墨消し境界ではありません。

目的別の設定:

再利用可能な送信者許可リストについては、アクセスグループを参照してください。

# セッションキー

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

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

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

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

これにより、1 つのエージェント「頭脳」（共有ワークスペース + メモリ）で、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"],
      },
    },
  },
}

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

関連情報:

• 設定キーとデフォルト: Gateway 設定
• ツールがブロックされる理由のデバッグ: サンドボックス vs ツールポリシー vs 昇格
• バインドマウントの詳細: サンドボックス化

# 表示ラベル

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

簡単なメンタルモデル（グループメッセージの評価順序）:

# メンションゲート（デフォルト）

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

チャンネルが返信メタデータをサポートしている場合、ボットメッセージへの返信は暗黙のメンションとして扱われます。引用メタデータを公開するチャンネルでは、ボットメッセージの引用も暗黙のメンションとして扱われる場合があります。現在の組み込みケースには Telegram、WhatsApp、Slack、Discord、Microsoft Teams、ZaloUser が含まれます。

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

# グループ/チャンネルのツール制限（任意）

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

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

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

例（Telegram）:

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

# グループ許可リスト

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

一般的な意図（コピー/貼り付け）:

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

{
  channels: {
    whatsapp: {
      groups: {
        "[email protected]": { requireMention: true },
        "[email protected]": { requireMention: false },
      },
    },
  },
}

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

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

# Activation（所有者のみ）

グループ所有者はグループ単位の activation を切り替えられます。

• /activation mention
• /activation always

所有者は channels.whatsapp.allowFrom（未設定の場合はボット自身の E.164）によって決まります。コマンドは単独のメッセージとして送信します。現在、他のサーフェスは /activation を無視します。

# コンテキストフィールド

グループ受信ペイロードは次を設定します。

• ChatType=group
• GroupSubject（既知の場合）
• GroupMembers（既知の場合）
• WasMentioned（メンションゲートの結果）
• Telegram フォーラムトピックには MessageThreadId と IsForum も含まれます。

チャンネル固有の注記:

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

エージェントのシステムプロンプトには、新しいグループセッションの最初のターンでグループ導入が含まれます。これは、モデルに人間のように応答すること、Markdown テーブルを避けること、空行を最小限にして通常のチャット間隔に従うこと、リテラルの \n シーケンスを入力しないことを促します。チャンネル由来のグループ名と参加者ラベルは、インラインのシステム指示ではなく、フェンスされた信頼できないメタデータとしてレンダリングされます。

# iMessage 固有事項

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

# WhatsApp システムプロンプト

グループおよび直接プロンプトの解決、ワイルドカード動作、アカウント上書きセマンティクスを含む、正準の WhatsApp システムプロンプト規則については WhatsApp を参照してください。

# WhatsApp 固有事項

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

# 関連

• ブロードキャストグループ
• チャンネルルーティング
• グループメッセージ
• ペアリング