Группы

OpenClaw обрабатывает групповые чаты единообразно на всех платформах: WhatsApp, Telegram, Discord, Slack, Signal, iMessage, Microsoft Teams, Zalo.

Введение для начинающих (2 минуты)

OpenClaw «живёт» на ваших собственных аккаунтах мессенджеров. Отдельного пользователя-бота WhatsApp нет. Если вы состоите в группе, OpenClaw может видеть эту группу и отвечать там.

Поведение по умолчанию:

Группы ограничены (groupPolicy: "allowlist").
Ответы требуют упоминания, если вы явно не отключите гейтинг по упоминанию.

Иначе говоря: авторизованные отправители могут активировать OpenClaw, упомянув его.

TL;DR

Доступ к ЛС контролируется через *.allowFrom.

Доступ к группам контролируется через *.groupPolicy + списки доступа (*.groups, *.groupAllowFrom).

Активация ответа контролируется гейтингом по упоминанию (requireMention, /activation).

Быстрый поток (что происходит с групповым сообщением):

groupPolicy? disabled -> отброс
groupPolicy? allowlist -> группа разрешена? нет -> отброс
requireMention? yes -> упомянут? нет -> сохранить только для контекста
иначе -> ответить

Поток групповых сообщений

Если вы хотите…

Цель	Что настроить
Разрешить все группы, но отвечать только на @	`groups: { "*": { requireMention: true } }`
Отключить все ответы в группах	`groupPolicy: "disabled"`
Только определённые группы	`groups: { "<group-id>": { ... } }` (без ключа `"*"`)
Только вы можете активировать бота в группах	`groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]`

Ключи сессий

Групповые сессии используют ключи agent:<agentId>:<channel>:group:<id> (комнаты/каналы используют agent:<agentId>:<channel>:channel:<id>).
Темы форумов Telegram добавляют :topic:<threadId> к ID группы, чтобы каждая тема имела свою сессию.
Прямые чаты используют основную сессию (или по отправителю, если настроено).
Heartbeat-ы пропускаются для групповых сессий.

Паттерн: личные ЛС + публичные группы (один агент)

Да — это хорошо работает, если ваш «личный» трафик — ЛС, а «публичный» — группы.

Почему: в режиме одного агента ЛС обычно попадают в основную сессию (agent:main:main), а группы всегда используют неосновные ключи сессий (agent:main:<channel>:group:<id>). Если вы включите песочницу с mode: "non-main", групповые сессии будут выполняться в Docker, а основная ЛС-сессия останется на хосте.

Это даёт один «мозг» агента (общее рабочее пространство + память), но два режима выполнения:

ЛС: полные инструменты (хост)
Группы: песочница + ограниченные инструменты (Docker)

Если вам нужны действительно отдельные рабочие пространства/персоны («личное» и «публичное» не должны смешиваться), используйте второго агента + привязки. См. Мульти-агентная маршрутизация.

Пример (ЛС на хосте, группы в песочнице + только инструменты обмена сообщениями):

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // группы/каналы — неосновные -> в песочнице
        scope: "session", // сильнейшая изоляция (один контейнер на группу/канал)
        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",
          ],
        },
      },
    },
  },
}

Связанное:

Ключи конфигурации и значения по умолчанию: Конфигурация шлюза
Диагностика блокировки инструмента: Песочница vs Политика инструментов vs Elevated
Подробности bind mount: Песочница

Метки отображения

UI-метки используют displayName при наличии, форматируются как <channel>:<token>.
#room зарезервирован для комнат/каналов; групповые чаты используют g-<slug> (нижний регистр, пробелы -> -, сохраняются #@+._-).

Групповая политика

Управление обработкой групповых/комнатных сообщений для каждого канала:

{
  channels: {
    whatsapp: {
      groupPolicy: "disabled", // "open" | "disabled" | "allowlist"
      groupAllowFrom: ["+15551234567"],
    },
    telegram: {
      groupPolicy: "disabled",
      groupAllowFrom: ["123456789"], // числовой Telegram user id (мастер может разрешить @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 (fallback: явный allowFrom).
Подтверждения спаривания ЛС (записи *-allowFrom в хранилище) применяются только к доступу ЛС; авторизация отправителей в группах остаётся явной через списки доступа групп.
Discord: список доступа использует channels.discord.guilds.<id>.channels.
Slack: список доступа использует channels.slack.channels.
Matrix: список доступа использует channels.matrix.groups (ID комнат, алиасы или имена). Используйте channels.matrix.groupAllowFrom для ограничения отправителей; поддерживаются также списки users для конкретных комнат.
Групповые ЛС контролируются отдельно (channels.discord.dm.*, channels.slack.dm.*).
Telegram может сопоставлять user ID ("123456789", "telegram:123456789", "tg:123456789") или имена пользователей ("@alice" или "alice"); префиксы регистронезависимы.
По умолчанию groupPolicy: "allowlist"; если список доступа групп пуст, групповые сообщения блокируются.
Безопасность при отсутствии блока провайдера (channels.<provider> отсутствует): групповая политика использует fail-closed (обычно allowlist) вместо наследования channels.defaults.groupPolicy.

Ментальная модель (порядок проверки групповых сообщений):

groupPolicy (open/disabled/allowlist)
списки доступа групп (*.groups, *.groupAllowFrom, специфичный для канала список)
гейтинг по упоминанию (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 — регистронезависимые regex-выражения.
Платформы с нативными упоминаниями всё равно проходят; паттерны — запасной вариант.
Переопределение для агента: 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:.

Порядок разрешения (побеждает наиболее специфичное):

toolsBySender группы/канала
tools группы/канала
toolsBySender по умолчанию ("*")
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 настроены, ключи действуют как список доступа групп. Используйте "*" для разрешения всех групп с настройкой поведения упоминания по умолчанию.

Распространённые намерения (скопируйте и вставьте):

Отключить все ответы в группах

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

Разрешить только определённые группы (WhatsApp)

{
  channels: {
    whatsapp: {
      groups: {
        "[email protected]": { requireMention: true },
        "[email protected]": { 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.

Поля контекста

Входящие данные групп содержат:

ChatType=group
GroupSubject (если известно)
GroupMembers (если известно)
WasMentioned (результат гейтинга по упоминанию)
Темы форумов Telegram также включают MessageThreadId и IsForum.

Системный промпт агента включает групповое введение при первом повороте новой групповой сессии. Оно напоминает модели отвечать как человек, избегать Markdown-таблиц и не писать буквальные последовательности \n.

Особенности iMessage

Предпочтительно chat_id:<id> при маршрутизации или добавлении в список доступа.
Список чатов: imsg chats --limit 20.
Ответы в группах всегда возвращаются в тот же chat_id.

Особенности WhatsApp

См. Групповые сообщения для поведения, специфичного для WhatsApp (инъекция истории, детали обработки упоминаний).