WhatsApp

Стан: готовий до production через WhatsApp Web (Baileys). Gateway керує прив’язаними сеансами.

# Встановлення (на вимогу)

• Onboarding (openclaw onboard) і openclaw channels add --channel whatsapp пропонують встановити WhatsApp plugin під час першого вибору.
• openclaw channels login --channel whatsapp також пропонує процес встановлення, коли plugin ще відсутній.
• Dev-канал + git checkout: за замовчуванням використовує локальний шлях plugin.
• Stable/Beta: використовує npm-пакет @openclaw/whatsapp на поточному офіційному тегу релізу.

Ручне встановлення залишається доступним:

openclaw plugins install @openclaw/whatsapp

Використовуйте пакет без версії, щоб стежити за поточним офіційним тегом релізу. Закріплюйте точну версію лише тоді, коли потрібне відтворюване встановлення.

У Windows WhatsApp plugin потребує Git у PATH під час npm install, оскільки одна з його залежностей Baileys/libsignal завантажується з git URL. Встановіть Git for Windows, потім перезапустіть оболонку й повторіть встановлення:

winget install --id Git.Git -e

Portable Git також працює, якщо його каталог bin є в PATH.

# Швидке налаштування

{
channels: {
whatsapp: {
  dmPolicy: "pairing",
  allowFrom: ["+15551234567"],
  groupPolicy: "allowlist",
  groupAllowFrom: ["+15551234567"],
},
},
}

openclaw channels login --channel whatsapp

openclaw channels login --channel whatsapp --account work

openclaw channels add --channel whatsapp --account work --auth-dir /path/to/wa-auth
openclaw channels login --channel whatsapp --account work

openclaw gateway

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

# Шаблони розгортання

{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567"],
    },
  },
}

# Модель виконання

• Gateway керує сокетом WhatsApp і циклом повторного підключення.
• Watchdog повторного підключення використовує активність транспорту WhatsApp Web, а не лише обсяг вхідних повідомлень застосунку, тому тихий сеанс прив’язаного пристрою не перезапускається лише через те, що останнім часом ніхто не надсилав повідомлень. Довший ліміт тиші застосунку все одно примусово виконує повторне підключення, якщо транспортні кадри продовжують надходити, але жодні повідомлення застосунку не обробляються протягом вікна watchdog; після тимчасового повторного підключення для нещодавно активного сеансу ця перевірка тиші застосунку використовує звичайний таймаут повідомлень для першого вікна відновлення.
• Таймінги сокета Baileys явно задаються в web.whatsapp.*: keepAliveIntervalMs керує ping-ами застосунку WhatsApp Web, connectTimeoutMs керує таймаутом початкового handshake, а defaultQueryTimeoutMs керує таймаутами запитів Baileys.
• Вихідні надсилання потребують активного слухача WhatsApp для цільового облікового запису.
• Групові надсилання додають нативні метадані згадок для токенів @+<digits> і @<digits> у тексті та підписах медіа, коли токен збігається з поточними метаданими учасників WhatsApp, включно з групами на базі LID.
• Чати статусів і трансляцій ігноруються (@status, @broadcast).
• Watchdog повторного підключення відстежує активність транспорту WhatsApp Web, а не лише обсяг вхідних повідомлень застосунку: тихі сеанси прив’язаного пристрою залишаються активними, доки транспортні кадри продовжують надходити, але зупинка транспорту примусово викликає повторне підключення задовго до пізнішого шляху віддаленого відключення.
• Прямі чати використовують правила DM-сеансів (session.dmScope; типове значення main згортає DM-и до головного сеансу агента).
• Групові сеанси ізольовані (agent:<agentId>:whatsapp:group:<jid>).
• WhatsApp Channels/Newsletters можуть бути явними вихідними цілями з їхнім нативним JID @newsletter. Вихідні надсилання до newsletter використовують метадані сеансу каналу (agent:<agentId>:whatsapp:channel:<jid>), а не семантику DM-сеансу.
• Транспорт WhatsApp Web враховує стандартні змінні середовища proxy на хості gateway (HTTPS_PROXY, HTTP_PROXY, NO_PROXY / варіанти в нижньому регістрі). Надавайте перевагу конфігурації proxy на рівні хоста замість налаштувань proxy WhatsApp, специфічних для каналу.
• Коли messages.removeAckAfterReply увімкнено, OpenClaw очищає ack-реакцію WhatsApp після доставки видимої відповіді.

# Хуки Plugin і приватність

Вхідні повідомлення WhatsApp можуть містити особистий вміст повідомлень, телефонні номери, ідентифікатори груп, імена відправників і поля кореляції сеансу. З цієї причини WhatsApp не транслює вхідні payload-и хуку message_received до plugins, якщо ви явно не погодитеся:

