WhatsApp

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

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

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

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

openclaw plugins install clawhub:@openclaw/whatsapp

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

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

{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>

Виклик поточного запитувача за допомогою MeowCaller (експериментально)

Плагін WhatsApp може надавати whatsapp_call у WhatsApp-ініційованих ходах агента. Інструмент використовує MeowCaller, щоб здійснити голосовий виклик WhatsApp поточному авторизованому запитувачу та відтворити повідомлення OpenClaw TTS після відповіді. Інструмент не приймає номер призначення, тому prompt не може перенаправити виклик третій стороні. Ця експериментальна можливість вимкнена за замовчуванням.

{"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

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

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

Runtime-модель

• Gateway керує сокетом WhatsApp і циклом повторного підключення.
• Watchdog повторного підключення використовує транспортну активність WhatsApp Web, а не лише обсяг вхідних повідомлень застосунку, тому тихий сеанс пов’язаного пристрою не перезапускається лише через те, що ніхто не надсилав повідомлення останнім часом. Довше обмеження application-silence усе ще примусово виконує повторне підключення, якщо транспортні кадри продовжують надходити, але жодні повідомлення застосунку не обробляються протягом watchdog-вікна; після тимчасового повторного підключення для нещодавно активного сеансу ця перевірка application-silence використовує звичайний timeout повідомлення для першого вікна відновлення.
• Таймінги сокета Baileys явно задані в web.whatsapp.*: keepAliveIntervalMs керує application ping WhatsApp Web, connectTimeoutMs керує timeout початкового handshake, а defaultQueryTimeoutMs керує очікуваннями запитів Baileys плюс локальними межами операцій OpenClaw для вихідного надсилання/presence і вхідного read-receipt.
• Вихідні надсилання потребують активного слухача WhatsApp для цільового облікового запису.
• Групові надсилання додають нативні метадані згадок для токенів @+<digits> і @<digits> у тексті та підписах медіа, коли токен відповідає поточним метаданим учасника WhatsApp, включно з групами на базі LID.
• Чати статусів і broadcast ігноруються (@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 після доставки видимої відповіді.

Prompt-и схвалення

WhatsApp може рендерити prompt-и схвалення exec і плагіна за допомогою реакцій 👍 / 👎. Доставкою керує конфігурація пересилання схвалень верхнього рівня:

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

approvals.exec і approvals.plugin є незалежними. Увімкнення WhatsApp як каналу лише під’єднує транспорт; воно не надсилає prompt-и схвалення, якщо відповідну family схвалень не ввімкнено й не маршрутизовано до WhatsApp. Режим session доставляє нативні emoji-схвалення лише для схвалень, що походять із WhatsApp. Режим target використовує спільний pipeline пересилання для явних цілей WhatsApp і не створює окремий fanout approver-DM.

Реакції схвалення WhatsApp потребують явних approver-ів WhatsApp із allowFrom або "*". defaultTo керує звичайними стандартними цілями повідомлень; це не approver для схвалень. Ручні команди /approve усе ще проходять через звичайний шлях авторизації відправника WhatsApp перед вирішенням схвалення.

Хуки плагіна та приватність

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

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

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

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

Увімкніть це лише для plugins, яким ви довіряєте отримувати вміст і ідентифікатори вхідних повідомлень 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, як-от +15555550123.
• Групи зіставляються з JID груп WhatsApp, як-от 120363424282127706@g.us.
• Allowlist-и груп, політика відправників і перевірка згадки або активації виконуються до того, як OpenClaw забезпечує існування налаштованого сеансу ACP.
• Зіставлена налаштована прив’язка ACP володіє маршрутом. Групи трансляції WhatsApp не розгалужують цей turn до звичайних сеансів WhatsApp.

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

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

• пропускати сповіщення про прочитання для turn-ів чату із собою
• ігнорувати поведінку автоматичного запуску за mention-JID, яка інакше пінгувала б вас самих
• якщо 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,        },      },    },  },}

Доставка, chunking і медіа

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

WhatsApp підтримує native цитування відповідей, коли вихідні відповіді видимо цитують вхідне повідомлення. Керуйте цим через 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 підтримує негайні ack-реакції на отримання вхідних повідомлень через channels.whatsapp.ackReaction. Ack-реакції обмежуються reactionLevel — вони пригнічуються, коли 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 замінював реакцію підтвердження під час ходу, а не залишав статичний емодзі отримання. Коли це ввімкнено, OpenClaw використовує той самий слот реакції вхідного повідомлення для станів життєвого циклу, як-от у черзі, обдумування, активність інструментів, 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
• Записи конфігурації, ініційовані каналом, увімкнено типово (вимкнення через 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 визначено. Якщо systemPrompt є порожнім рядком (""), wildcard пригнічується й системний промпт не застосовується.
2. Wildcard-системний промпт групи (groups["*"].systemPrompt): використовується, коли конкретний запис групи повністю відсутній у мапі або коли він існує, але не визначає ключ systemPrompt.

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

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

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

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

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

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

Приклад:

{  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.            "120363406415684625@g.us": {              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

Пов’язане

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