diff --git a/docs/uk/channels/whatsapp.md b/docs/uk/channels/whatsapp.md index 51284f4be..9d9d232ba 100644 --- a/docs/uk/channels/whatsapp.md +++ b/docs/uk/channels/whatsapp.md @@ -1,26 +1,26 @@ --- read_when: - - Робота з поведінкою каналів WhatsApp/веб або маршрутизацією вхідних повідомлень -summary: Підтримка каналу WhatsApp, засоби контролю доступу, поведінка доставлення та операції + - Робота з поведінкою каналу WhatsApp/вебканалу або маршрутизацією вхідної скриньки +summary: Підтримка каналу WhatsApp, засоби контролю доступу, поведінка доставки та експлуатація title: WhatsApp x-i18n: - generated_at: "2026-05-02T21:58:35Z" + generated_at: "2026-05-03T05:39:59Z" model: gpt-5.5 provider: openai - source_hash: ffe2fce121dd1230fbcf20d55ec3855beb22c39f80b926eed41bf56183178ab2 + source_hash: 2f12709fc8ecb45e1b060647daf9a4624485d52b7b6436c3d07f171e6807babf source_path: channels/whatsapp.md workflow: 16 --- -Статус: готово до production через WhatsApp Web (Baileys). Gateway володіє пов’язаними сеансами. +Стан: готовий до production через WhatsApp Web (Baileys). Gateway володіє пов’язаними сеансами. -## Встановлення (за потреби) +## Встановлення (на вимогу) -- Онбординг (`openclaw onboard`) і `openclaw channels add --channel whatsapp` +- Onboarding (`openclaw onboard`) і `openclaw channels add --channel whatsapp` пропонують установити WhatsApp plugin під час першого вибору. - `openclaw channels login --channel whatsapp` також пропонує потік установлення, коли - plugin ще немає. -- Канал розробки + git checkout: за замовчуванням використовує локальний шлях plugin. + plugin ще відсутній. +- Dev-канал + git checkout: стандартно використовує локальний шлях plugin. - Stable/Beta: використовує npm-пакет `@openclaw/whatsapp` на поточному офіційному тезі релізу. @@ -30,18 +30,18 @@ x-i18n: openclaw plugins install @openclaw/whatsapp ``` -Використовуйте пакет без версії, щоб стежити за поточним офіційним тегом релізу. Закріплюйте точну +Використовуйте пакет без версії, щоб слідувати за поточним офіційним тегом релізу. Закріплюйте точну версію лише тоді, коли потрібне відтворюване встановлення. - Політика DM за замовчуванням для невідомих відправників — pairing. + Типова політика DM — pairing для невідомих відправників. - Міжканальна діагностика та інструкції з відновлення. + Діагностика між каналами та playbook-и відновлення. - Повні шаблони й приклади конфігурації каналів. + Повні шаблони та приклади конфігурації каналів. @@ -77,7 +77,7 @@ openclaw channels login --channel whatsapp openclaw channels login --channel whatsapp --account work ``` - Щоб підключити наявний або власний каталог автентифікації WhatsApp Web перед входом: + Щоб під’єднати наявний/власний каталог автентифікації WhatsApp Web перед входом: ```bash openclaw channels add --channel whatsapp --account work --auth-dir /path/to/wa-auth @@ -101,13 +101,13 @@ openclaw pairing list whatsapp openclaw pairing approve whatsapp ``` - Запити pairing спливають через 1 годину. Кількість очікуваних запитів обмежена 3 на канал. + Запити pairing спливають через 1 годину. Очікувані запити обмежені 3 на канал. -OpenClaw рекомендує за можливості запускати WhatsApp на окремому номері. (Метадані каналу й потік налаштування оптимізовані для такого сценарію, але сценарії з особистим номером також підтримуються.) +OpenClaw рекомендує за можливості запускати WhatsApp на окремому номері. (Метадані каналу та потік налаштування оптимізовані для такого налаштування, але налаштування з особистим номером також підтримуються.) ## Шаблони розгортання @@ -117,7 +117,7 @@ OpenClaw рекомендує за можливості запускати Whats Це найчистіший операційний режим: - окрема ідентичність WhatsApp для OpenClaw - - чіткіші allowlists DM і межі маршрутизації + - чіткіші allowlist-и DM і межі маршрутизації - менша ймовірність плутанини із self-chat Мінімальний шаблон політики: @@ -136,43 +136,44 @@ OpenClaw рекомендує за можливості запускати Whats - Онбординг підтримує режим особистого номера й записує базову конфігурацію, зручну для self-chat: + Onboarding підтримує режим особистого номера і записує базовий варіант, зручний для self-chat: - `dmPolicy: "allowlist"` - `allowFrom` містить ваш особистий номер - `selfChatMode: true` - Під час виконання захисти self-chat спираються на пов’язаний власний номер і `allowFrom`. + Під час runtime захисти self-chat спираються на пов’язаний власний номер і `allowFrom`. Канал платформи повідомлень у поточній архітектурі каналів OpenClaw базується на WhatsApp Web (`Baileys`). - У вбудованому реєстрі chat-channel немає окремого каналу обміну повідомленнями Twilio WhatsApp. + У вбудованому реєстрі чат-каналів немає окремого каналу обміну повідомленнями Twilio WhatsApp. -## Модель виконання +## Модель runtime - Gateway володіє сокетом WhatsApp і циклом повторного підключення. -- Watchdog повторного підключення використовує активність транспорту WhatsApp Web, а не лише обсяг вхідних app-message, тому тихий сеанс пов’язаного пристрою не перезапускається тільки через те, що останнім часом ніхто не надсилав повідомлень. Довше обмеження application-silence все ще примусово виконує повторне підключення, якщо транспортні кадри продовжують надходити, але протягом вікна watchdog не обробляються повідомлення застосунку; після тимчасового повторного підключення для нещодавно активного сеансу ця перевірка application-silence використовує звичайний тайм-аут повідомлень для першого вікна відновлення. -- Часові параметри сокета Baileys явно налаштовуються в `web.whatsapp.*`: `keepAliveIntervalMs` керує application pings WhatsApp Web, `connectTimeoutMs` керує тайм-аутом початкового handshake, а `defaultQueryTimeoutMs` керує тайм-аутами запитів Baileys. +- Watchdog повторного підключення використовує активність транспорту WhatsApp Web, а не лише обсяг вхідних app-message, тому тихий сеанс пов’язаного пристрою не перезапускається тільки через те, що останнім часом ніхто не надсилав повідомлень. Довший ліміт тиші застосунку все ще примусово запускає повторне підключення, якщо транспортні кадри продовжують надходити, але протягом вікна watchdog не обробляються повідомлення застосунку; після тимчасового повторного підключення для нещодавно активного сеансу ця перевірка тиші застосунку використовує звичайний таймаут повідомлень для першого вікна відновлення. +- Таймінги сокета Baileys явно задані в `web.whatsapp.*`: `keepAliveIntervalMs` керує application ping-ами WhatsApp Web, `connectTimeoutMs` керує таймаутом початкового handshake, а `defaultQueryTimeoutMs` керує таймаутами запитів Baileys. - Вихідні надсилання потребують активного слухача WhatsApp для цільового облікового запису. -- Чати статусів і трансляцій ігноруються (`@status`, `@broadcast`). -- Watchdog повторного підключення відстежує активність транспорту WhatsApp Web, а не лише обсяг вхідних app-message: тихі сеанси пов’язаних пристроїв залишаються активними, доки тривають транспортні кадри, але зупинка транспорту примушує повторне підключення значно раніше за пізніший шлях віддаленого відключення. -- Прямі чати використовують правила сеансів DM (`session.dmScope`; стандартне `main` згортає DM до головного сеансу агента). +- Групові надсилання додають нативні метадані згадок для токенів `@+` і `@` у тексті та підписах медіа, коли токен відповідає поточним метаданим учасника WhatsApp, включно з групами на базі LID. +- Чати статусів і розсилок ігноруються (`@status`, `@broadcast`). +- Watchdog повторного підключення стежить за активністю транспорту WhatsApp Web, а не лише за обсягом вхідних app-message: тихі сеанси пов’язаного пристрою залишаються активними, доки транспортні кадри продовжують надходити, але зупинка транспорту примусово запускає повторне підключення задовго до пізнішого шляху віддаленого від’єднання. +- Прямі чати використовують правила сеансу DM (`session.dmScope`; стандартне `main` згортає DM до головного сеансу агента). - Групові сеанси ізольовані (`agent::whatsapp:group:`). -- WhatsApp Channels/Newsletters можуть бути явними вихідними цілями зі своїм нативним JID `@newsletter`. Вихідні надсилання newsletter використовують метадані сеансу каналу (`agent::whatsapp:channel:`), а не семантику сеансів DM. -- Транспорт WhatsApp Web поважає стандартні змінні середовища proxy на хості gateway (`HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY` / варіанти в нижньому регістрі). Надавайте перевагу proxy-конфігурації на рівні хоста, а не специфічним для каналу налаштуванням proxy WhatsApp. -- Коли `messages.removeAckAfterReply` увімкнено, OpenClaw очищає реакцію ack у WhatsApp після доставки видимої відповіді. +- WhatsApp Channels/Newsletters можуть бути явними вихідними цілями зі своїм нативним JID `@newsletter`. Вихідні надсилання newsletter використовують метадані сеансу каналу (`agent::whatsapp:channel:`), а не семантику сеансу DM. +- Транспорт WhatsApp Web поважає стандартні змінні середовища проксі на хості Gateway (`HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY` / варіанти в нижньому регістрі). Надавайте перевагу проксі-конфігурації на рівні хоста, а не специфічним для каналу налаштуванням проксі WhatsApp. +- Коли `messages.removeAckAfterReply` увімкнено, OpenClaw очищає реакцію ack WhatsApp після доставлення видимої відповіді. -## Plugin hooks і приватність +## Хуки Plugin і приватність -Вхідні повідомлення WhatsApp можуть містити особистий вміст повідомлень, номери телефонів, -ідентифікатори груп, імена відправників і поля кореляції сеансів. З цієї причини -WhatsApp не транслює вхідні payload hook `message_received` до plugins, +Вхідні повідомлення WhatsApp можуть містити особистий вміст повідомлень, телефонні номери, +ідентифікатори груп, імена відправників і поля кореляції сеансу. Через це +WhatsApp не транслює вхідні payload-и hook `message_received` до plugins, якщо ви явно не погодитеся: ```json5 @@ -187,7 +188,7 @@ WhatsApp не транслює вхідні payload hook `message_received` до } ``` -Можна обмежити opt-in одним обліковим записом: +Можна обмежити згоду одним обліковим записом: ```json5 { @@ -205,8 +206,8 @@ WhatsApp не транслює вхідні payload hook `message_received` до } ``` -Увімкніть це лише для plugins, яким ви довіряєте отримувати вміст і ідентифікатори -вхідних повідомлень WhatsApp. +Умикайте це лише для plugins, яким ви довіряєте отримувати вміст і +ідентифікатори вхідних повідомлень WhatsApp. ## Контроль доступу й активація @@ -214,85 +215,85 @@ WhatsApp не транслює вхідні payload hook `message_received` до `channels.whatsapp.dmPolicy` керує доступом до прямих чатів: - - `pairing` (за замовчуванням) + - `pairing` (типово) - `allowlist` - `open` (потребує, щоб `allowFrom` містив `"*"`) - `disabled` `allowFrom` приймає номери у стилі E.164 (нормалізуються внутрішньо). - `allowFrom` — це список контролю доступу відправників DM. Він не обмежує явні вихідні надсилання до JID груп WhatsApp або JID каналів `@newsletter`. + `allowFrom` — це список контролю доступу відправників DM. Він не блокує явні вихідні надсилання до JID груп WhatsApp або JID каналів `@newsletter`. - Перевизначення для кількох облікових записів: `channels.whatsapp.accounts..dmPolicy` (і `allowFrom`) мають пріоритет над стандартними значеннями рівня каналу для цього облікового запису. + Перевизначення для кількох облікових записів: `channels.whatsapp.accounts..dmPolicy` (і `allowFrom`) мають пріоритет над типовими значеннями рівня каналу для цього облікового запису. - Деталі поведінки під час виконання: + Деталі поведінки runtime: - - pairings зберігаються в allow-store каналу й об’єднуються з налаштованим `allowFrom` - - запланована автоматизація та резервний вибір отримувачів Heartbeat використовують явні цілі доставки або налаштований `allowFrom`; схвалення DM pairing не є неявними отримувачами cron чи heartbeat - - якщо allowlist не налаштовано, пов’язаний власний номер дозволено за замовчуванням - - OpenClaw ніколи автоматично не pair вихідні DM `fromMe` (повідомлення, які ви надсилаєте собі з пов’язаного пристрою) + - pairings зберігаються в allow-store каналу та об’єднуються з налаштованим `allowFrom` + - запланована автоматизація та резервні отримувачі Heartbeat використовують явні цілі доставлення або налаштований `allowFrom`; схвалення DM pairing не є неявними отримувачами Cron чи Heartbeat + - якщо allowlist не налаштовано, пов’язаний власний номер дозволено типово + - OpenClaw ніколи автоматично не pairing-ить вихідні DM `fromMe` (повідомлення, які ви надсилаєте собі з пов’язаного пристрою) - Доступ до груп має два рівні: + Груповий доступ має два рівні: 1. **Allowlist членства в групах** (`channels.whatsapp.groups`) - якщо `groups` пропущено, усі групи придатні - якщо `groups` присутній, він діє як allowlist груп (`"*"` дозволено) - 2. **Політика відправників групи** (`channels.whatsapp.groupPolicy` + `groupAllowFrom`) + 2. **Політика відправника групи** (`channels.whatsapp.groupPolicy` + `groupAllowFrom`) - `open`: allowlist відправників обходиться - `allowlist`: відправник має відповідати `groupAllowFrom` (або `*`) - - `disabled`: блокувати всі вхідні групові повідомлення + - `disabled`: блокує всі групові вхідні повідомлення - Резервний варіант allowlist відправників: + Резервна логіка allowlist відправників: - якщо `groupAllowFrom` не задано, runtime повертається до `allowFrom`, коли він доступний - - allowlists відправників оцінюються до активації через mention/reply + - allowlist-и відправників оцінюються перед активацією згадкою/відповіддю - Примітка: якщо блоку `channels.whatsapp` взагалі немає, резервна групова політика runtime — `allowlist` (із warning log), навіть якщо задано `channels.defaults.groupPolicy`. + Примітка: якщо блок `channels.whatsapp` взагалі відсутній, runtime fallback групової політики — `allowlist` (із попереджувальним логом), навіть якщо `channels.defaults.groupPolicy` задано. - Групові відповіді за замовчуванням потребують mention. + Групові відповіді типово потребують згадки. - Виявлення mention включає: + Виявлення згадок включає: - - явні mentions WhatsApp ідентичності бота - - налаштовані шаблони regex для mention (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`) + - явні згадки WhatsApp ідентичності бота + - налаштовані regex-шаблони згадок (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`) - транскрипти вхідних voice-note для авторизованих групових повідомлень - - неявне виявлення reply-to-bot (відправник відповіді збігається з ідентичністю бота) + - неявне виявлення reply-to-bot (відправник відповіді відповідає ідентичності бота) Примітка щодо безпеки: - - quote/reply лише задовольняє mention gating; він **не** надає авторизацію відправника - - з `groupPolicy: "allowlist"` відправники не з allowlist усе одно блокуються, навіть якщо відповідають на повідомлення користувача з allowlist + - цитата/відповідь лише задовольняє mention gating; вона **не** надає авторизацію відправнику + - з `groupPolicy: "allowlist"` відправники поза allowlist усе одно блокуються, навіть якщо відповідають на повідомлення користувача з allowlist Команда активації на рівні сеансу: - `/activation mention` - `/activation always` - `activation` оновлює стан сеансу (не глобальну конфігурацію). Доступ обмежено власником. + `activation` оновлює стан сеансу (не глобальну конфігурацію). Вона owner-gated. ## Поведінка особистого номера та self-chat -Коли пов’язаний власний номер також присутній у `allowFrom`, активуються запобіжники WhatsApp self-chat: +Коли пов’язаний власний номер також присутній в `allowFrom`, активуються запобіжники WhatsApp self-chat: - пропускати read receipts для ходів self-chat -- ігнорувати поведінку автоматичного запуску mention-JID, яка інакше ping себе -- якщо `messages.responsePrefix` не задано, відповіді self-chat за замовчуванням мають формат `[{identity.name}]` або `[openclaw]` +- ігнорувати поведінку auto-trigger за mention-JID, яка інакше ping-ила б вас +- якщо `messages.responsePrefix` не задано, відповіді self-chat типово мають префікс `[{identity.name}]` або `[openclaw]` ## Нормалізація повідомлень і контекст - Вхідні повідомлення WhatsApp загортаються в спільний вхідний envelope. + Вхідні повідомлення WhatsApp загортаються у спільний вхідний envelope. Якщо існує цитована відповідь, контекст додається в такій формі: @@ -303,15 +304,15 @@ WhatsApp не транслює вхідні payload hook `message_received` до ``` Поля метаданих відповіді також заповнюються, коли доступні (`ReplyToId`, `ReplyToBody`, `ReplyToSender`, JID/E.164 відправника). - Коли ціль цитованої відповіді — медіа, яке можна завантажити, OpenClaw зберігає його через - звичайне сховище вхідних медіа й надає його як `MediaPath`/`MediaType`, щоб - агент міг переглянути згадане зображення, а не бачити лише + Коли ціль цитованої відповіді є медіа, яке можна завантажити, OpenClaw зберігає його через + звичайне сховище вхідних медіа й показує як `MediaPath`/`MediaType`, щоб + агент міг оглянути згадане зображення, а не бачити лише ``. - Вхідні повідомлення лише з медіа нормалізуються з placeholders, як-от: + Вхідні повідомлення лише з медіа нормалізуються з placeholder-ами, такими як: - `` - `` @@ -319,24 +320,24 @@ WhatsApp не транслює вхідні payload hook `message_received` до - `` - `` - Авторизовані групові voice notes транскрибуються до mention gating, коли - тіло містить лише ``, тож вимова mention бота у voice note може + Авторизовані групові voice notes транскрибуються перед mention gating, коли + тіло містить лише ``, тож вимовлена згадка бота у voice note може запустити відповідь. Якщо транскрипт усе ще не згадує бота, його - зберігають в історії очікуваних групових повідомлень замість сирого placeholder. + зберігають в очікуваній груповій історії замість сирого placeholder-а. - Тіла location використовують стислий текст координат. Мітки/коментарі location і деталі contact/vCard відображаються як fenced untrusted metadata, а не inline prompt text. + Тіла локацій використовують стислий текст координат. Мітки/коментарі локацій і дані contact/vCard рендеряться як fenced недовірені метадані, а не inline-текст prompt. - Для груп необроблені повідомлення можуть буферизуватися й вставлятися як контекст, коли бот нарешті запускається. + Для груп необроблені повідомлення можуть буферизуватися й додаватися як контекст, коли бота нарешті активовано. - - стандартний ліміт: `50` + - типовий ліміт: `50` - конфігурація: `channels.whatsapp.historyLimit` - fallback: `messages.groupChat.historyLimit` - `0` вимикає - Маркери вставлення: + Маркери ін’єкції: - `[Chat messages since your last reply - for context]` - `[Current message - respond to this]` @@ -344,7 +345,7 @@ WhatsApp не транслює вхідні payload hook `message_received` до - Read receipts увімкнені за замовчуванням для прийнятих вхідних повідомлень WhatsApp. + Read receipts типово ввімкнені для прийнятих вхідних повідомлень WhatsApp. Вимкнути глобально: @@ -358,7 +359,7 @@ WhatsApp не транслює вхідні payload hook `message_received` до } ``` - Перевизначення для окремого облікового запису: + Перевизначення для облікового запису: ```json5 { @@ -374,7 +375,7 @@ WhatsApp не транслює вхідні payload hook `message_received` до } ``` - Ходи в чаті із самим собою не надсилають сповіщення про прочитання, навіть коли їх увімкнено глобально. + Ходи в чаті із самим собою пропускають сповіщення про прочитання, навіть коли вони ввімкнені глобально. @@ -383,47 +384,47 @@ WhatsApp не транслює вхідні payload hook `message_received` до - - стандартне обмеження фрагмента: `channels.whatsapp.textChunkLimit = 4000` + - типовий ліміт фрагмента: `channels.whatsapp.textChunkLimit = 4000` - `channels.whatsapp.chunkMode = "length" | "newline"` - - режим `newline` надає перевагу межам абзаців (порожнім рядкам), а потім повертається до безпечного за довжиною розбиття на фрагменти + - режим `newline` віддає перевагу межам абзаців (порожнім рядкам), а потім переходить до безпечного за довжиною розбиття на фрагменти - - підтримує зображення, відео, аудіо (голосову нотатку PTT) і документні payload-и - - аудіомедіа надсилається через payload `audio` Baileys із `ptt: true`, тому клієнти WhatsApp відображають його як голосову нотатку push-to-talk - - payload-и відповідей зберігають `audioAsVoice`; вивід голосових нотаток TTS для WhatsApp залишається на цьому шляху PTT, навіть коли провайдер повертає MP3 або WebM + - підтримує зображення, відео, аудіо (голосову нотатку PTT) і документні payloads + - аудіомедіа надсилаються через payload Baileys `audio` з `ptt: true`, тому клієнти WhatsApp відображають їх як голосову нотатку push-to-talk + - payloads відповідей зберігають `audioAsVoice`; вивід голосової нотатки TTS для WhatsApp залишається на цьому шляху PTT, навіть коли провайдер повертає MP3 або WebM - нативне аудіо Ogg/Opus надсилається як `audio/ogg; codecs=opus` для сумісності з голосовими нотатками - - аудіо не у форматі Ogg, зокрема вивід Microsoft Edge TTS MP3/WebM, перекодовується за допомогою `ffmpeg` у моно Ogg/Opus 48 кГц перед доставкою PTT - - `/tts latest` надсилає останню відповідь асистента як одну голосову нотатку й пригнічує повторні надсилання для тієї самої відповіді; `/tts chat on|off|default` керує автоматичним TTS для поточного чату WhatsApp + - аудіо не у форматі Ogg, зокрема вивід Microsoft Edge TTS MP3/WebM, транскодується за допомогою `ffmpeg` у моно Ogg/Opus 48 кГц перед доставкою PTT + - `/tts latest` надсилає останню відповідь асистента як одну голосову нотатку та приглушує повторні надсилання тієї самої відповіді; `/tts chat on|off|default` керує автоматичним TTS для поточного чату WhatsApp - відтворення анімованих GIF підтримується через `gifPlayback: true` під час надсилання відео - - підписи застосовуються до першого медіаелемента під час надсилання payload-ів відповідей із кількома медіа, крім голосових нотаток PTT: вони спочатку надсилають аудіо, а видимий текст окремо, бо клієнти WhatsApp не завжди стабільно відображають підписи до голосових нотаток + - підписи застосовуються до першого медіаелемента під час надсилання payloads відповідей із кількома медіа, окрім голосових нотаток PTT: вони надсилають аудіо першим, а видимий текст окремо, оскільки клієнти WhatsApp не відображають підписи до голосових нотаток послідовно - джерелом медіа може бути HTTP(S), `file://` або локальні шляхи - - обмеження збереження вхідних медіа: `channels.whatsapp.mediaMaxMb` (стандартно `50`) - - обмеження надсилання вихідних медіа: `channels.whatsapp.mediaMaxMb` (стандартно `50`) - - перевизначення для окремих облікових записів використовують `channels.whatsapp.accounts..mediaMaxMb` - - зображення автоматично оптимізуються (зміна розміру/підбір якості), щоб вкластися в обмеження - - у разі помилки надсилання медіа резервна поведінка для першого елемента надсилає текстове попередження замість тихого відкидання відповіді + - ліміт збереження вхідних медіа: `channels.whatsapp.mediaMaxMb` (типово `50`) + - ліміт надсилання вихідних медіа: `channels.whatsapp.mediaMaxMb` (типово `50`) + - перевизначення для облікового запису використовують `channels.whatsapp.accounts..mediaMaxMb` + - зображення автоматично оптимізуються (зміна розміру/перебір якості), щоб відповідати лімітам + - у разі помилки надсилання медіа резервний варіант для першого елемента надсилає текстове попередження замість тихого відкидання відповіді -## Цитування відповідей +## Цитування відповіді WhatsApp підтримує нативне цитування відповідей, коли вихідні відповіді видимо цитують вхідне повідомлення. Керуйте цим за допомогою `channels.whatsapp.replyToMode`. -| Значення | Поведінка | -| ----------- | ----------------------------------------------------------------------- | -| `"off"` | Ніколи не цитувати; надсилати як звичайне повідомлення | -| `"first"` | Цитувати лише перший фрагмент вихідної відповіді | -| `"all"` | Цитувати кожен фрагмент вихідної відповіді | +| Значення | Поведінка | +| ----------- | --------------------------------------------------------------------- | +| `"off"` | Ніколи не цитувати; надсилати як звичайне повідомлення | +| `"first"` | Цитувати лише перший фрагмент вихідної відповіді | +| `"all"` | Цитувати кожен фрагмент вихідної відповіді | | `"batched"` | Цитувати поставлені в чергу пакетні відповіді, залишаючи негайні відповіді без цитування | -Стандартно: `"off"`. Перевизначення для окремих облікових записів використовують `channels.whatsapp.accounts..replyToMode`. +Типово: `"off"`. Перевизначення для облікового запису використовують `channels.whatsapp.accounts..replyToMode`. ```json5 { @@ -437,18 +438,18 @@ WhatsApp підтримує нативне цитування відповіде ## Рівень реакцій -`channels.whatsapp.reactionLevel` керує тим, наскільки широко агент використовує emoji-реакції у WhatsApp: +`channels.whatsapp.reactionLevel` керує тим, наскільки широко агент використовує емодзі-реакції у WhatsApp: -| Рівень | Ack-реакції | Реакції, ініційовані агентом | Опис | -| ------------- | ----------- | ---------------------------- | ---------------------------------------------- | -| `"off"` | Ні | Ні | Жодних реакцій | -| `"ack"` | Так | Ні | Лише Ack-реакції (сповіщення перед відповіддю) | -| `"minimal"` | Так | Так (обережно) | Ack + реакції агента з обережними настановами | -| `"extensive"` | Так | Так (заохочується) | Ack + реакції агента із заохочувальними настановами | +| Рівень | Реакції підтвердження | Реакції, ініційовані агентом | Опис | +| ------------- | --------------------- | ---------------------------- | ------------------------------------------------ | +| `"off"` | Ні | Ні | Жодних реакцій | +| `"ack"` | Так | Ні | Лише реакції підтвердження (отримання перед відповіддю) | +| `"minimal"` | Так | Так (обережно) | Підтвердження + реакції агента з обережними вказівками | +| `"extensive"` | Так | Так (заохочується) | Підтвердження + реакції агента із заохочувальними вказівками | -Стандартно: `"minimal"`. +Типово: `"minimal"`. -Перевизначення для окремих облікових записів використовують `channels.whatsapp.accounts..reactionLevel`. +Перевизначення для облікового запису використовують `channels.whatsapp.accounts..reactionLevel`. ```json5 { @@ -462,8 +463,8 @@ WhatsApp підтримує нативне цитування відповіде ## Реакції підтвердження -WhatsApp підтримує негайні Ack-реакції після отримання вхідного повідомлення через `channels.whatsapp.ackReaction`. -Ack-реакції обмежуються `reactionLevel` — вони пригнічуються, коли `reactionLevel` має значення `"off"`. +WhatsApp підтримує негайні реакції підтвердження на отримання вхідного повідомлення через `channels.whatsapp.ackReaction`. +Реакції підтвердження обмежуються `reactionLevel` — вони приглушуються, коли `reactionLevel` дорівнює `"off"`. ```json5 { @@ -481,34 +482,34 @@ Ack-реакції обмежуються `reactionLevel` — вони приг Примітки щодо поведінки: -- надсилається негайно після прийняття вхідного повідомлення (до відповіді) +- надсилається негайно після прийняття вхідного повідомлення (перед відповіддю) - помилки записуються в журнал, але не блокують нормальну доставку відповіді -- режим групи `mentions` реагує на ходи, запущені згадкою; активація групи `always` працює як обхід цієї перевірки -- WhatsApp використовує `channels.whatsapp.ackReaction` (застаріле `messages.ackReaction` тут не використовується) +- груповий режим `mentions` реагує на ходи, запущені згадкою; групова активація `always` діє як обхід цієї перевірки +- WhatsApp використовує `channels.whatsapp.ackReaction` (застарілий `messages.ackReaction` тут не використовується) ## Кілька облікових записів і облікові дані - - - ідентифікатори облікових записів беруться з `channels.whatsapp.accounts` - - стандартний вибір облікового запису: `default`, якщо він наявний, інакше перший налаштований ідентифікатор облікового запису (відсортовано) + + - ідентифікатори облікових записів надходять із `channels.whatsapp.accounts` + - типовий вибір облікового запису: `default`, якщо він наявний, інакше перший налаштований ідентифікатор облікового запису (відсортований) - ідентифікатори облікових записів внутрішньо нормалізуються для пошуку - - - поточний шлях авторизації: `~/.openclaw/credentials/whatsapp//creds.json` + + - поточний шлях автентифікації: `~/.openclaw/credentials/whatsapp//creds.json` - файл резервної копії: `creds.json.bak` - - застаріла стандартна авторизація в `~/.openclaw/credentials/` досі розпізнається/мігрується для потоків стандартного облікового запису + - застаріла типова автентифікація в `~/.openclaw/credentials/` усе ще розпізнається/мігрується для потоків типового облікового запису - - `openclaw channels logout --channel whatsapp [--account ]` очищає стан авторизації WhatsApp для цього облікового запису. + + `openclaw channels logout --channel whatsapp [--account ]` очищує стан автентифікації WhatsApp для цього облікового запису. - Коли Gateway доступний, вихід спочатку зупиняє активний слухач WhatsApp для вибраного облікового запису, щоб пов’язаний сеанс не продовжував отримувати повідомлення до наступного перезапуску. `openclaw channels remove --channel whatsapp` також зупиняє активний слухач перед вимкненням або видаленням конфігурації облікового запису. + Коли Gateway доступний, вихід спершу зупиняє активний слухач WhatsApp для вибраного облікового запису, щоб пов’язана сесія не продовжувала отримувати повідомлення до наступного перезапуску. `openclaw channels remove --channel whatsapp` також зупиняє активний слухач перед вимкненням або видаленням конфігурації облікового запису. - У застарілих каталогах авторизації `oauth.json` зберігається, а файли авторизації Baileys видаляються. + У застарілих каталогах автентифікації `oauth.json` зберігається, а файли автентифікації Baileys видаляються. @@ -516,16 +517,16 @@ Ack-реакції обмежуються `reactionLevel` — вони приг ## Інструменти, дії та записи конфігурації - Підтримка інструментів агента включає дію реакції WhatsApp (`react`). -- Обмеження дій: +- Обмежувачі дій: - `channels.whatsapp.actions.reactions` - `channels.whatsapp.actions.polls` -- Записи конфігурації, ініційовані каналом, увімкнено стандартно (вимикайте через `channels.whatsapp.configWrites=false`). +- Записи конфігурації, ініційовані каналом, увімкнені типово (вимкнути через `channels.whatsapp.configWrites=false`). ## Усунення несправностей - Симптом: стан каналу повідомляє, що його не пов’язано. + Симптом: статус каналу повідомляє, що він не пов’язаний. Виправлення: @@ -539,14 +540,14 @@ Ack-реакції обмежуються `reactionLevel` — вони приг Симптом: пов’язаний обліковий запис із повторними від’єднаннями або спробами повторного підключення. - Тихі облікові записи можуть залишатися підключеними після звичайного тайм-ауту повідомлення; watchdog - перезапускається, коли зупиняється активність транспорту WhatsApp Web, socket закривається або - активність рівня застосунку лишається тихою понад довше безпечне вікно. + Тихі облікові записи можуть залишатися підключеними після звичайного тайм-ауту повідомлення; сторожовий механізм + перезапускається, коли транспортна активність WhatsApp Web припиняється, сокет закривається або + активність на рівні застосунку залишається беззвучною довше за довше захисне вікно. Якщо журнали показують повторюване `status=408 Request Time-out Connection was lost`, налаштуйте - таймінги socket Baileys у `web.whatsapp`. Почніть зі скорочення + таймінги сокета Baileys у `web.whatsapp`. Почніть зі скорочення `keepAliveIntervalMs` нижче тайм-ауту простою вашої мережі та збільшення - `connectTimeoutMs` на повільних або нестабільних з’єднаннях: + `connectTimeoutMs` для повільних або нестабільних з’єднань: ```json5 { @@ -572,33 +573,33 @@ Ack-реакції обмежуються `reactionLevel` — вони приг Gateway і WhatsApp справні, запустіть `openclaw doctor`. У Linux doctor попереджає про застарілі записи crontab, які досі викликають `~/.openclaw/bin/ensure-whatsapp.sh`; видаліть ці застарілі записи за допомогою - `crontab -e`, бо cron може не мати середовища користувацької шини systemd і - змушувати старий скрипт неправильно повідомляти стан Gateway. + `crontab -e`, оскільки cron може не мати середовища user-bus systemd і + змусити старий скрипт неправильно повідомляти про справність Gateway. За потреби повторно пов’яжіть через `channels login`. - Симптом: `openclaw channels login --channel whatsapp` завершується помилкою до показу придатного QR-коду з `status=408 Request Time-out` або від’єднанням TLS socket. + Симптом: `openclaw channels login --channel whatsapp` завершується помилкою до показу придатного QR-коду з `status=408 Request Time-out` або від’єднанням TLS-сокета. - Вхід у WhatsApp Web використовує стандартне проксі-середовище хоста Gateway (`HTTPS_PROXY`, `HTTP_PROXY`, варіанти в нижньому регістрі та `NO_PROXY`). Перевірте, що процес Gateway успадковує proxy env і що `NO_PROXY` не збігається з `mmg.whatsapp.net`. + Вхід у WhatsApp Web використовує стандартне проксі-середовище хоста Gateway (`HTTPS_PROXY`, `HTTP_PROXY`, варіанти в нижньому регістрі та `NO_PROXY`). Перевірте, що процес Gateway успадковує змінні середовища проксі та що `NO_PROXY` не збігається з `mmg.whatsapp.net`. - Вихідні надсилання швидко завершуються помилкою, коли для цільового облікового запису не існує активного слухача gateway. + Вихідні надсилання швидко завершуються помилкою, коли для цільового облікового запису немає активного слухача Gateway. - Переконайтеся, що gateway запущено й обліковий запис пов’язано. + Переконайтеся, що Gateway запущений і обліковий запис пов’язаний. - - Рядки transcript записують те, що згенерував агент. Доставка WhatsApp перевіряється окремо: OpenClaw вважає автоматичну відповідь надісланою лише після того, як Baileys поверне ідентифікатор вихідного повідомлення для принаймні одного видимого текстового або медіанадсилання. + + Рядки transcript записують те, що згенерував агент. Доставка WhatsApp перевіряється окремо: OpenClaw вважає автоматичну відповідь надісланою лише після того, як Baileys повертає ідентифікатор вихідного повідомлення хоча б для одного видимого текстового або медіанадсилання. - Ack-реакції є незалежними сповіщеннями перед відповіддю. Успішна реакція не доводить, що пізнішу текстову або медіавідповідь прийняв WhatsApp. + Реакції підтвердження є незалежними отриманнями перед відповіддю. Успішна реакція не доводить, що пізнішу текстову або медіавідповідь прийняв WhatsApp. - Перевірте журнали gateway на `auto-reply delivery failed` або `auto-reply was not accepted by WhatsApp provider`. + Перевірте журнали Gateway на `auto-reply delivery failed` або `auto-reply was not accepted by WhatsApp provider`. @@ -608,13 +609,13 @@ Ack-реакції обмежуються `reactionLevel` — вони приг - `groupPolicy` - `groupAllowFrom` / `allowFrom` - записи allowlist у `groups` - - обмеження за згадками (`requireMention` + шаблони згадок) - - дублікати ключів в `openclaw.json` (JSON5): пізніші записи перевизначають попередні, тому тримайте один `groupPolicy` на область + - обмеження згадками (`requireMention` + шаблони згадок) + - дублікати ключів у `openclaw.json` (JSON5): пізніші записи перевизначають попередні, тому тримайте один `groupPolicy` для кожної області - - Runtime gateway WhatsApp має використовувати Node. Bun позначено як несумісний для стабільної роботи gateway WhatsApp/Telegram. + + Середовище виконання Gateway для WhatsApp має використовувати Node. Bun позначено як несумісний для стабільної роботи Gateway WhatsApp/Telegram. @@ -624,30 +625,30 @@ WhatsApp підтримує системні prompts у стилі Telegram дл Ієрархія розв’язання для групових повідомлень: -Ефективна мапа `groups` визначається першою: якщо обліковий запис визначає власні `groups`, вона повністю замінює кореневу мапу `groups` (без глибокого злиття). Потім пошук prompt виконується на отриманій єдиній мапі: +Ефективна мапа `groups` визначається першою: якщо обліковий запис визначає власну `groups`, вона повністю замінює кореневу мапу `groups` (без глибокого злиття). Потім пошук prompt виконується на отриманій єдиній мапі: -1. **Груповий системний prompt** (`groups[""].systemPrompt`): використовується, коли конкретний запис групи існує в мапі **і** його ключ `systemPrompt` визначено. Якщо `systemPrompt` є порожнім рядком (`""`), wildcard пригнічується й системний prompt не застосовується. -2. **Груповий wildcard-системний prompt** (`groups["*"].systemPrompt`): використовується, коли конкретний запис групи повністю відсутній у мапі або коли він існує, але не визначає ключ `systemPrompt`. +1. **Системний prompt для конкретної групи** (`groups[""].systemPrompt`): використовується, коли конкретний запис групи існує в мапі **і** його ключ `systemPrompt` визначений. Якщо `systemPrompt` є порожнім рядком (`""`), wildcard приглушується і системний prompt не застосовується. +2. **Системний prompt wildcard для групи** (`groups["*"].systemPrompt`): використовується, коли конкретний запис групи повністю відсутній у мапі або коли він існує, але не визначає ключ `systemPrompt`. Ієрархія розв’язання для прямих повідомлень: -Ефективна мапа `direct` визначається першою: якщо обліковий запис визначає власні `direct`, вона повністю замінює кореневу мапу `direct` (без глибокого злиття). Потім пошук prompt виконується на отриманій єдиній мапі: +Ефективна мапа `direct` визначається першою: якщо обліковий запис визначає власну `direct`, вона повністю замінює кореневу мапу `direct` (без глибокого злиття). Потім пошук prompt виконується на отриманій єдиній мапі: -1. **Прямий системний prompt** (`direct[""].systemPrompt`): використовується, коли конкретний запис peer існує в мапі **і** його ключ `systemPrompt` визначено. Якщо `systemPrompt` є порожнім рядком (`""`), wildcard пригнічується й системний prompt не застосовується. -2. **Прямий wildcard-системний prompt** (`direct["*"].systemPrompt`): використовується, коли конкретний запис peer повністю відсутній у мапі або коли він існує, але не визначає ключ `systemPrompt`. +1. **Системний prompt для конкретного direct** (`direct[""].systemPrompt`): використовується, коли конкретний запис співрозмовника існує в мапі **і** його ключ `systemPrompt` визначений. Якщо `systemPrompt` є порожнім рядком (`""`), wildcard приглушується і системний prompt не застосовується. +2. **Системний prompt wildcard для direct** (`direct["*"].systemPrompt`): використовується, коли конкретний запис співрозмовника повністю відсутній у мапі або коли він існує, але не визначає ключ `systemPrompt`. -`dms` залишається легким контейнером перевизначень історії для окремих DM (`dms..historyLimit`). Перевизначення prompt живуть у `direct`. +`dms` залишається легким контейнером перевизначень історії для окремих DM (`dms..historyLimit`). Перевизначення prompt розміщуються в `direct`. -**Відмінність від поведінки кількох акаунтів у Telegram:** У Telegram кореневий `groups` навмисно пригнічується для всіх акаунтів у налаштуванні з кількома акаунтами — навіть для акаунтів, які не визначають власних `groups`, — щоб бот не отримував групові повідомлення з груп, до яких він не належить. WhatsApp не застосовує цей запобіжник: кореневі `groups` і кореневий `direct` завжди успадковуються акаунтами, які не визначають перевизначення на рівні акаунта, незалежно від того, скільки акаунтів налаштовано. У налаштуванні WhatsApp із кількома акаунтами, якщо вам потрібні групові або прямі промпти для кожного акаунта окремо, явно визначте повну мапу під кожним акаунтом, а не покладайтеся на кореневі значення за замовчуванням. +**Відмінність від поведінки мультиакаунтів Telegram:** У Telegram кореневий `groups` навмисно пригнічується для всіх акаунтів у налаштуванні з кількома акаунтами — навіть для акаунтів, які не визначають власних `groups`, — щоб бот не отримував групові повідомлення з груп, до яких він не належить. WhatsApp не застосовує цей захист: кореневі `groups` і кореневий `direct` завжди успадковуються акаунтами, які не визначають перевизначення на рівні акаунта, незалежно від кількості налаштованих акаунтів. У налаштуванні WhatsApp із кількома акаунтами, якщо вам потрібні окремі групові або прямі промпти для кожного акаунта, явно визначте повну мапу для кожного акаунта замість того, щоб покладатися на стандартні значення кореневого рівня. Важлива поведінка: -- `channels.whatsapp.groups` є одночасно мапою конфігурації для кожної групи та списком дозволених груп на рівні чату. На кореневому рівні або в межах акаунта `groups["*"]` означає «усі групи допускаються» для цієї області. -- Додавайте wildcard-групу `systemPrompt` лише тоді, коли ви вже хочете, щоб ця область допускала всі групи. Якщо ви все ще хочете, щоб придатним був лише фіксований набір ID груп, не використовуйте `groups["*"]` для промпта за замовчуванням. Натомість повторіть промпт у кожному явно дозволеному записі групи. -- Допуск групи й авторизація відправника є окремими перевірками. `groups["*"]` розширює набір груп, які можуть потрапити в обробку груп, але сам по собі він не авторизує кожного відправника в цих групах. Доступ відправників усе ще окремо контролюється `channels.whatsapp.groupPolicy` і `channels.whatsapp.groupAllowFrom`. -- `channels.whatsapp.direct` не має такого самого побічного ефекту для особистих повідомлень. `direct["*"]` лише надає конфігурацію за замовчуванням для прямого чату після того, як особисте повідомлення вже допущено через `dmPolicy` разом із `allowFrom` або правилами сховища сполучень. +- `channels.whatsapp.groups` є і мапою конфігурації для окремих груп, і allowlist груп на рівні чату. На кореневому рівні або в межах акаунта `groups["*"]` означає «допущено всі групи» для цієї області. +- Додавайте wildcard-групу `systemPrompt` лише тоді, коли ви вже хочете, щоб ця область допускала всі групи. Якщо ви все ще хочете, щоб придатним був лише фіксований набір ID груп, не використовуйте `groups["*"]` для стандартного промпта. Натомість повторіть промпт у кожному явно дозволеному записі групи. +- Допуск групи та авторизація відправника є окремими перевірками. `groups["*"]` розширює набір груп, які можуть потрапити в обробку груп, але сам по собі не авторизує кожного відправника в цих групах. Доступ відправників і далі окремо контролюється через `channels.whatsapp.groupPolicy` і `channels.whatsapp.groupAllowFrom`. +- `channels.whatsapp.direct` не має такого самого побічного ефекту для DM. `direct["*"]` лише надає стандартну конфігурацію прямого чату після того, як DM уже допущено через `dmPolicy` разом з `allowFrom` або правилами pairing-store. Приклад: @@ -691,22 +692,22 @@ WhatsApp підтримує системні prompts у стилі Telegram дл ## Вказівники до довідника конфігурації -Основний довідник: +Основна довідка: - [Довідник конфігурації - WhatsApp](/uk/gateway/config-channels#whatsapp) -Найважливіші поля WhatsApp: +Ключові поля WhatsApp: - доступ: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups` - доставка: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `sendReadReceipts`, `ackReaction`, `reactionLevel` -- кілька акаунтів: `accounts..enabled`, `accounts..authDir`, перевизначення на рівні акаунта +- мультиакаунт: `accounts..enabled`, `accounts..authDir`, перевизначення на рівні акаунта - операції: `configWrites`, `debounceMs`, `web.enabled`, `web.heartbeatSeconds`, `web.reconnect.*`, `web.whatsapp.*` -- поведінка сесії: `session.dmScope`, `historyLimit`, `dmHistoryLimit`, `dms..historyLimit` +- поведінка сеансу: `session.dmScope`, `historyLimit`, `dmHistoryLimit`, `dms..historyLimit` - промпти: `groups..systemPrompt`, `groups["*"].systemPrompt`, `direct..systemPrompt`, `direct["*"].systemPrompt` ## Пов’язане -- [Сполучення](/uk/channels/pairing) +- [Pairing](/uk/channels/pairing) - [Групи](/uk/channels/groups) - [Безпека](/uk/gateway/security) - [Маршрутизація каналів](/uk/channels/channel-routing)