{
  channels: {
    whatsapp: {
      pluginHooks: {
        messageReceived: true,
      },
    },
  },
}

Можна обмежити згоду одним обліковим записом:

{
  channels: {
    whatsapp: {
      accounts: {
        work: {
          pluginHooks: {
            messageReceived: true,
          },
        },
      },
    },
  },
}

Умикайте це лише для plugins, яким ви довіряєте отримувати вхідний вміст повідомлень WhatsApp та ідентифікатори.

# Контроль доступу та активація

# Особистий номер і поведінка чату із самим собою

Коли прив’язаний власний номер також присутній в allowFrom, активуються захисти чату WhatsApp із самим собою:

• пропускати підтвердження прочитання для ходів чату із самим собою
• ігнорувати поведінку автоматичного запуску mention-JID, яка інакше ping-ала б вас самих
• якщо messages.responsePrefix не задано, відповіді в чаті із самим собою за замовчуванням мають префікс [{identity.name}] або [openclaw]

# Нормалізація повідомлень і контекст

[Replying to <sender> id:<stanzaId>]
<quoted body or media placeholder>
[/Replying]

{
  channels: {
    whatsapp: {
      sendReadReceipts: false,
    },
  },
}

{
  channels: {
    whatsapp: {
      accounts: {
        work: {
          sendReadReceipts: false,
        },
      },
    },
  },
}

# Доставка, розбиття на фрагменти та медіа

# Цитування відповідей

WhatsApp підтримує нативне цитування відповідей, коли вихідні відповіді видимо цитують вхідне повідомлення. Керуйте цим за допомогою channels.whatsapp.replyToMode.

За замовчуванням: "off". Перевизначення для окремого облікового запису використовують channels.whatsapp.accounts.<id>.replyToMode.

{
  channels: {
    whatsapp: {
      replyToMode: "first",
    },
  },
}

# Рівень реакцій

channels.whatsapp.reactionLevel керує тим, наскільки широко агент використовує emoji-реакції у WhatsApp:

За замовчуванням: "minimal".

Перевизначення для окремого облікового запису використовують channels.whatsapp.accounts.<id>.reactionLevel.

{
  channels: {
    whatsapp: {
      reactionLevel: "ack",
    },
  },
}

# Реакції підтвердження

WhatsApp підтримує негайні реакції підтвердження на вхідне отримання через channels.whatsapp.ackReaction. Реакції підтвердження обмежуються reactionLevel — вони пригнічуються, коли reactionLevel дорівнює "off".

{
  channels: {
    whatsapp: {
      ackReaction: {
        emoji: "👀",
        direct: true,
        group: "mentions", // always | mentions | never
      },
    },
  },
}

Примітки щодо поведінки:

• надсилаються негайно після прийняття вхідного повідомлення (до відповіді)
• помилки журналюються, але не блокують звичайну доставку відповіді
• режим групи mentions реагує на ходи, запущені згадкою; активація групи always діє як обхід цієї перевірки
• WhatsApp використовує channels.whatsapp.ackReaction (застаріле messages.ackReaction тут не використовується)

# Кілька облікових записів і облікові дані

# Інструменти, дії та записи конфігурації

• Підтримка інструментів агента включає дію реакції WhatsApp (react).
• Обмеження дій:
  • channels.whatsapp.actions.reactions
  • channels.whatsapp.actions.polls
• Записи конфігурації, ініційовані каналом, увімкнені за замовчуванням (вимикаються через channels.whatsapp.configWrites=false).

# Усунення несправностей

openclaw channels login --channel whatsapp
openclaw channels status

{
  web: {
    whatsapp: {
      keepAliveIntervalMs: 15000,
      connectTimeoutMs: 60000,
      defaultQueryTimeoutMs: 60000,
    },
  },
}

openclaw doctor
openclaw logs --follow

# Системні prompts

WhatsApp підтримує системні prompts у стилі Telegram для груп і прямих чатів через мапи groups і direct.

Ієрархія вирішення для групових повідомлень:

Ефективна мапа groups визначається першою: якщо обліковий запис визначає власну groups, вона повністю замінює кореневу мапу groups (без глибокого злиття). Пошук prompt потім виконується в отриманій єдиній мапі:

1. Системний prompt для конкретної групи (groups["<groupId>"].systemPrompt): використовується, коли конкретний запис групи існує в мапі і його ключ systemPrompt визначений. Якщо systemPrompt є порожнім рядком (""), wildcard пригнічується, і системний prompt не застосовується.
2. Wildcard системного prompt групи (groups["*"].systemPrompt): використовується, коли конкретний запис групи повністю відсутній у мапі або коли він існує, але не визначає ключ systemPrompt.

