Configuration

Сообщения группы WhatsApp

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

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

Поведение

Режимы активации: mention (по умолчанию) или always. mention требует обращения (настоящие @-упоминания WhatsApp через mentionedJids, безопасные regex-шаблоны или E.164 бота в любом месте текста). always пробуждает агента на каждое сообщение, но он должен отвечать только тогда, когда может добавить осмысленную пользу; иначе он возвращает точный токен молчания NO_REPLY / 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, /trace on или /think high (отправленные как отдельные сообщения) ограничены этой группой; состояние личного DM не затрагивается. Heartbeat пропускаются для групповых тредов.
Внедрение контекста: только ожидающие групповые сообщения (по умолчанию 50), которые не запустили выполнение, добавляются с префиксом под [Chat messages since your last reply - for context], а запускающая строка помещается под [Current message - respond to this]. Сообщения, уже находящиеся в сеансе, повторно не внедряются.
Отображение отправителя: каждый групповой пакет теперь заканчивается [from: Sender Name (+E164)], чтобы OpenClaw понимал, кто говорит.
Эфемерные/view-once: мы разворачиваем их перед извлечением текста/упоминаний, поэтому обращения внутри них все равно запускают агента.
Системный промпт группы: на первом ходе группового сеанса (и всякий раз, когда /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

{  channels: {    whatsapp: {      groups: {        "*": { requireMention: true },      },    },  },  agents: {    list: [      {        id: "main",        groupChat: {          historyLimit: 50,          mentionPatterns: ["@?openclaw", "\\+?15555550123"],        },      },    ],  },}

Примечания:

Regex-шаблоны нечувствительны к регистру и используют те же ограничения безопасных regex, что и другие конфигурационные поверхности regex; недопустимые шаблоны и небезопасные вложенные повторения игнорируются.
WhatsApp все равно отправляет канонические упоминания через mentionedJids, когда кто-то нажимает контакт, поэтому резервный вариант с номером нужен редко, но он полезен как подстраховка.

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

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

/activation mention
/activation always

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

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

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

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

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

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

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

Связанные материалы

Was this useful?