Configuration

Сообщения в группах WhatsApp

Описание модели групп для разных каналов (Discord, iMessage, Matrix, Microsoft Teams, QQBot, Signal, Slack, Telegram, WhatsApp, Zalo) см. в разделе Группы. На этой странице рассматривается специфичное для WhatsApp поведение поверх этой модели: активация, списки разрешённых групп, ключи сеансов для отдельных групп и внедрение контекста ожидающих сообщений.

Цель: позволить OpenClaw находиться в группах WhatsApp, активироваться только при упоминании и вести эту ветку отдельно от личного сеанса в переписке.

Поведение

Режимы активации: mention (по умолчанию) или always. Для mention требуется обращение: настоящее @-упоминание в WhatsApp (mentionedJids), настроенный шаблон регулярного выражения, цифры номера бота в формате E.164 в любом месте текста или ответ с цитированием одного из сообщений бота (кроме конфигураций с перепиской с самим собой при общем номере). always активирует агента при каждом сообщении, но внедрённая групповая подсказка предписывает отвечать только тогда, когда ответ полезен, а в остальных случаях возвращать точный токен молчания NO_REPLY (без учёта регистра). Значения по умолчанию берутся из конфигурации (channels.whatsapp.groups requireMention) и могут быть переопределены для каждой группы через /activation.
Список разрешённых групп: если задан channels.whatsapp.groups, допускаются только указанные JID групп (добавьте "*", чтобы разрешить все); сообщения из групп, отсутствующих в списке, отбрасываются с пояснением в журнале.
Политика групп: channels.whatsapp.groupPolicy определяет, принимаются ли групповые сообщения (open|disabled|allowlist). allowlist использует channels.whatsapp.groupAllowFrom (резервный вариант: явно заданный channels.whatsapp.allowFrom). Значение по умолчанию — allowlist (сообщения блокируются, пока вы не добавите отправителей).
Сеансы для отдельных групп: ключи сеансов имеют вид agent:<agentId>:whatsapp:group:<jid> (для учётных записей не по умолчанию добавляется :thread:whatsapp-account-<accountId>), поэтому область действия таких директив, как /verbose on, /trace on или /think high (отправленных отдельными сообщениями), ограничена этой группой; состояние личной переписки не изменяется.
Внедрение контекста: только ожидающие групповые сообщения (по умолчанию 50), которые не запустили выполнение, добавляются с префиксом в разделе [Chat messages since your last reply - for context], а строка, вызвавшая запуск, — в разделе [Current message - respond to this]. После выполнения окно ожидающих сообщений очищается; сообщения, уже находящиеся в сеансе, повторно не внедряются.
Атрибуция отправителя: каждая строка группы содержит метку отправителя внутри конверта сообщения, например [WhatsApp <groupJid> <timestamp>] Alice (+447700900123): text, а идентификатор отправителя, тема группы и список участников передаются вместе с ней в недоверенном блоке метаданных разговора.
Исчезающие сообщения и однократный просмотр: оболочки снимаются до извлечения текста и упоминаний, поэтому находящиеся внутри них обращения по-прежнему вызывают активацию.
Системная подсказка группы: на первом ходе группового сеанса (и на любом ходе после изменения режима через /activation) в системную подсказку внедряются инструкции по активации (Activation: trigger-only ... или Activation: always-on ..., а также «обращайтесь к конкретному отправителю»). Постоянные инструкции по отправке сообщений в групповой чат («Вы находитесь в групповом чате WhatsApp…») включаются всегда.

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

Обеспечьте работу обращений по отображаемому имени, даже если WhatsApp удаляет визуальный символ @ из текста сообщения:

json5

{  channels: {    whatsapp: {      groups: {        "*": { requireMention: true },      },      historyLimit: 50, // окно контекста ожидающих сообщений группы (по умолчанию 50)    },  },  agents: {    list: [      {        id: "main",        groupChat: {          mentionPatterns: ["@?openclaw", "\\+?15555550123"],        },      },    ],  },}

Примечания:

Регулярные выражения не учитывают регистр и используют те же ограничения безопасных регулярных выражений, что и другие параметры конфигурации с регулярными выражениями; недопустимые шаблоны и небезопасные вложенные повторения игнорируются.
Когда пользователь нажимает на контакт, WhatsApp по-прежнему отправляет канонические упоминания через mentionedJids, поэтому резервный вариант с номером требуется редко, но служит полезной защитой.
Размер окна ожидающего контекста определяется в следующем порядке: channels.whatsapp.accounts.<id>.historyLimit → channels.whatsapp.historyLimit → messages.groupChat.historyLimit → 50.

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

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

/activation mention
/activation always

Изменить этот параметр могут только номера владельцев (из channels.whatsapp.allowFrom или собственный номер бота в формате E.164, если параметр не задан); /activation от любого другого пользователя игнорируется и сохраняется только как контекст. Чтобы увидеть текущий режим активации, отправьте /status отдельным сообщением в группу.

Использование

Добавьте свою учётную запись WhatsApp (ту, в которой работает OpenClaw) в группу.
Отправьте @openclaw ... (или укажите номер). Активировать агента могут только отправители из списка разрешённых, если не задан groupPolicy: "open".
Подсказка агента содержит контекст ожидающих сообщений группы и строки с метками отправителей, чтобы агент мог обратиться к нужному человеку.
Директивы сеанса (/verbose on, /trace on, /think high, /new или /reset, /compact) применяются только к сеансу этой группы; отправляйте их отдельными сообщениями, чтобы они были зарегистрированы. Ваш личный сеанс переписки остаётся независимым.

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

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

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

Heartbeat выполняются в основном сеансе агента; в групповых сеансах Heartbeat никогда не запускаются.
Для подавления эха по каждому сеансу запоминается объединённая подсказка (история и текущее сообщение), поэтому доставленные сообщения самого бота не активируют его повторно; идентичный повторный пакет может быть пропущен как эхо.
Записи хранилища сеансов отображаются как agent:<agentId>:whatsapp:group:<jid> в хранилище сеансов SQLite каждого агента; отсутствие записи означает лишь то, что группа ещё не запускала выполнение.
Индикаторы набора текста соответствуют session.typingMode / agents.defaults.typingMode. Если для видимых ответов выбран режим отправки только через инструмент сообщений, по умолчанию индикатор набора включается немедленно, чтобы участники группы видели, что агент работает, даже если автоматический итоговый ответ не публикуется. Явная настройка режима набора текста по-прежнему имеет приоритет.

Связанные разделы

Was this useful?