WhatsApp

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

Встановлення

openclaw onboard і openclaw channels add --channel whatsapp пропонують установити Plugin, коли ви вперше його вибираєте; openclaw channels login --channel whatsapp пропонує той самий процес встановлення, якщо Plugin відсутній. Середовища розробки використовують локальний шлях до Plugin; стабільні та бета-версії спочатку встановлюють @openclaw/whatsapp із ClawHub, а в разі невдачі — з npm. Середовище виконання WhatsApp постачається поза основним npm-пакетом OpenClaw, тому його залежності середовища виконання залишаються із зовнішнім Plugin. Встановлення вручну:

openclaw plugins install clawhub:@openclaw/whatsapp

Використовуйте пакет npm без префікса (@openclaw/whatsapp) лише як резервний варіант реєстру; фіксуйте точну версію лише для відтворюваного встановлення.

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

{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-authopenclaw channels login --channel whatsapp --account work

openclaw gateway

openclaw pairing list whatsappopenclaw pairing approve whatsapp <CODE>

Схеми розгортання

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

Модель середовища виконання

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

Виклик поточного запитувача через MeowCaller (експериментальна функція)

Plugin може надавати whatsapp_call у запусках агента, ініційованих із WhatsApp. Він використовує MeowCaller, щоб здійснити голосовий виклик у WhatsApp поточному авторизованому запитувачу та відтворити повідомлення OpenClaw із синтезом мовлення після відповіді. Інструмент не має параметра номера призначення, тому запит не може перенаправити виклик. Типово вимкнено.

{"channels": {"whatsapp": {  "actions": {    "calls": true  }}}}

git clone --branch feat/send-only-notify https://github.com/steipete/meowcaller.gitcd meowcallergit checkout 752050471fc2bf7a8cdfbf7dbd3cd4e865d85d3fmkdir -p "$HOME/.local/bin"go build -o "$HOME/.local/bin/meowcaller" ./cmd/meowcaller

state_dir="$HOME/.openclaw/credentials/whatsapp-calls/default"mkdir -p "$state_dir"chmod 700 "$state_dir"meowcaller pair --store "$state_dir/wa-voip.db"

Обмеження: лише вихідні аудіовиклики один на один, без довільних номерів призначення, без спільної автентифікації зі з’єднанням чату, без викликів самому собі в режимі особистого номера або чату із самим собою, тривалість синтезованого аудіо обмежена 60 секундами, без підтвердження чутності на боці слухавки, крім завершення етапів відповіді, відтворення та завершення виклику MeowCaller; OpenClaw зупиняє супровідний процес після обмеженого вікна тривалістю 115–175 секунд (що охоплює етапи підключення, відповіді, відтворення та завершення роботи MeowCaller).

Запити на схвалення

WhatsApp може відображати запити на схвалення виконання команд і дій Plugin як реакції 👍/👎, керовані конфігурацією пересилання схвалень верхнього рівня:

{  approvals: {    exec: {      enabled: true,      mode: "session",    },    plugin: {      enabled: true,      mode: "targets",      targets: [{ channel: "whatsapp", to: "+15551234567" }],    },  },}

approvals.exec і approvals.plugin є незалежними; увімкнення WhatsApp як каналу лише пов’язує транспорт і нічого не надсилає, якщо відповідну категорію схвалень не ввімкнено та не спрямовано туди. У режимі сеансу власні схвалення емодзі доставляються лише для схвалень, що походять із WhatsApp. Режим цілей використовує спільний конвеєр пересилання для явно заданих цілей і не створює окремого розгалуженого надсилання особистих повідомлень схвалювачам.

Для реакцій схвалення WhatsApp потрібні явно вказані схвалювачі в allowFrom (або "*"). defaultTo задає звичайні типові цілі повідомлень, а не список схвалювачів. Команди /approve, введені вручну, усе одно проходять звичайний шлях авторизації відправника WhatsApp перед визначенням схвалення.

Хуки Plugin і конфіденційність

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

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

Обмежте цю згоду одним обліковим записом у channels.whatsapp.accounts.<id>.pluginHooks.messageReceived. Вмикайте це лише для плагінів, яким ви довіряєте вхідний вміст та ідентифікатори WhatsApp.

Керування доступом і активація

Налаштовані прив’язки ACP

WhatsApp підтримує постійні прив’язки ACP через bindings[] верхнього рівня:

{  bindings: [    {      type: "acp",      agentId: "codex",      match: {        channel: "whatsapp",        accountId: "work",        peer: { kind: "direct", id: "+15555550123" },      },    },    {      type: "acp",      agentId: "codex",      match: {        channel: "whatsapp",        accountId: "work",        peer: { kind: "group", id: "120363424282127706@g.us" },      },    },  ],}

Особисті чати зіставляються з номерами E.164, а групи — з груповими JID WhatsApp. Списки дозволених груп, політика щодо відправників і перевірки активації згадкою виконуються до того, як OpenClaw забезпечить існування прив’язаного сеансу ACP. Зіставлена прив’язка керує маршрутом — групи широкомовлення не розгалужують цей хід на звичайні сеанси WhatsApp.

Поведінка особистого номера та чату із собою

Коли прив’язаний власний номер також присутній в allowFrom, активуються запобіжники для чату із собою: сповіщення про прочитання для таких ходів пропускаються, поведінка автоматичного запуску за JID згадки, яка призвела б до сповіщення самого себе, ігнорується, а відповіді за замовчуванням отримують префікс [{identity.name}] (або [openclaw]), якщо messages.responsePrefix не задано.

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

[Відповідь для <sender> id:<stanzaId>]<цитований текст або заповнювач медіафайлу>[/Відповідь]

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

Доставка, поділ на частини та медіафайли

Цитування у відповідях

channels.whatsapp.replyToMode керує нативним цитуванням у відповідях (вихідні відповіді видимо цитують вхідне повідомлення):

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

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

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

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

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

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

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

channels.whatsapp.ackReaction надсилає негайну реакцію після отримання вхідного повідомлення з урахуванням reactionLevel (пригнічується за значення "off"):

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

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

Реакції стану життєвого циклу

Установіть messages.statusReactions.enabled: true, щоб WhatsApp під час ходу замінював реакцію-підтвердження, а не залишав статичний емодзі отримання, циклічно змінюючи стани, як-от очікування в черзі, обдумування, активність інструментів, Compaction, завершення та помилка:

{  messages: {    statusReactions: {      enabled: true,      emojis: {        deploy: "🛫",        build: "🏗️",        concierge: "💁",      },    },  },}

Примітки: channels.whatsapp.ackReaction і надалі визначає доступність для особистих повідомлень і груп; стан очікування в черзі використовує той самий ефективний емодзі, що й звичайні реакції-підтвердження; WhatsApp має одне місце для реакції бота на повідомлення, тому оновлення життєвого циклу замінюють поточну реакцію на місці; messages.removeAckAfterReply: true видаляє остаточну реакцію стану після налаштованої затримки для стану завершення або помилки; категорії емодзі інструментів охоплюють tool, coding, web, deploy, build і concierge.

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

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

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

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

openclaw channels login --channel whatsappopenclaw channels status

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

openclaw channels status --probeopenclaw doctoropenclaw logs --followopenclaw gateway status

cp -a ~/.openclaw/credentials/whatsapp/<accountId> \  ~/.openclaw/credentials/whatsapp/<accountId>.bakopenclaw channels logout --channel whatsapp --account <accountId>openclaw channels login --channel whatsapp --account <accountId>

Системні підказки

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

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

1. Підказка для конкретної групи (groups["<groupId>"].systemPrompt): використовується, коли запис групи існує і його ключ systemPrompt визначено. Порожній рядок ("") пригнічує шаблон і не застосовує жодної підказки.
2. Групова підказка-шаблон (groups["*"].systemPrompt): використовується, коли запис конкретної групи відсутній або існує без ключа systemPrompt.

Визначення для приватних повідомлень відбувається за ідентичною схемою для мапи direct і direct["*"].

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

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

• channels.whatsapp.groups є одночасно мапою конфігурації для окремих груп і списком дозволів груп на рівні чатів. На кореневому рівні або рівні облікового запису groups["*"] означає «дозволено всі групи» для цієї області.
• Додавайте шаблонний systemPrompt, лише якщо вже хочете дозволити всі групи в цій області. Щоб залишити доступним лише фіксований набір ідентифікаторів груп, повторіть підказку в кожному явно дозволеному записі замість використання groups["*"].
• Допуск групи й авторизація відправника — це окремі перевірки. groups["*"] розширює перелік груп, повідомлення яких надходять до обробки груп; він не авторизує кожного відправника в цих групах — це й надалі контролюється через groupPolicy/groupAllowFrom.
• channels.whatsapp.direct не має аналогічного побічного ефекту для приватних повідомлень: direct["*"] лише надає типову конфігурацію після того, як приватне повідомлення вже допущено правилами dmPolicy разом із allowFrom або правилами сховища пов’язування.

Приклад:

{  channels: {    whatsapp: {      groups: {        // Використовуйте, лише якщо на кореневому рівні потрібно дозволити всі групи.        // Застосовується до всіх облікових записів, які не визначають власну мапу groups.        "*": { systemPrompt: "Типова підказка для всіх груп." },      },      direct: {        // Застосовується до всіх облікових записів, які не визначають власну мапу direct.        "*": { systemPrompt: "Типова підказка для всіх приватних чатів." },      },      accounts: {        work: {          groups: {            // Цей обліковий запис визначає власний groups, тому кореневий groups повністю            // замінюється. Щоб зберегти шаблон, також явно визначте тут "*".            "120363406415684625@g.us": {              requireMention: false,              systemPrompt: "Зосереджуйтеся на керуванні проєктами.",            },            // Використовуйте, лише якщо в цьому обліковому записі потрібно дозволити всі групи.            "*": { systemPrompt: "Типова підказка для робочих груп." },          },          direct: {            // Цей обліковий запис визначає власну мапу direct, тому кореневі записи direct            // повністю замінюються. Щоб зберегти шаблон, також явно визначте тут "*".            "+15551234567": { systemPrompt: "Підказка для конкретного робочого приватного чату." },            "*": { systemPrompt: "Типова підказка для робочих приватних чатів." },          },        },      },    },  },}

Посилання на довідник із конфігурації

Основний довідник: Довідник із конфігурації — WhatsApp

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

• Пов’язування
• Групи
• Безпека
• Маршрутизація каналів
• Маршрутизація між кількома агентами
• Усунення несправностей