English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

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)], щоб 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 прибирає візуальний @ із тіла тексту:

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

Примітки:

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

Команда активації (лише власник)

Використовуйте команду групового чату:

  • /activation mention
  • /activation always

Змінити це може лише номер власника (з channels.whatsapp.allowFrom або власний E.164 бота, якщо не задано). Надішліть /status як окреме повідомлення в групі, щоб побачити поточний режим активації.

Як користуватися

  1. Додайте свій обліковий запис WhatsApp (той, на якому працює OpenClaw) до групи.
  2. Напишіть @openclaw … (або вкажіть номер). Запустити його можуть лише відправники зі списку дозволених, якщо ви не встановите groupPolicy: "open".
  3. Промпт агента міститиме нещодавній контекст групи плюс кінцевий маркер [from: …], щоб він міг звернутися до правильної людини.
  4. Директиви рівня сеансу (/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. Коли видимі відповіді використовують типовий режим лише через інструмент повідомлень, набір тексту типово починається негайно, щоб учасники групи бачили, що агент працює, навіть якщо автоматична фінальна відповідь не опублікована. Явна конфігурація режиму набору тексту все одно має пріоритет.

Повʼязане