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> і текст із позначкою відправника.

Відомі особливості

Heartbeats виконуються в основному сеансі агента; у групових сеансах запуски Heartbeat ніколи не виконуються.
Механізм придушення відлуння запам'ятовує об'єднану підказку (історію та поточне повідомлення) для кожного сеансу, щоб доставлені повідомлення самого бота не спричиняли повторну активацію; ідентичний повторно надісланий пакет може бути пропущений як відлуння.
Записи сховища сеансів відображаються як agent:<agentId>:whatsapp:group:<jid> у сховищі сеансів SQLite відповідного агента; відсутність запису лише означає, що група ще не спричиняла запуск.
Індикатори введення тексту керуються session.typingMode / agents.defaults.typingMode. Коли для видимих відповідей увімкнено режим надсилання лише через інструмент повідомлень, індикатор введення типово з'являється відразу, щоб учасники групи бачили роботу агента, навіть якщо автоматичну остаточну відповідь не буде опубліковано. Явна конфігурація режиму введення тексту все одно має пріоритет.

Пов’язані матеріали

Was this useful?