diff --git a/docs/uk/channels/bluebubbles.md b/docs/uk/channels/bluebubbles.md index 92c5fce71..cc47b06e8 100644 --- a/docs/uk/channels/bluebubbles.md +++ b/docs/uk/channels/bluebubbles.md @@ -1,48 +1,48 @@ --- read_when: - Налаштування каналу BlueBubbles - - Вирішення проблем зі сполученням Webhook + - Усунення несправностей сполучення Webhook - Налаштування iMessage на macOS sidebarTitle: BlueBubbles -summary: iMessage через сервер BlueBubbles для macOS (надсилання/отримання через REST, набір тексту, реакції, сполучення, розширені дії). +summary: iMessage через macOS-сервер BlueBubbles (надсилання/отримання через REST, набір тексту, реакції, сполучення, розширені дії). title: BlueBubbles x-i18n: - generated_at: "2026-04-28T11:04:09Z" + generated_at: "2026-05-01T05:05:03Z" model: gpt-5.5 provider: openai - source_hash: 7a77b248ed86eb4114f8b7f1fc6bd4cea004d65095a0439a4a8c814bc180082c + source_hash: 499cc2a46db6e0eddfb897e96ec4b3e4a39ba9f2f6da8e7485c1c46562de4145 source_path: channels/bluebubbles.md workflow: 16 --- -Стан: вбудований plugin, який взаємодіє з macOS-сервером BlueBubbles через HTTP. **Рекомендовано для інтеграції з iMessage** завдяки багатшому API та простішому налаштуванню порівняно із застарілим каналом imsg. +Статус: bundled plugin, який взаємодіє з macOS-сервером BlueBubbles через HTTP. **Рекомендовано для інтеграції з iMessage** завдяки багатшому API та простішому налаштуванню порівняно із застарілим каналом imsg. -Поточні випуски OpenClaw вбудовують BlueBubbles, тому звичайні пакетовані збірки не потребують окремого кроку `openclaw plugins install`. +Поточні випуски OpenClaw постачають BlueBubbles у комплекті, тому звичайні пакетовані збірки не потребують окремого кроку `openclaw plugins install`. ## Огляд - Працює на macOS через допоміжний застосунок BlueBubbles ([bluebubbles.app](https://bluebubbles.app)). -- Рекомендовано/перевірено: macOS Sequoia (15). macOS Tahoe (26) працює; редагування зараз зламане на Tahoe, а оновлення піктограм груп можуть повідомляти про успіх, але не синхронізуватися. -- OpenClaw взаємодіє з ним через його REST API (`GET /api/v1/ping`, `POST /message/text`, `POST /chat/:id/*`). -- Вхідні повідомлення надходять через вебхуки; вихідні відповіді, індикатори набору, сповіщення про прочитання та tapback-реакції виконуються REST-викликами. -- Вкладення та стікери приймаються як вхідні медіа (і, коли можливо, передаються агенту). -- Автоматичні TTS-відповіді, які синтезують MP3 або CAF-аудіо, доставляються як бульбашки голосових нотаток iMessage замість звичайних файлових вкладень. -- Сполучення/список дозволених працює так само, як в інших каналах (`/channels/pairing` тощо), з `channels.bluebubbles.allowFrom` + кодами сполучення. -- Реакції відображаються як системні події так само, як у Slack/Telegram, щоб агенти могли "згадувати" їх перед відповіддю. -- Розширені можливості: редагування, скасування надсилання, гілкування відповідей, ефекти повідомлень, керування групами. +- Рекомендовано/перевірено: macOS Sequoia (15). macOS Tahoe (26) працює; редагування наразі зламане на Tahoe, а оновлення іконок груп можуть повідомляти про успіх, але не синхронізуватися. +- OpenClaw взаємодіє з ним через REST API (`GET /api/v1/ping`, `POST /message/text`, `POST /chat/:id/*`). +- Вхідні повідомлення надходять через webhooks; вихідні відповіді, індикатори набору, сповіщення про прочитання та tapbacks виконуються REST-викликами. +- Вкладення та стікери приймаються як вхідні медіа (і, коли можливо, передаються agent). +- Автоматичні TTS-відповіді, що синтезують MP3 або CAF-аудіо, доставляються як бульбашки голосових нотаток iMessage замість звичайних файлових вкладень. +- Сполучення/allowlist працює так само, як і в інших каналах (`/channels/pairing` тощо), з `channels.bluebubbles.allowFrom` + кодами сполучення. +- Реакції передаються як системні події, так само як у Slack/Telegram, щоб agents могли "згадати" їх перед відповіддю. +- Розширені можливості: редагування, скасування надсилання, гілки відповідей, ефекти повідомлень, керування групами. ## Швидкий старт - - Установіть сервер BlueBubbles на свій Mac (дотримуйтесь інструкцій на [bluebubbles.app/install](https://bluebubbles.app/install)). + + Установіть сервер BlueBubbles на ваш Mac (дотримуйтесь інструкцій на [bluebubbles.app/install](https://bluebubbles.app/install)). - - У конфігурації BlueBubbles увімкніть web API і задайте пароль. + + У конфігурації BlueBubbles увімкніть web API та встановіть пароль. - + Запустіть `openclaw onboard` і виберіть BlueBubbles або налаштуйте вручну: ```json5 @@ -59,29 +59,29 @@ x-i18n: ``` - - Спрямуйте вебхуки BlueBubbles на свій Gateway (приклад: `https://your-gateway-host:3000/bluebubbles-webhook?password=`). + + Спрямуйте webhooks BlueBubbles на ваш gateway (приклад: `https://your-gateway-host:3000/bluebubbles-webhook?password=`). - - Запустіть Gateway; він зареєструє обробник вебхука й почне сполучення. + + Запустіть gateway; він зареєструє обробник webhook і почне сполучення. **Безпека** -- Завжди задавайте пароль вебхука. -- Автентифікація Webhook завжди обов'язкова. OpenClaw відхиляє запити Webhook BlueBubbles, якщо вони не містять password/guid, що збігається з `channels.bluebubbles.password` (наприклад `?password=` або `x-password`), незалежно від топології loopback/proxy. -- Автентифікація паролем перевіряється перед читанням/розбором повних тіл вебхуків. +- Завжди встановлюйте пароль webhook. +- Автентифікація webhook завжди обов’язкова. OpenClaw відхиляє webhook-запити BlueBubbles, якщо вони не містять пароль/guid, що відповідає `channels.bluebubbles.password` (наприклад, `?password=` або `x-password`), незалежно від топології loopback/proxy. +- Автентифікація паролем перевіряється перед читанням/розбором повних тіл webhook. ## Підтримання Messages.app активним (VM / headless-налаштування) -У деяких macOS VM / постійно ввімкнених налаштуваннях Messages.app може переходити в "idle" (вхідні події зупиняються, доки застосунок не відкриють або не виведуть на передній план). Простий обхідний шлях — **штовхати Messages кожні 5 хвилин** за допомогою AppleScript + LaunchAgent. +У деяких VM macOS / постійно ввімкнених налаштуваннях Messages.app може переходити в стан "idle" (вхідні події зупиняються, доки застосунок не відкриють або не виведуть на передній план). Простий обхідний шлях — **підштовхувати Messages кожні 5 хвилин** за допомогою AppleScript + LaunchAgent. - + Збережіть це як `~/Scripts/poke-messages.scpt`: ```applescript @@ -100,7 +100,7 @@ x-i18n: ``` - + Збережіть це як `~/Library/LaunchAgents/com.user.poke-messages.plist`: ```xml @@ -132,10 +132,10 @@ x-i18n: ``` - Це запускається **кожні 300 секунд** і **під час входу в систему**. Перший запуск може викликати запити **Automation** у macOS (`osascript` → Messages). Підтвердьте їх у тому самому сеансі користувача, у якому працює LaunchAgent. + Це запускається **кожні 300 секунд** і **під час входу в систему**. Перший запуск може спричинити запити macOS **Automation** (`osascript` → Messages). Схваліть їх у тому самому сеансі користувача, у якому працює LaunchAgent. - + ```bash launchctl unload ~/Library/LaunchAgents/com.user.poke-messages.plist 2>/dev/null || true launchctl load ~/Library/LaunchAgents/com.user.poke-messages.plist @@ -160,13 +160,13 @@ openclaw onboard Пароль API з налаштувань BlueBubbles Server. - Шлях кінцевої точки Webhook. + Шлях кінцевої точки webhook. `pairing`, `allowlist`, `open` або `disabled`. - Номери телефонів, електронні адреси або цілі чатів. + Номери телефонів, електронні адреси або цілі чату. Ви також можете додати BlueBubbles через CLI: @@ -178,30 +178,30 @@ openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --passwor ## Контроль доступу (DM + групи) - - - Типово: `channels.bluebubbles.dmPolicy = "pairing"`. - - Невідомі відправники отримують код сполучення; повідомлення ігноруються, доки їх не схвалять (коди спливають через 1 годину). - - Схвалення через: + + - За замовчуванням: `channels.bluebubbles.dmPolicy = "pairing"`. + - Невідомі відправники отримують код сполучення; повідомлення ігноруються, доки їх не буде схвалено (коди спливають через 1 годину). + - Схвалити через: - `openclaw pairing list bluebubbles` - `openclaw pairing approve bluebubbles ` - - Сполучення — це типовий обмін токенами. Докладніше: [Сполучення](/uk/channels/pairing) + - Сполучення є типовим обміном токенами. Докладніше: [Сполучення](/uk/channels/pairing) - - - `channels.bluebubbles.groupPolicy = open | allowlist | disabled` (типово: `allowlist`). - - `channels.bluebubbles.groupAllowFrom` керує тим, хто може запускати в групах, коли встановлено `allowlist`. + + - `channels.bluebubbles.groupPolicy = open | allowlist | disabled` (за замовчуванням: `allowlist`). + - `channels.bluebubbles.groupAllowFrom` контролює, хто може запускати agent у групах, коли встановлено `allowlist`. -### Збагачення імен контактів (macOS, необов'язково) +### Збагачення імен контактів (macOS, необов’язково) -Групові вебхуки BlueBubbles часто містять лише необроблені адреси учасників. Якщо ви хочете, щоб контекст `GroupMembers` натомість показував локальні імена контактів, можете увімкнути локальне збагачення Contacts на macOS: +Групові webhooks BlueBubbles часто містять лише сирі адреси учасників. Якщо ви хочете, щоб контекст `GroupMembers` натомість показував локальні імена контактів, ви можете ввімкнути збагачення локальними Contacts на macOS: -- `channels.bluebubbles.enrichGroupParticipantsFromContacts = true` вмикає пошук. Типово: `false`. -- Пошуки виконуються лише після того, як доступ до групи, авторизація команди та фільтрація згадок пропустили повідомлення. -- Збагачуються лише учасники з телефонами без імен. -- Необроблені номери телефонів залишаються резервним варіантом, коли локальний збіг не знайдено. +- `channels.bluebubbles.enrichGroupParticipantsFromContacts = true` вмикає пошук. За замовчуванням: `false`. +- Пошуки запускаються лише після того, як доступ до групи, авторизація команди та mention gating пропустили повідомлення. +- Збагачуються лише учасники з телефонними номерами без імен. +- Сирі номери телефонів залишаються fallback-значенням, коли локальний збіг не знайдено. ```json5 { @@ -213,13 +213,13 @@ openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --passwor } ``` -### Фільтрація згадок (групи) +### Mention gating (групи) -BlueBubbles підтримує фільтрацію згадок для групових чатів, відповідно до поведінки iMessage/WhatsApp: +BlueBubbles підтримує mention gating для групових чатів, що відповідає поведінці iMessage/WhatsApp: - Використовує `agents.list[].groupChat.mentionPatterns` (або `messages.groupChat.mentionPatterns`) для виявлення згадок. -- Коли для групи увімкнено `requireMention`, агент відповідає лише тоді, коли його згадано. -- Керівні команди від авторизованих відправників обходять фільтрацію згадок. +- Коли `requireMention` увімкнено для групи, agent відповідає лише тоді, коли його згадали. +- Команди керування від авторизованих відправників обходять mention gating. Конфігурація для окремої групи: @@ -238,15 +238,15 @@ BlueBubbles підтримує фільтрацію згадок для груп } ``` -### Фільтрація команд +### Command gating -- Керівні команди (наприклад, `/config`, `/model`) потребують авторизації. -- Використовує `allowFrom` і `groupAllowFrom`, щоб визначити авторизацію команди. -- Авторизовані відправники можуть виконувати керівні команди навіть без згадування в групах. +- Команди керування (наприклад, `/config`, `/model`) потребують авторизації. +- Використовує `allowFrom` і `groupAllowFrom` для визначення авторизації команд. +- Авторизовані відправники можуть запускати команди керування навіть без згадування в групах. ### Системний prompt для окремої групи -Кожен запис у `channels.bluebubbles.groups.*` приймає необов'язковий рядок `systemPrompt`. Значення вставляється в системний prompt агента на кожному ході, який обробляє повідомлення в цій групі, тож ви можете задавати персоналізацію або поведінкові правила для окремої групи без редагування prompt агента: +Кожен запис у `channels.bluebubbles.groups.*` приймає необов’язковий рядок `systemPrompt`. Значення додається до системного prompt agent на кожному ході, який обробляє повідомлення в цій групі, тож ви можете задати persona або поведінкові правила для окремої групи без редагування prompt agent: ```json5 { @@ -262,11 +262,11 @@ BlueBubbles підтримує фільтрацію згадок для груп } ``` -Ключ відповідає тому, що BlueBubbles повідомляє як `chatGuid` / `chatIdentifier` / числовий `chatId` для групи, а wildcard-запис `"*"` задає типове значення для кожної групи без точного збігу (той самий шаблон використовується `requireMention` і політиками інструментів для окремих груп). Точні збіги завжди мають перевагу над wildcard. DM ігнорують це поле; натомість використовуйте налаштування prompt на рівні агента або облікового запису. +Ключ відповідає тому, що BlueBubbles повідомляє як `chatGuid` / `chatIdentifier` / числовий `chatId` для групи, а wildcard-запис `"*"` задає значення за замовчуванням для кожної групи без точного збігу (той самий шаблон, що використовується `requireMention` і політиками інструментів для окремих груп). Точні збіги завжди мають пріоритет над wildcard. DM ігнорують це поле; натомість використовуйте налаштування prompt на рівні agent або облікового запису. -#### Практичний приклад: гілковані відповіді та tapback-реакції (Private API) +#### Робочий приклад: гілковані відповіді та tapback-реакції (Private API) -Коли BlueBubbles Private API увімкнено, вхідні повідомлення надходять із короткими ID повідомлень (наприклад `[[reply_to:5]]`), а агент може викликати `action=reply`, щоб відповісти в гілці конкретного повідомлення, або `action=react`, щоб додати tapback. `systemPrompt` для окремої групи — надійний спосіб утримувати агента в межах правильного інструмента: +Коли увімкнено BlueBubbles Private API, вхідні повідомлення надходять із короткими ідентифікаторами повідомлень (наприклад, `[[reply_to:5]]`), а agent може викликати `action=reply`, щоб відповісти в гілці конкретного повідомлення, або `action=react`, щоб залишити tapback. `systemPrompt` для окремої групи — надійний спосіб змусити agent вибирати правильний інструмент: ```json5 { @@ -290,29 +290,29 @@ BlueBubbles підтримує фільтрацію згадок для груп } ``` -І tapback-реакції, і гілковані відповіді потребують BlueBubbles Private API; див. [Розширені дії](#advanced-actions) і [ID повідомлень](#message-ids-short-vs-full) щодо базових механік. +Tapback-реакції та гілковані відповіді обидві потребують BlueBubbles Private API; див. [Розширені дії](#advanced-actions) і [Ідентифікатори повідомлень](#message-ids-short-vs-full), щоб дізнатися про базову механіку. -## Прив'язки розмов ACP +## Прив’язки розмов ACP -Чати BlueBubbles можна перетворити на довготривалі робочі простори ACP без зміни транспортного рівня. +Чати BlueBubbles можна перетворити на довговічні робочі простори ACP без зміни транспортного шару. Швидкий потік оператора: -- Запустіть `/acp spawn codex --bind here` у DM або дозволеному груповому чаті. -- Майбутні повідомлення в тій самій розмові BlueBubbles спрямовуються до створеної сесії ACP. -- `/new` і `/reset` скидають ту саму прив'язану сесію ACP на місці. -- `/acp close` закриває сесію ACP і видаляє прив'язку. +- Запустіть `/acp spawn codex --bind here` усередині DM або дозволеного групового чату. +- Майбутні повідомлення в тій самій розмові BlueBubbles маршрутизуються до створеного сеансу ACP. +- `/new` і `/reset` скидають той самий прив’язаний сеанс ACP на місці. +- `/acp close` закриває сеанс ACP і видаляє прив’язку. -Також підтримуються налаштовані постійні прив'язки через записи верхнього рівня `bindings[]` з `type: "acp"` і `match.channel: "bluebubbles"`. +Налаштовані постійні прив’язки також підтримуються через записи верхнього рівня `bindings[]` з `type: "acp"` і `match.channel: "bluebubbles"`. `match.peer.id` може використовувати будь-яку підтримувану форму цілі BlueBubbles: -- нормалізований DM-handle, наприклад `+15555550123` або `user@example.com` +- нормалізований DM handle, як-от `+15555550123` або `user@example.com` - `chat_id:` - `chat_guid:` - `chat_identifier:` -Для стабільних групових прив'язок віддавайте перевагу `chat_id:*` або `chat_identifier:*`. +Для стабільних групових прив’язок віддавайте перевагу `chat_id:*` або `chat_identifier:*`. Приклад: @@ -344,13 +344,13 @@ BlueBubbles підтримує фільтрацію згадок для груп } ``` -Див. [ACP Agents](/uk/tools/acp-agents) щодо спільної поведінки прив'язок ACP. +Див. [ACP Agents](/uk/tools/acp-agents) щодо спільної поведінки прив’язок ACP. ## Набір тексту + сповіщення про прочитання -- **Індикатори набору**: надсилаються автоматично до та під час генерації відповіді. -- **Сповіщення про прочитання**: керуються `channels.bluebubbles.sendReadReceipts` (типово: `true`). -- **Індикатори набору**: OpenClaw надсилає події початку набору; BlueBubbles автоматично очищає набір під час надсилання або після тайм-ауту (ручна зупинка через DELETE ненадійна). +- **Індикатори набору**: надсилаються автоматично перед і під час генерації відповіді. +- **Підтвердження прочитання**: керуються `channels.bluebubbles.sendReadReceipts` (типово: `true`). +- **Індикатори набору**: OpenClaw надсилає події початку набору; BlueBubbles автоматично очищає стан набору під час надсилання або після тайм-ауту (ручна зупинка через DELETE ненадійна). ```json5 { @@ -389,8 +389,8 @@ BlueBubbles підтримує розширені дії з повідомлен ``` - - - **react**: додати/видалити реакції tapback (`messageId`, `emoji`, `remove`). Вбудований набір tapback в iMessage: `love`, `like`, `dislike`, `laugh`, `emphasize` і `question`. Коли агент вибирає emoji поза цим набором (наприклад, `👀`), інструмент реакцій повертається до `love`, щоб tapback усе одно відобразився замість збою всього запиту. Налаштовані реакції підтвердження все ще перевіряються суворо й повертають помилку для невідомих значень. + + - **react**: додати/видалити tapback-реакції (`messageId`, `emoji`, `remove`). Нативний набір tapback в iMessage: `love`, `like`, `dislike`, `laugh`, `emphasize` і `question`. Коли агент вибирає emoji поза цим набором (наприклад `👀`), інструмент реакцій повертається до `love`, щоб tapback усе одно відобразився, а не зірвав увесь запит. Налаштовані ack-реакції й далі проходять сувору валідацію та дають помилку для невідомих значень. - **edit**: редагувати надіслане повідомлення (`messageId`, `text`). - **unsend**: скасувати надсилання повідомлення (`messageId`). - **reply**: відповісти на конкретне повідомлення (`messageId`, `text`, `to`). @@ -401,22 +401,22 @@ BlueBubbles підтримує розширені дії з повідомлен - **removeParticipant**: видалити когось із групи (`chatGuid`, `address`). - **leaveGroup**: вийти з групового чату (`chatGuid`). - **upload-file**: надіслати медіа/файли (`to`, `buffer`, `filename`, `asVoice`). - - Голосові нотатки: задайте `asVoice: true` з аудіо **MP3** або **CAF**, щоб надіслати як голосове повідомлення iMessage. BlueBubbles перетворює MP3 → CAF під час надсилання голосових нотаток. - - Застарілий псевдонім: `sendAttachment` усе ще працює, але `upload-file` є канонічною назвою дії. + - Голосові нотатки: установіть `asVoice: true` з аудіо **MP3** або **CAF**, щоб надіслати як голосове повідомлення iMessage. BlueBubbles перетворює MP3 → CAF під час надсилання голосових нотаток. + - Застарілий псевдонім: `sendAttachment` і далі працює, але `upload-file` є канонічною назвою дії. -### Ідентифікатори повідомлень (короткі та повні) +### ID повідомлень (короткі й повні) -OpenClaw може показувати _короткі_ ідентифікатори повідомлень (наприклад, `1`, `2`), щоб заощадити токени. +OpenClaw може показувати _короткі_ ID повідомлень (наприклад, `1`, `2`), щоб заощаджувати токени. -- `MessageSid` / `ReplyToId` можуть бути короткими ідентифікаторами. -- `MessageSidFull` / `ReplyToIdFull` містять повні ідентифікатори провайдера. -- Короткі ідентифікатори зберігаються в пам'яті; вони можуть застаріти після перезапуску або витіснення з кешу. -- Дії приймають короткий або повний `messageId`, але короткі ідентифікатори спричинять помилку, якщо вони більше недоступні. +- `MessageSid` / `ReplyToId` можуть бути короткими ID. +- `MessageSidFull` / `ReplyToIdFull` містять повні ID провайдера. +- Короткі ID зберігаються в пам’яті; вони можуть застаріти після перезапуску або витіснення з кешу. +- Дії приймають короткий або повний `messageId`, але короткі ID спричинять помилку, якщо вони більше недоступні. -Використовуйте повні ідентифікатори для довговічних автоматизацій і зберігання: +Використовуйте повні ID для довготривалих автоматизацій і зберігання: - Шаблони: `{{MessageSidFull}}`, `{{ReplyToIdFull}}` - Контекст: `MessageSidFull` / `ReplyToIdFull` у вхідних payload @@ -425,32 +425,32 @@ OpenClaw може показувати _короткі_ ідентифікато -## Об'єднання DM із розділеним надсиланням (команда + URL в одному складеному повідомленні) +## Об’єднання split-send DM (команда + URL в одному складанні) -Коли користувач вводить команду та URL разом в iMessage — наприклад, `Dump https://example.com/article` — Apple розділяє надсилання на **дві окремі доставки webhook**: +Коли користувач вводить команду й URL разом в iMessage — наприклад `Dump https://example.com/article` — Apple розділяє надсилання на **дві окремі доставки Webhook**: 1. Текстове повідомлення (`"Dump"`). -2. Бульбашку URL-перегляду (`"https://..."`) з OG-зображеннями попереднього перегляду як вкладеннями. +2. Бульбашка URL-прев’ю (`"https://..."`) із зображеннями OG-прев’ю як вкладеннями. -Два webhook надходять до OpenClaw з інтервалом приблизно 0,8-2,0 с у більшості конфігурацій. Без об'єднання агент отримує лише команду на ході 1, відповідає (часто "надішли мені URL") і бачить URL лише на ході 2 — коли контекст команди вже втрачено. +У більшості налаштувань два Webhook надходять в OpenClaw з інтервалом приблизно 0,8-2,0 с. Без об’єднання агент отримує лише команду на ході 1, відповідає (часто «надішліть мені URL») і бачить URL лише на ході 2 — коли контекст команди вже втрачено. -`channels.bluebubbles.coalesceSameSenderDms` вмикає для DM об'єднання послідовних webhook від того самого відправника в один хід агента. Групові чати й надалі ключуються за повідомленням, щоб зберегти структуру ходів із кількома користувачами. +`channels.bluebubbles.coalesceSameSenderDms` вмикає для DM об’єднання послідовних Webhook від того самого відправника в один хід агента. Групові чати й далі прив’язуються до окремих повідомлень, щоб зберегти структуру ходів кількох користувачів. - + Увімкніть, коли: - - Ви постачаєте skills, які очікують `command + payload` в одному повідомленні (dump, paste, save, queue тощо). + - Ви постачаєте Skills, які очікують `command + payload` в одному повідомленні (dump, paste, save, queue тощо). - Ваші користувачі вставляють URL, зображення або довгий вміст разом із командами. - Ви можете прийняти додаткову затримку ходу DM (див. нижче). Залиште вимкненим, коли: - - Вам потрібна мінімальна затримка команди для однослівних тригерів DM. - - Усі ваші потоки — одноразові команди без подальших payload. + - Вам потрібна мінімальна затримка команд для однословних тригерів DM. + - Усі ваші потоки є одноразовими командами без наступних payload. - + ```json5 { channels: { @@ -461,7 +461,7 @@ OpenClaw може показувати _короткі_ ідентифікато } ``` - Коли прапорець увімкнено й немає явного `messages.inbound.byChannel.bluebubbles`, вікно debounce розширюється до **2500 мс** (типове значення без об'єднання — 500 мс). Ширше вікно потрібне — cadence розділеного надсилання Apple у 0,8-2,0 с не вкладається в жорсткіше типове значення. + Коли прапорець увімкнено й немає явного `messages.inbound.byChannel.bluebubbles`, debounce-вікно розширюється до **2500 мс** (типово для режиму без об’єднання — 500 мс). Ширше вікно потрібне, бо cadence split-send від Apple у 0,8-2,0 с не вкладається в тісніше типове значення. Щоб налаштувати вікно самостійно: @@ -480,62 +480,62 @@ OpenClaw може показувати _короткі_ ідентифікато ``` - - - **Додаткова затримка для керівних команд DM.** Коли прапорець увімкнено, повідомлення керівних команд DM (як-от `Dump`, `Save` тощо) тепер очікують до кінця вікна debounce перед відправленням на обробку, на випадок якщо надходить webhook із payload. Команди в групових чатах зберігають миттєве відправлення. - - **Об'єднаний вивід обмежений** — об'єднаний текст обмежується 4000 символами з явним маркером `…[truncated]`; вкладення — 20; записи джерел — 10 (понад це зберігаються перший і найновіший). Кожен вихідний `messageId` усе ще потрапляє до дедуплікації вхідних повідомлень, тому пізніший повтор будь-якої окремої події MessagePoller розпізнається як дублікат. - - **Увімкнення окремо для каналу.** Інші канали (Telegram, WhatsApp, Slack, …) не зачіпаються. + + - **Додана затримка для керівних команд DM.** Коли прапорець увімкнено, повідомлення керівних команд DM (наприклад `Dump`, `Save` тощо) тепер чекають до завершення debounce-вікна перед dispatch, на випадок якщо надходить Webhook із payload. Команди групового чату зберігають миттєвий dispatch. + - **Об’єднаний вивід обмежений** — об’єднаний текст обмежується 4000 символами з явним маркером `…[truncated]`; вкладення обмежуються 20; записи джерел обмежуються 10 (понад це зберігаються перший і найновіший). Кожен вихідний `messageId` усе одно доходить до inbound-dedupe, тож пізніший replay MessagePoller будь-якої окремої події розпізнається як дублікат. + - **Opt-in, для окремого каналу.** Інші канали (Telegram, WhatsApp, Slack, …) не зачіпаються. -### Сценарії та що бачить агент +### Сценарії й те, що бачить агент -| Користувач складає повідомлення | Apple доставляє | Прапорець вимкнено (типово) | Прапорець увімкнено + вікно 2500 мс | -| ------------------------------------------------------------------ | ------------------------- | --------------------------------------- | ----------------------------------------------------------------------- | -| `Dump https://example.com` (одне надсилання) | 2 webhook з інтервалом ~1 с | Два ходи агента: лише "Dump", потім URL | Один хід: об'єднаний текст `Dump https://example.com` | -| `Save this 📎image.jpg caption` (вкладення + текст) | 2 webhook | Два ходи | Один хід: текст + зображення | -| `/status` (окрема команда) | 1 webhook | Миттєве відправлення | **Очікує до кінця вікна, потім відправляється** | -| URL, вставлений окремо | 1 webhook | Миттєве відправлення | Миттєве відправлення (лише один запис у bucket) | -| Текст + URL, надіслані як два навмисно окремі повідомлення з різницею в хвилини | 2 webhook поза вікном | Два ходи | Два ходи (вікно спливає між ними) | -| Швидкий потік (>10 малих DM усередині вікна) | N webhook | N ходів | Один хід, обмежений вивід (перший + найновіший, застосовано обмеження тексту/вкладень) | +| Користувач складає | Apple доставляє | Прапорець вимкнено (типово) | Прапорець увімкнено + вікно 2500 мс | +| ------------------------------------------------------------------ | ------------------------------ | --------------------------------------- | ----------------------------------------------------------------------- | +| `Dump https://example.com` (одне надсилання) | 2 Webhook з інтервалом ~1 с | Два ходи агента: лише "Dump", потім URL | Один хід: об’єднаний текст `Dump https://example.com` | +| `Save this 📎image.jpg caption` (вкладення + текст) | 2 Webhook | Два ходи | Один хід: текст + зображення | +| `/status` (окрема команда) | 1 Webhook | Миттєвий dispatch | **Чекати до вікна, потім dispatch** | +| URL, вставлений окремо | 1 Webhook | Миттєвий dispatch | Миттєвий dispatch (лише один запис у bucket) | +| Текст + URL, надіслані як два навмисно окремі повідомлення, з різницею в хвилини | 2 Webhook поза вікном | Два ходи | Два ходи (вікно завершується між ними) | +| Швидкий потік (>10 малих DM у межах вікна) | N Webhook | N ходів | Один хід, обмежений вивід (перший + найновіший, застосовані обмеження тексту/вкладень) | -### Усунення проблем з об'єднанням розділеного надсилання +### Усунення несправностей об’єднання split-send -Якщо прапорець увімкнено, але розділені надсилання все ще надходять як два ходи, перевірте кожен рівень: +Якщо прапорець увімкнено, але split-send і далі надходять як два ходи, перевірте кожен рівень: - + ``` grep coalesceSameSenderDms ~/.openclaw/openclaw.json ``` - Потім `openclaw gateway restart` — прапорець читається під час створення реєстру debouncer. + Потім `openclaw gateway restart` — прапорець зчитується під час створення debouncer-registry. - + Перегляньте журнал сервера BlueBubbles у `~/Library/Logs/bluebubbles-server/main.log`: ``` grep -E "Dispatching event to webhook" main.log | tail -20 ``` - Виміряйте проміжок між відправленням тексту на кшталт `"Dump"` і наступним відправленням `"https://..."; Attachments:`. Збільште `messages.inbound.byChannel.bluebubbles`, щоб він із запасом покривав цей проміжок. + Виміряйте проміжок між dispatch тексту в стилі `"Dump"` і наступним dispatch `"https://..."; Attachments:`. Збільште `messages.inbound.byChannel.bluebubbles`, щоб із запасом покрити цей проміжок. - - Мітки часу подій сеансу (`~/.openclaw/agents//sessions/*.jsonl`) відображають момент, коли Gateway передає повідомлення агенту, **а не** момент надходження webhook. Друге повідомлення в черзі з позначкою `[Queued messages while agent was busy]` означає, що перший хід усе ще виконувався, коли надійшов другий webhook — bucket об'єднання вже було скинуто. Налаштовуйте вікно за журналом сервера BB, а не за журналом сеансу. + + Позначки часу подій сеансу (`~/.openclaw/agents//sessions/*.jsonl`) відображають момент, коли Gateway передає повідомлення агенту, **а не** момент надходження Webhook. Друге повідомлення в черзі, позначене `[Queued messages while agent was busy]`, означає, що перший хід усе ще виконувався, коли надійшов другий Webhook — bucket об’єднання вже було скинуто. Налаштовуйте вікно за журналом сервера BB, а не за журналом сеансу. - - На менших машинах (8 ГБ) ходи агента можуть тривати достатньо довго, щоб bucket об'єднання скинувся до завершення відповіді, і URL потрапив як другий хід у черзі. Перевірте `memory_pressure` і `ps -o rss -p $(pgrep openclaw-gateway)`; якщо Gateway має понад ~500 МБ RSS і компресор активний, закрийте інші важкі процеси або перейдіть на більший хост. + + На менших машинах (8 ГБ) ходи агента можуть тривати достатньо довго, щоб bucket об’єднання скинувся до завершення відповіді, і URL потрапив як другий хід у черзі. Перевірте `memory_pressure` і `ps -o rss -p $(pgrep openclaw-gateway)`; якщо Gateway використовує понад ~500 МБ RSS і compressor активний, закрийте інші важкі процеси або перейдіть на більший хост. - - Якщо користувач натиснув `Dump` як **відповідь** на наявну URL-бульбашку (iMessage показує бейдж "1 Reply" на бульбашці Dump), URL міститься в `replyToBody`, а не в другому webhook. Об'єднання не застосовується — це питання skill/промпта, а не debouncer. + + Якщо користувач натиснув `Dump` як **відповідь** на наявну URL-бульбашку (iMessage показує бейдж "1 Reply" на бульбашці Dump), URL міститься в `replyToBody`, а не в другому Webhook. Об’єднання не застосовується — це питання skill/prompt, а не debouncer. ## Блокове потокове передавання -Керуйте тим, чи відповіді надсилаються як одне повідомлення, чи потоково блоками: +Керує тим, чи відповіді надсилаються як одне повідомлення, чи потоково блоками: ```json5 { @@ -551,47 +551,48 @@ OpenClaw може показувати _короткі_ ідентифікато - Вхідні вкладення завантажуються та зберігаються в кеші медіа. - Обмеження медіа через `channels.bluebubbles.mediaMaxMb` для вхідних і вихідних медіа (типово: 8 МБ). -- Вихідний текст розбивається на фрагменти за `channels.bluebubbles.textChunkLimit` (типово: 4000 символів). +- Вихідний текст розбивається на частини за `channels.bluebubbles.textChunkLimit` (типово: 4000 символів). ## Довідник конфігурації Повна конфігурація: [Конфігурація](/uk/gateway/configuration) - + - `channels.bluebubbles.enabled`: увімкнути/вимкнути канал. - - `channels.bluebubbles.serverUrl`: базова URL-адреса REST API BlueBubbles. + - `channels.bluebubbles.serverUrl`: базовий URL REST API BlueBubbles. - `channels.bluebubbles.password`: пароль API. - - `channels.bluebubbles.webhookPath`: шлях endpoint webhook (типово: `/bluebubbles-webhook`). + - `channels.bluebubbles.webhookPath`: шлях endpoint Webhook (типово: `/bluebubbles-webhook`). - + - `channels.bluebubbles.dmPolicy`: `pairing | allowlist | open | disabled` (типово: `pairing`). - - `channels.bluebubbles.allowFrom`: allowlist DM (handles, emails, E.164 numbers, `chat_id:*`, `chat_guid:*`). + - `channels.bluebubbles.allowFrom`: allowlist DM (handles, email, номери E.164, `chat_id:*`, `chat_guid:*`). - `channels.bluebubbles.groupPolicy`: `open | allowlist | disabled` (типово: `allowlist`). - `channels.bluebubbles.groupAllowFrom`: allowlist відправників групи. - - `channels.bluebubbles.enrichGroupParticipantsFromContacts`: на macOS, за потреби доповнювати безіменних учасників групи з локальних Контактів після проходження gating. Типово: `false`. - - `channels.bluebubbles.groups`: конфігурація для кожної групи (`requireMention` тощо). + - `channels.bluebubbles.enrichGroupParticipantsFromContacts`: на macOS, за бажанням доповнювати безіменних учасників групи з локальних Contacts після проходження gating. Типово: `false`. + - `channels.bluebubbles.groups`: конфігурація для окремих груп (`requireMention` тощо). - - `channels.bluebubbles.sendReadReceipts`: Надсилати сповіщення про прочитання (типово: `true`). + - `channels.bluebubbles.sendReadReceipts`: Надсилати підтвердження прочитання (типово: `true`). - `channels.bluebubbles.blockStreaming`: Увімкнути блокове потокове передавання (типово: `false`; потрібно для потокових відповідей). - `channels.bluebubbles.textChunkLimit`: Розмір вихідного фрагмента в символах (типово: 4000). - - `channels.bluebubbles.sendTimeoutMs`: Тайм-аут на запит у мс для надсилання вихідного тексту через `/api/v1/message/text` (типово: 30000). Збільште на конфігураціях macOS 26, де надсилання Private API iMessage може зависати на 60+ секунд усередині фреймворку iMessage; наприклад `45000` або `60000`. Перевірки, пошук чатів, реакції, редагування та перевірки справності наразі зберігають коротше типове значення 10 с; розширення покриття на реакції та редагування заплановано як подальше поліпшення. Перевизначення для окремого облікового запису: `channels.bluebubbles.accounts..sendTimeoutMs`. - - `channels.bluebubbles.chunkMode`: `length` (типово) розбиває лише за перевищення `textChunkLimit`; `newline` розбиває за порожніми рядками (межами абзаців) перед фрагментацією за довжиною. + - `channels.bluebubbles.sendTimeoutMs`: Тайм-аут на запит у мс для надсилання вихідного тексту через `/api/v1/message/text` (типово: 30000). Збільште для налаштувань macOS 26, де надсилання iMessage через Private API може зависати на 60+ секунд усередині фреймворку iMessage; наприклад `45000` або `60000`. Зондування, пошук чатів, реакції, редагування та перевірки стану наразі зберігають коротше типове значення 10 с; розширення покриття на реакції та редагування заплановано як наступний крок. Перевизначення для окремого облікового запису: `channels.bluebubbles.accounts..sendTimeoutMs`. + - `channels.bluebubbles.chunkMode`: `length` (типово) розбиває лише за перевищення `textChunkLimit`; `newline` розбиває за порожніми рядками (межами абзаців) перед розбиттям за довжиною. - - `channels.bluebubbles.mediaMaxMb`: Обмеження вхідних/вихідних медіа в МБ (типово: 8). - - `channels.bluebubbles.mediaLocalRoots`: Явний список дозволених абсолютних локальних каталогів, дозволених для вихідних локальних шляхів до медіа. Надсилання локальних шляхів типово заборонено, якщо це не налаштовано. Перевизначення для окремого облікового запису: `channels.bluebubbles.accounts..mediaLocalRoots`. - - `channels.bluebubbles.coalesceSameSenderDms`: Об’єднувати послідовні Webhook DM від одного відправника в один хід агента, щоб розділене Apple надсилання текст+URL надходило як одне повідомлення (типово: `false`). Див. [Об’єднання розділених DM](#coalescing-split-send-dms-command--url-in-one-composition) для сценаріїв, налаштування вікна та компромісів. Розширює типове вікно debounce для вхідних повідомлень із 500 мс до 2500 мс, коли ввімкнено без явного `messages.inbound.byChannel.bluebubbles`. + - `channels.bluebubbles.mediaMaxMb`: Ліміт вхідних/вихідних медіа в МБ (типово: 8). + - `channels.bluebubbles.mediaLocalRoots`: Явний список дозволених абсолютних локальних каталогів, дозволених для вихідних локальних шляхів медіа. Надсилання локальних шляхів типово заборонено, якщо це не налаштовано. Перевизначення для окремого облікового запису: `channels.bluebubbles.accounts..mediaLocalRoots`. + - `channels.bluebubbles.coalesceSameSenderDms`: Об’єднувати послідовні DM-вебхуки від того самого відправника в один хід агента, щоб Apple-розділення текст+URL надходило як одне повідомлення (типово: `false`). Див. [Об’єднання розділених DM](#coalescing-split-send-dms-command--url-in-one-composition) для сценаріїв, налаштування вікна та компромісів. Розширює типове вікно debounce для вхідних повідомлень із 500 мс до 2500 мс, якщо ввімкнено без явного `messages.inbound.byChannel.bluebubbles`. - `channels.bluebubbles.historyLimit`: Максимальна кількість групових повідомлень для контексту (0 вимикає). - - `channels.bluebubbles.dmHistoryLimit`: Обмеження історії DM. + - `channels.bluebubbles.dmHistoryLimit`: Ліміт історії DM. + - `channels.bluebubbles.replyContextApiFallback`: Коли вхідна відповідь надходить без `replyToBody`/`replyToSender` і кеш контексту відповіді в пам’яті не спрацьовує, отримувати оригінальне повідомлення з BlueBubbles HTTP API як резервний варіант best-effort (типово: `false`). Корисно для розгортань із кількома екземплярами, що спільно використовують один обліковий запис BlueBubbles, після перезапусків процесу або після витіснення з довготривалого кешу TTL/LRU. Отримання захищене від SSRF тією самою політикою, що й кожен інший запит клієнта BlueBubbles, ніколи не кидає виняток і заповнює кеш, щоб подальші відповіді амортизували витрати. Перевизначення для окремого облікового запису: `channels.bluebubbles.accounts..replyContextApiFallback`. Налаштування рівня каналу поширюється на облікові записи, які пропускають цей прапорець. - - `channels.bluebubbles.actions`: Увімкнути/вимкнути певні дії. + - `channels.bluebubbles.actions`: Увімкнути/вимкнути конкретні дії. - `channels.bluebubbles.accounts`: Конфігурація кількох облікових записів. @@ -604,7 +605,7 @@ OpenClaw може показувати _короткі_ ідентифікато ## Адресація / цілі доставки -Надавайте перевагу `chat_guid` для стабільної маршрутизації: +Віддавайте перевагу `chat_guid` для стабільної маршрутизації: - `chat_guid:iMessage;-;+15555550123` (бажано для груп) - `chat_id:123` @@ -612,34 +613,34 @@ OpenClaw може показувати _короткі_ ідентифікато - Прямі дескриптори: `+15555550123`, `user@example.com` - Якщо прямий дескриптор не має наявного DM-чату, OpenClaw створить його через `POST /api/v1/chat/new`. Для цього потрібно ввімкнути BlueBubbles Private API. -### Маршрутизація iMessage і SMS +### Маршрутизація iMessage проти SMS -Коли той самий дескриптор має на Mac і iMessage-, і SMS-чат (наприклад, номер телефону, зареєстрований в iMessage, але який також отримував резервні повідомлення з зеленими бульбашками), OpenClaw надає перевагу чату iMessage і ніколи тихо не переходить на SMS. Щоб примусово використати SMS-чат, застосуйте явний префікс цілі `sms:` (наприклад `sms:+15555550123`). Дескриптори без відповідного iMessage-чату все одно надсилаються через будь-який чат, який повідомляє BlueBubbles. +Коли той самий дескриптор має і iMessage, і SMS-чат на Mac (наприклад номер телефону, зареєстрований в iMessage, але який також отримував зелені fallback-повідомлення), OpenClaw віддає перевагу чату iMessage і ніколи безшумно не понижує до SMS. Щоб примусово використати SMS-чат, застосуйте явний цільовий префікс `sms:` (наприклад `sms:+15555550123`). Дескриптори без відповідного iMessage-чату все одно надсилаються через будь-який чат, який повідомляє BlueBubbles. ## Безпека -- Запити Webhook автентифікуються порівнянням параметрів запиту або заголовків `guid`/`password` із `channels.bluebubbles.password`. -- Тримайте пароль API та кінцеву точку Webhook у секреті (розглядайте їх як облікові дані). -- Для автентифікації BlueBubbles Webhook немає обходу через localhost. Якщо ви проксіюєте трафік Webhook, зберігайте пароль BlueBubbles у запиті наскрізно. `gateway.trustedProxies` тут не замінює `channels.bluebubbles.password`. Див. [Безпека Gateway](/uk/gateway/security#reverse-proxy-configuration). -- Увімкніть HTTPS + правила брандмауера на сервері BlueBubbles, якщо відкриваєте його за межі вашої LAN. +- Webhook-запити автентифікуються шляхом порівняння query-параметрів або заголовків `guid`/`password` із `channels.bluebubbles.password`. +- Зберігайте пароль API та кінцеву точку Webhook у таємниці (ставтеся до них як до облікових даних). +- Для автентифікації Webhook BlueBubbles немає обходу через localhost. Якщо ви проксіюєте Webhook-трафік, зберігайте пароль BlueBubbles у запиті наскрізно. `gateway.trustedProxies` тут не замінює `channels.bluebubbles.password`. Див. [Безпека Gateway](/uk/gateway/security#reverse-proxy-configuration). +- Увімкніть HTTPS і правила firewall на сервері BlueBubbles, якщо відкриваєте його за межі своєї LAN. ## Усунення несправностей -- Якщо події введення/прочитання перестають працювати, перевірте журнали BlueBubbles Webhook і переконайтеся, що шлях Gateway відповідає `channels.bluebubbles.webhookPath`. +- Якщо події введення/прочитання перестали працювати, перевірте журнали Webhook BlueBubbles і переконайтеся, що шлях Gateway відповідає `channels.bluebubbles.webhookPath`. - Коди сполучення спливають через одну годину; використовуйте `openclaw pairing list bluebubbles` і `openclaw pairing approve bluebubbles `. - Для реакцій потрібен приватний API BlueBubbles (`POST /api/v1/message/react`); переконайтеся, що версія сервера його надає. -- Для редагування/скасування надсилання потрібні macOS 13+ і сумісна версія сервера BlueBubbles. На macOS 26 (Tahoe) редагування наразі не працює через зміни приватного API. -- Оновлення іконок груп можуть бути нестабільними на macOS 26 (Tahoe): API може повернути успіх, але нова іконка не синхронізується. -- OpenClaw автоматично приховує відомі непрацездатні дії на основі версії macOS сервера BlueBubbles. Якщо редагування все ще з’являється на macOS 26 (Tahoe), вимкніть його вручну через `channels.bluebubbles.actions.edit=false`. -- `coalesceSameSenderDms` увімкнено, але розділені надсилання (наприклад, `Dump` + URL) все одно надходять як два ходи: див. контрольний список [усунення несправностей об’єднання розділених надсилань](#split-send-coalescing-troubleshooting) — поширені причини: занадто вузьке вікно debounce, часові позначки журналу сесії помилково прийнято за час надходження Webhook або надсилання з цитатою-відповіддю (яке використовує `replyToBody`, а не другий Webhook). -- Для інформації про стан/справність: `openclaw status --all` або `openclaw status --deep`. +- Для редагування/скасування надсилання потрібні macOS 13+ і сумісна версія сервера BlueBubbles. На macOS 26 (Tahoe) редагування наразі зламане через зміни private API. +- Оновлення іконки групи може бути нестабільним на macOS 26 (Tahoe): API може повернути успіх, але нова іконка не синхронізується. +- OpenClaw автоматично приховує відомо зламані дії на основі версії macOS сервера BlueBubbles. Якщо редагування все ще відображається на macOS 26 (Tahoe), вимкніть його вручну за допомогою `channels.bluebubbles.actions.edit=false`. +- `coalesceSameSenderDms` увімкнено, але розділені надсилання (наприклад `Dump` + URL) усе ще надходять як два ходи: див. контрольний список [усунення несправностей об’єднання розділених надсилань](#split-send-coalescing-troubleshooting) — поширені причини: занадто вузьке debounce-вікно, часові позначки журналу сесії помилково сприйняті як надходження Webhook, або надсилання цитати-відповіді (яке використовує `replyToBody`, а не другий Webhook). +- Для інформації про статус/стан: `openclaw status --all` або `openclaw status --deep`. -Загальну довідку щодо робочих процесів каналів див. у [Каналах](/uk/channels) і посібнику [Plugins](/uk/tools/plugin). +Загальну довідку щодо робочого процесу каналів див. у [Канали](/uk/channels) та посібнику [Plugins](/uk/tools/plugin). ## Пов’язане - [Маршрутизація каналів](/uk/channels/channel-routing) — маршрутизація сесій для повідомлень - [Огляд каналів](/uk/channels) — усі підтримувані канали -- [Групи](/uk/channels/groups) — поведінка групового чату та керування згадками -- [Сполучення](/uk/channels/pairing) — автентифікація DM і потік сполучення +- [Групи](/uk/channels/groups) — поведінка групового чату та контроль згадок +- [Сполучення](/uk/channels/pairing) — автентифікація DM і процес сполучення - [Безпека](/uk/gateway/security) — модель доступу та посилення захисту