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 поточному авторизованому запитувачу та відтворити повідомлення TTS від 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 до Plugin, якщо ви явно не погодилися:

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

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

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

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

{ 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

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

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