Ієрархія вирішення для прямих повідомлень:

Ефективна мапа direct визначається першою: якщо обліковий запис визначає власну direct, вона повністю замінює кореневу мапу direct (без глибокого злиття). Пошук prompt потім виконується в отриманій єдиній мапі:

1. Системний промпт для конкретного direct (direct["<peerId>"].systemPrompt): використовується, коли конкретний запис peer існує в мапі і його ключ systemPrompt визначено. Якщо systemPrompt є порожнім рядком (""), wildcard пригнічується, і системний промпт не застосовується.
2. Wildcard системного промпту direct (direct["*"].systemPrompt): використовується, коли конкретний запис peer повністю відсутній у мапі або коли він існує, але не визначає ключ systemPrompt.

Відмінність від поведінки Telegram з кількома обліковими записами: У Telegram кореневий groups навмисно пригнічується для всіх облікових записів у конфігурації з кількома обліковими записами — навіть для тих, що не визначають власних groups — щоб бот не отримував групові повідомлення для груп, до яких він не належить. WhatsApp не застосовує цей захист: кореневі groups і кореневий direct завжди успадковуються обліковими записами, які не визначають перевизначення на рівні облікового запису, незалежно від кількості налаштованих облікових записів. У конфігурації WhatsApp з кількома обліковими записами, якщо вам потрібні групові або direct-промпти для кожного облікового запису окремо, визначайте повну мапу явно в кожному обліковому записі, а не покладайтеся на кореневі значення за замовчуванням.

Важлива поведінка:

• channels.whatsapp.groups є одночасно мапою конфігурації для окремих груп і allowlist груп на рівні чату. На кореневому рівні або в scope облікового запису groups["*"] означає "допущено всі групи" для цього scope.
• Додавайте wildcard групового systemPrompt лише тоді, коли ви вже хочете, щоб цей scope допускав усі групи. Якщо ви все ще хочете, щоб придатним був лише фіксований набір ID груп, не використовуйте groups["*"] як значення промпту за замовчуванням. Натомість повторіть промпт у кожному явно внесеному до allowlist записі групи.
• Допуск групи й авторизація відправника є окремими перевірками. groups["*"] розширює набір груп, які можуть досягати обробки груп, але сам по собі не авторизує кожного відправника в цих групах. Доступ відправника все ще окремо контролюється channels.whatsapp.groupPolicy і channels.whatsapp.groupAllowFrom.
• channels.whatsapp.direct не має такого самого побічного ефекту для DM. direct["*"] лише надає конфігурацію direct-чату за замовчуванням після того, як DM уже допущено через dmPolicy плюс allowFrom або правила pairing-store.

Приклад:

{
  channels: {
    whatsapp: {
      groups: {
        // Use only if all groups should be admitted at the root scope.
        // Applies to all accounts that do not define their own groups map.
        "*": { systemPrompt: "Default prompt for all groups." },
      },
      direct: {
        // Applies to all accounts that do not define their own direct map.
        "*": { systemPrompt: "Default prompt for all direct chats." },
      },
      accounts: {
        work: {
          groups: {
            // This account defines its own groups, so root groups are fully
            // replaced. To keep a wildcard, define "*" explicitly here too.
            "[email protected]": {
              requireMention: false,
              systemPrompt: "Focus on project management.",
            },
            // Use only if all groups should be admitted in this account.
            "*": { systemPrompt: "Default prompt for work groups." },
          },
          direct: {
            // This account defines its own direct map, so root direct entries are
            // fully replaced. To keep a wildcard, define "*" explicitly here too.
            "+15551234567": { systemPrompt: "Prompt for a specific work direct chat." },
            "*": { systemPrompt: "Default prompt for work direct chats." },
          },
        },
      },
    },
  },
}

# Вказівники довідника конфігурації

Основний довідник:

• Довідник конфігурації - WhatsApp

Найважливіші поля WhatsApp:

• доступ: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
• доставка: textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction, reactionLevel
• кілька облікових записів: accounts.<id>.enabled, accounts.<id>.authDir, перевизначення на рівні облікового запису
• операції: configWrites, debounceMs, web.enabled, web.heartbeatSeconds, web.reconnect.*, web.whatsapp.*
• поведінка сеансу: session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit
• промпти: groups.<id>.systemPrompt, groups["*"].systemPrompt, direct.<id>.systemPrompt, direct["*"].systemPrompt

# Пов’язане

• Сполучення
• Групи
• Безпека
• Маршрутизація каналів
• Маршрутизація кількох агентів
• Усунення несправностей