> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Групповые сообщения

# Групповые сообщения (веб-канал WhatsApp)

Цель: позволить Clawd находиться в группах WhatsApp, просыпаться только при пинге и держать этот тред отдельным от личного сеанса личных сообщений.

Примечание: `agents.list[].groupChat.mentionPatterns` теперь используется также Telegram/Discord/Slack/iMessage; этот документ сосредоточен на поведении, специфичном для WhatsApp. Для мультиагентных конфигураций задайте `agents.list[].groupChat.mentionPatterns` для каждого агента (или используйте `messages.groupChat.mentionPatterns` как глобальный запасной вариант).

## Что реализовано (2025-12-03)

* Режимы активации: `mention` (по умолчанию) или `always`. `mention` требует пинга (реальные WhatsApp @-упоминания через `mentionedJids`, regex-шаблоны или E.164 бота в любом месте текста). `always` пробуждает агента на каждом сообщении, но он должен отвечать только когда может добавить осмысленную ценность; в противном случае возвращается тихий токен `NO_REPLY`. Значения по умолчанию можно задать в конфигурации (`channels.whatsapp.groups`) и переопределять для каждой группы через `/activation`. Когда задан `channels.whatsapp.groups`, он также действует как список разрешённых групп (включите `"*"`, чтобы разрешить все).
* Политика групп: `channels.whatsapp.groupPolicy` управляет тем, принимаются ли групповые сообщения (`open|disabled|allowlist`). `allowlist` использует `channels.whatsapp.groupAllowFrom` (запасной вариант: явный `channels.whatsapp.allowFrom`). Значение по умолчанию — `allowlist` (заблокировано, пока вы не добавите отправителей).
* Сеансы на группу: ключи сеансов выглядят как `agent:<agentId>:whatsapp:group:<jid>`, поэтому команды вроде `/verbose on` или `/think high` (отправленные как отдельные сообщения) ограничены рамками этой группы; состояние личных сообщений не затрагивается. Сигналы keepalive пропускаются для групповых тредов.
* Инъекция контекста: **только ожидающие** групповые сообщения (по умолчанию 50), которые *не* запустили выполнение, добавляются префиксом под `[Chat messages since your last reply - for context]`, а строка-триггер — под `[Current message - respond to this]`. Сообщения, уже находящиеся в сеансе, повторно не инъецируются.
* Отображение отправителя: каждый пакет группы теперь завершается `[from: Sender Name (+E164)]`, чтобы Pi понимал, кто говорит.
* Эфемерные/«просмотреть один раз»: мы разворачиваем их перед извлечением текста/упоминаний, поэтому пинги внутри них всё равно срабатывают.
* Системный промпт группы: при первом ходе группового сеанса (и всякий раз, когда `/activation` меняет режим) мы вставляем короткий текст в системный промпт вроде `You are replying inside the WhatsApp group "<subject>". Group members: Alice (+44...), Bob (+43...), … Activation: trigger-only … Address the specific sender noted in the message context.`. Если метаданные недоступны, мы всё равно сообщаем агенту, что это групповой чат.

## Пример конфигурации (WhatsApp)

Добавьте блок `groupChat` в `~/.openclaw/openclaw.json`, чтобы пинги по отображаемому имени работали даже когда WhatsApp удаляет визуальное `@` из тела текста:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    whatsapp: {
      groups: {
        "*": { requireMention: true },
      },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          historyLimit: 50,
          mentionPatterns: ["@?openclaw", "\\+?15555550123"],
        },
      },
    ],
  },
}
```

Примечания:

* Регулярные выражения регистронезависимы; они покрывают пинг по отображаемому имени вроде `@openclaw` и «сырое» число с `+`/пробелами или без них.
* WhatsApp по-прежнему отправляет канонические упоминания через `mentionedJids`, когда кто-то нажимает на контакт, поэтому запасной вариант с номером редко нужен, но является полезной страховкой.

### Команда активации (только для владельца)

Используйте команду в групповом чате:

* `/activation mention`
* `/activation always`

Менять это может только номер владельца (из `channels.whatsapp.allowFrom` или собственный E.164 бота, если не задано). Отправьте `/status` отдельным сообщением в группе, чтобы увидеть текущий режим активации.

## Как использовать

1. Добавьте свой аккаунт WhatsApp (тот, на котором запущен OpenClaw) в группу.
2. Скажите `@openclaw …` (или укажите номер). Триггерить могут только отправители из списка разрешённых, если вы не установили `groupPolicy: "open"`.
3. Промпт агента будет включать недавний групповой контекст плюс завершающий маркер `[from: …]`, чтобы обратиться к нужному человеку.
4. Директивы уровня сеанса (`/verbose on`, `/think high`, `/new` или `/reset`, `/compact`) применяются только к сеансу этой группы; отправляйте их отдельными сообщениями, чтобы они зарегистрировались. Ваш личный сеанс личных сообщений остаётся независимым.

## Тестирование / проверка

* Ручной smoke-тест:
  * Отправьте пинг `@openclaw` в группе и подтвердите ответ, в котором упоминается имя отправителя.
  * Отправьте второй пинг и проверьте, что блок истории включён, а затем очищается на следующем ходе.
* Проверьте логи шлюза Gateway (запуск с `--verbose`), чтобы увидеть записи `inbound web message`, показывающие `from: <groupJid>` и суффикс `[from: …]`.

## Известные особенности

* Сигналы keepalive намеренно пропускаются для групп, чтобы избежать шумных рассылок.
* Подавление эха использует объединённую строку пакета; если отправить идентичный текст дважды без упоминаний, ответ будет только на первый.
* Записи хранилища сеансов будут выглядеть как `agent:<agentId>:whatsapp:group:<jid>` в хранилище сеансов (`~/.openclaw/agents/<agentId>/sessions/sessions.json` по умолчанию); отсутствие записи означает лишь, что группа ещё не запускала выполнение.
* Индикаторы набора текста в группах следуют `agents.defaults.typingMode` (по умолчанию: `message` при отсутствии упоминаний).