diff --git a/docs/uk/channels/bluebubbles.md b/docs/uk/channels/bluebubbles.md index ef0ad8031..bd61ca9cb 100644 --- a/docs/uk/channels/bluebubbles.md +++ b/docs/uk/channels/bluebubbles.md @@ -3,24 +3,24 @@ read_when: - Налаштування каналу BlueBubbles - Усунення проблем зі сполученням Webhook - Налаштування iMessage на macOS -summary: iMessage через сервер BlueBubbles для macOS (REST-надсилання/отримання, друк, реакції, сполучення, розширені дії). +summary: iMessage через сервер BlueBubbles для macOS (REST надсилання/отримання, набір тексту, реакції, сполучення, розширені дії). title: BlueBubbles x-i18n: - generated_at: "2026-04-20T17:06:46Z" + generated_at: "2026-04-21T03:02:44Z" model: gpt-5.4 provider: openai - source_hash: 5d7186ba92aa63bc811f874e5a910af884c17ad7d6394b5624eec63e17adc2f6 + source_hash: b3d8d617fc86ca1b191ff4dd2ae26b464e4d3f456a79c67b484a3a76d75de0d2 source_path: channels/bluebubbles.md workflow: 15 --- # BlueBubbles (macOS REST) -Статус: вбудований Plugin, який взаємодіє із сервером BlueBubbles для macOS через HTTP. **Рекомендовано для інтеграції iMessage** завдяки багатшому API та простішому налаштуванню порівняно зі застарілим каналом imsg. +Статус: вбудований Plugin, який взаємодіє із сервером BlueBubbles для macOS через HTTP. **Рекомендовано для інтеграції з iMessage** завдяки багатшому API та простішому налаштуванню порівняно зі застарілим каналом imsg. ## Вбудований Plugin -Поточні випуски OpenClaw постачаються з BlueBubbles, тому звичайним пакетованим збіркам не +Поточні випуски OpenClaw постачаються з BlueBubbles, тому звичайним пакетним збіркам не потрібен окремий крок `openclaw plugins install`. ## Огляд @@ -28,16 +28,16 @@ x-i18n: - Працює на 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/*`). -- Вхідні повідомлення надходять через Webhook; вихідні відповіді, індикатори набору, сповіщення про прочитання та tapback-реакції виконуються через REST-виклики. -- Вкладення та стікери обробляються як вхідні медіа (і за можливості передаються агенту). -- Сполучення/список дозволених працює так само, як і в інших каналах (`/channels/pairing` тощо) за допомогою `channels.bluebubbles.allowFrom` + кодів сполучення. -- Реакції відображаються як системні події так само, як у Slack/Telegram, щоб агенти могли "згадати" їх перед відповіддю. -- Розширені можливості: редагування, скасування надсилання, гілки відповідей, ефекти повідомлень, керування групами. +- Вхідні повідомлення надходять через Webhook; вихідні відповіді, індикатори набору тексту, сповіщення про прочитання та tapback — це REST-виклики. +- Вкладення та стікери обробляються як вхідні медіа (і передаються агенту, коли це можливо). +- Сполучення/allowlist працює так само, як і в інших каналах (`/channels/pairing` тощо) з `channels.bluebubbles.allowFrom` + кодами сполучення. +- Реакції відображаються як системні події, так само як у Slack/Telegram, тож агенти можуть «згадувати» їх перед відповіддю. +- Розширені можливості: редагування, скасування надсилання, відповіді у тредах, ефекти повідомлень, керування групами. ## Швидкий початок 1. Встановіть сервер BlueBubbles на ваш Mac (дотримуйтеся інструкцій на [bluebubbles.app/install](https://bluebubbles.app/install)). -2. У конфігурації BlueBubbles увімкніть web API і задайте пароль. +2. У конфігурації BlueBubbles увімкніть web API і встановіть пароль. 3. Запустіть `openclaw onboard` і виберіть BlueBubbles, або налаштуйте вручну: ```json5 @@ -58,13 +58,13 @@ x-i18n: Примітка щодо безпеки: -- Завжди задавайте пароль для Webhook. -- Автентифікація Webhook є завжди обов’язковою. OpenClaw відхиляє запити Webhook BlueBubbles, якщо вони не містять пароль/guid, що збігається з `channels.bluebubbles.password` (наприклад, `?password=` або `x-password`), незалежно від топології loopback/проксі. +- Обов’язково встановіть пароль Webhook. +- Автентифікація Webhook завжди обов’язкова. OpenClaw відхиляє запити Webhook BlueBubbles, якщо вони не містять пароль/guid, що збігається з `channels.bluebubbles.password` (наприклад, `?password=` або `x-password`), незалежно від топології loopback/проксі. - Автентифікація за паролем перевіряється до читання/розбору повних тіл Webhook. -## Підтримання активності Messages.app (VM / headless-середовища) +## Підтримання Messages.app активним (VM / безголові середовища) -У деяких середовищах macOS VM / always-on Messages.app може переходити в “idle” (вхідні події припиняються, доки застосунок не буде відкрито/виведено на передній план). Простий обхідний шлях — **торкатися Messages кожні 5 хвилин** за допомогою AppleScript + LaunchAgent. +У деяких середовищах macOS VM / always-on може статися так, що Messages.app переходить у «неактивний» стан (вхідні події припиняються, доки застосунок не буде відкрито/виведено на передній план). Простий обхідний шлях — **пінгувати Messages кожні 5 хвилин** за допомогою AppleScript + LaunchAgent. ### 1) Збережіть AppleScript @@ -127,7 +127,7 @@ end try Примітки: - Це запускається **кожні 300 секунд** і **під час входу в систему**. -- Перший запуск може викликати запити macOS на **Automation** (`osascript` → Messages). Підтвердіть їх у тій самій користувацькій сесії, де працює LaunchAgent. +- Під час першого запуску можуть з’явитися запити macOS **Automation** (`osascript` → Messages). Підтвердьте їх у тому самому користувацькому сеансі, у якому працює LaunchAgent. Завантажте його: @@ -136,9 +136,9 @@ launchctl unload ~/Library/LaunchAgents/com.user.poke-messages.plist 2>/dev/null launchctl load ~/Library/LaunchAgents/com.user.poke-messages.plist ``` -## Onboarding +## Онбординг -BlueBubbles доступний в інтерактивному Onboarding: +BlueBubbles доступний в інтерактивному онбордингу: ``` openclaw onboard @@ -150,7 +150,7 @@ openclaw onboard - **Password** (обов’язково): пароль API з налаштувань BlueBubbles Server - **Webhook path** (необов’язково): типово `/bluebubbles-webhook` - **Політика DM**: pairing, allowlist, open або disabled -- **Список дозволених**: номери телефонів, email-адреси або цілі чатів +- **Список дозволених**: номери телефонів, електронні адреси або цілі чатів Ви також можете додати BlueBubbles через CLI: @@ -158,30 +158,30 @@ openclaw onboard openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --password ``` -## Керування доступом (DM + групи) +## Контроль доступу (DM + групи) 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.groupAllowFrom` визначає, хто може ініціювати взаємодію в групах, коли встановлено `allowlist`. ### Збагачення імен контактів (macOS, необов’язково) -Webhook груп BlueBubbles часто містять лише сирі адреси учасників. Якщо ви хочете, щоб контекст `GroupMembers` натомість показував локальні імена контактів, на macOS можна ввімкнути локальне збагачення з Contacts: +Webhook груп BlueBubbles часто містять лише необроблені адреси учасників. Якщо ви хочете, щоб контекст `GroupMembers` натомість показував локальні імена контактів, у macOS можна ввімкнути локальне збагачення через Contacts: -- `channels.bluebubbles.enrichGroupParticipantsFromContacts = true` вмикає пошук. Типово: `false`. -- Пошук виконується лише після того, як груповий доступ, авторизація команд і mention gating дозволили повідомлення. -- Збагачуються лише безіменні телефонні учасники. -- Сирі номери телефонів залишаються резервним варіантом, якщо локальний збіг не знайдено. +- `channels.bluebubbles.enrichGroupParticipantsFromContacts = true` вмикає пошук. Типове значення: `false`. +- Пошук виконується лише після того, як доступ до групи, авторизація команди та обмеження згадування дозволили пропустити повідомлення. +- Збагачуються лише неіменовані телефонні учасники. +- Необроблені номери телефонів залишаються резервним варіантом, якщо локальний збіг не знайдено. ```json5 { @@ -193,15 +193,15 @@ Webhook груп BlueBubbles часто містять лише сирі адр } ``` -### Mention gating (групи) +### Обмеження за згадуванням (групи) -BlueBubbles підтримує mention gating для групових чатів, як і iMessage/WhatsApp: +BlueBubbles підтримує обмеження за згадуванням для групових чатів, як в iMessage/WhatsApp: -- Використовує `agents.list[].groupChat.mentionPatterns` (або `messages.groupChat.mentionPatterns`) для виявлення згадок. -- Коли для групи увімкнено `requireMention`, агент відповідає лише тоді, коли його згадано. -- Керувальні команди від авторизованих відправників обходять mention gating. +- Використовує `agents.list[].groupChat.mentionPatterns` (або `messages.groupChat.mentionPatterns`) для виявлення згадувань. +- Коли для групи ввімкнено `requireMention`, агент відповідає лише тоді, коли його згадано. +- Керівні команди від авторизованих відправників обходять це обмеження. -Конфігурація для окремих груп: +Налаштування для окремих груп: ```json5 { @@ -220,20 +220,68 @@ BlueBubbles підтримує mention gating для групових чатів ### Обмеження команд -- Керувальні команди (наприклад, `/config`, `/model`) вимагають авторизації. +- Керівні команди (наприклад, `/config`, `/model`) потребують авторизації. - Для визначення авторизації команд використовуються `allowFrom` і `groupAllowFrom`. -- Авторизовані відправники можуть виконувати керувальні команди навіть без згадки в групах. +- Авторизовані відправники можуть виконувати керівні команди навіть без згадування в групах. + +### Системний промпт для окремої групи + +Кожен запис у `channels.bluebubbles.groups.*` приймає необов’язковий рядок `systemPrompt`. Значення вбудовується в системний промпт агента на кожному ході, який обробляє повідомлення в цій групі, тож ви можете задавати образ або правила поведінки для окремих груп без редагування промптів агента: + +```json5 +{ + channels: { + bluebubbles: { + groups: { + "iMessage;-;chat123": { + systemPrompt: "Відповідай не більш ніж 3 реченнями. Відтворюй невимушений тон групи.", + }, + }, + }, + }, +} +``` + +Ключ збігається з тим, що BlueBubbles повідомляє як `chatGuid` / `chatIdentifier` / числовий `chatId` для групи, а запис-шаблон `"*"` задає типове значення для кожної групи без точного збігу (той самий шаблон використовується `requireMention` і політиками інструментів для окремих груп). Точні збіги завжди мають пріоритет над шаблоном. DM ігнорують це поле; замість цього використовуйте налаштування промптів на рівні агента або облікового запису. + +#### Практичний приклад: відповіді у тредах і реакції tapback (Private API) + +Коли ввімкнено BlueBubbles Private API, вхідні повідомлення надходять із короткими ідентифікаторами повідомлень (наприклад, `[[reply_to:5]]`), і агент може викликати `action=reply`, щоб відповісти на конкретне повідомлення в треді, або `action=react`, щоб поставити tapback. `systemPrompt` для окремої групи — надійний спосіб змусити агента вибирати правильний інструмент: + +```json5 +{ + channels: { + bluebubbles: { + groups: { + "iMessage;+;chat-family": { + systemPrompt: [ + "Під час відповіді в цій групі завжди викликай action=reply з", + "messageId `[[reply_to:N]]` із контексту, щоб твоя відповідь ішла", + "під повідомленням, яке її спричинило. Ніколи не надсилай нове непов’язане повідомлення.", + "", + "Для коротких підтверджень ('ок', 'отримав', 'зроблю') використовуй", + "action=react з відповідним tapback emoji (❤️, 👍, 😂, ‼️, ❓)", + "замість надсилання текстової відповіді.", + ].join(" "), + }, + }, + }, + }, +} +``` + +І tapback-реакції, і відповіді у тредах потребують BlueBubbles Private API; див. [Розширені дії](#advanced-actions) і [Ідентифікатори повідомлень](#message-ids-short-vs-full) щодо базової механіки. ## Прив’язки розмов ACP -Чати BlueBubbles можна перетворити на довготривалі робочі області ACP без зміни транспортного рівня. +Чати BlueBubbles можна перетворити на довготривалі робочі простори ACP без зміни транспортного рівня. -Швидкий операторський сценарій: +Швидкий робочий сценарій для операторів: - Виконайте `/acp spawn codex --bind here` у DM або дозволеному груповому чаті. -- Майбутні повідомлення в цій самій розмові BlueBubbles спрямовуватимуться до створеної сесії ACP. +- Подальші повідомлення в цій самій розмові BlueBubbles маршрутизуються до створеної сесії ACP. - `/new` і `/reset` скидають ту саму прив’язану сесію ACP на місці. -- `/acp close` закриває сесію ACP і видаляє прив’язку. +- `/acp close` закриває сесію ACP і прибирає прив’язку. Також підтримуються налаштовані постійні прив’язки через записи верхнього рівня `bindings[]` з `type: "acp"` і `match.channel: "bluebubbles"`. @@ -244,7 +292,7 @@ BlueBubbles підтримує mention gating для групових чатів - `chat_guid:` - `chat_identifier:` -Для стабільних прив’язок груп віддавайте перевагу `chat_id:*` або `chat_identifier:*`. +Для стабільних прив’язок груп надавайте перевагу `chat_id:*` або `chat_identifier:*`. Приклад: @@ -280,9 +328,9 @@ BlueBubbles підтримує mention gating для групових чатів ## Набір тексту + сповіщення про прочитання -- **Індикатори набору**: надсилаються автоматично перед і під час генерації відповіді. +- **Індикатори набору тексту**: надсилаються автоматично до та під час генерації відповіді. - **Сповіщення про прочитання**: керуються через `channels.bluebubbles.sendReadReceipts` (типово: `true`). -- **Індикатори набору**: OpenClaw надсилає події початку набору; BlueBubbles автоматично очищає стан набору після надсилання або тайм-ауту (ручна зупинка через DELETE ненадійна). +- **Індикатори набору тексту**: OpenClaw надсилає події початку набору; BlueBubbles автоматично очищає стан набору після надсилання або тайм-ауту (ручна зупинка через DELETE ненадійна). ```json5 { @@ -296,7 +344,7 @@ BlueBubbles підтримує mention gating для групових чатів ## Розширені дії -BlueBubbles підтримує розширені дії з повідомленнями, коли їх увімкнено в конфігурації: +BlueBubbles підтримує розширені дії з повідомленнями, якщо їх увімкнено в конфігурації: ```json5 { @@ -306,7 +354,7 @@ BlueBubbles підтримує розширені дії з повідомлен reactions: true, // tapback-реакції (типово: true) edit: true, // редагування надісланих повідомлень (macOS 13+, не працює на macOS 26 Tahoe) unsend: true, // скасування надсилання повідомлень (macOS 13+) - reply: true, // гілки відповідей за GUID повідомлення + reply: true, // відповіді у тредах за GUID повідомлення sendWithEffect: true, // ефекти повідомлень (slam, loud тощо) renameGroup: true, // перейменування групових чатів setGroupIcon: true, // встановлення значка/фото групового чату (нестабільно на macOS 26 Tahoe) @@ -322,39 +370,39 @@ BlueBubbles підтримує розширені дії з повідомлен Доступні дії: -- **react**: додавання/видалення tapback-реакцій (`messageId`, `emoji`, `remove`) -- **edit**: редагування надісланого повідомлення (`messageId`, `text`) -- **unsend**: скасування надсилання повідомлення (`messageId`) -- **reply**: відповідь на конкретне повідомлення (`messageId`, `text`, `to`) -- **sendWithEffect**: надсилання з ефектом iMessage (`text`, `to`, `effectId`) -- **renameGroup**: перейменування групового чату (`chatGuid`, `displayName`) -- **setGroupIcon**: встановлення значка/фото групового чату (`chatGuid`, `media`) — нестабільно на macOS 26 Tahoe (API може повертати успіх, але значок не синхронізується). -- **addParticipant**: додавання когось до групи (`chatGuid`, `address`) -- **removeParticipant**: видалення когось із групи (`chatGuid`, `address`) -- **leaveGroup**: вихід із групового чату (`chatGuid`) -- **upload-file**: надсилання медіа/файлів (`to`, `buffer`, `filename`, `asVoice`) - - Голосові повідомлення: встановіть `asVoice: true` з аудіо **MP3** або **CAF**, щоб надіслати його як голосове повідомлення iMessage. BlueBubbles перетворює MP3 → CAF під час надсилання голосових повідомлень. -- Застарілий псевдонім: `sendAttachment` усе ще працює, але `upload-file` є канонічною назвою дії. +- **react**: Додати/видалити tapback-реакції (`messageId`, `emoji`, `remove`) +- **edit**: Відредагувати надіслане повідомлення (`messageId`, `text`) +- **unsend**: Скасувати надсилання повідомлення (`messageId`) +- **reply**: Відповісти на конкретне повідомлення (`messageId`, `text`, `to`) +- **sendWithEffect**: Надіслати з ефектом iMessage (`text`, `to`, `effectId`) +- **renameGroup**: Перейменувати груповий чат (`chatGuid`, `displayName`) +- **setGroupIcon**: Встановити значок/фото групового чату (`chatGuid`, `media`) — нестабільно на macOS 26 Tahoe (API може повертати успіх, але значок не синхронізується). +- **addParticipant**: Додати когось до групи (`chatGuid`, `address`) +- **removeParticipant**: Видалити когось із групи (`chatGuid`, `address`) +- **leaveGroup**: Вийти з групового чату (`chatGuid`) +- **upload-file**: Надіслати медіа/файли (`to`, `buffer`, `filename`, `asVoice`) + - Голосові повідомлення: установіть `asVoice: true` з аудіо **MP3** або **CAF**, щоб надіслати його як голосове повідомлення iMessage. BlueBubbles перетворює MP3 → CAF під час надсилання голосових повідомлень. +- Застарілий псевдонім: `sendAttachment` усе ще працює, але `upload-file` — канонічна назва дії. -### ID повідомлень (короткі vs повні) +### Ідентифікатори повідомлень (короткі й повні) -OpenClaw може показувати _короткі_ ID повідомлень (наприклад, `1`, `2`) для економії токенів. +OpenClaw може показувати _короткі_ ідентифікатори повідомлень (наприклад, `1`, `2`) для економії токенів. -- `MessageSid` / `ReplyToId` можуть бути короткими ID. -- `MessageSidFull` / `ReplyToIdFull` містять повні ID провайдера. -- Короткі ID зберігаються в пам’яті; вони можуть зникати після перезапуску або витіснення кешу. -- Дії приймають короткий або повний `messageId`, але короткі ID повернуть помилку, якщо вони більше недоступні. +- `MessageSid` / `ReplyToId` можуть бути короткими ідентифікаторами. +- `MessageSidFull` / `ReplyToIdFull` містять повні ідентифікатори провайдера. +- Короткі ідентифікатори зберігаються в пам’яті; вони можуть зникнути після перезапуску або очищення кешу. +- Дії приймають короткий або повний `messageId`, але короткі ідентифікатори спричинять помилку, якщо вони більше недоступні. -Використовуйте повні ID для довготривалих автоматизацій і зберігання: +Використовуйте повні ідентифікатори для довготривалих автоматизацій і зберігання: - Шаблони: `{{MessageSidFull}}`, `{{ReplyToIdFull}}` -- Контекст: `MessageSidFull` / `ReplyToIdFull` у вхідному payload +- Контекст: `MessageSidFull` / `ReplyToIdFull` у вхідних payload -Див. [Конфігурація](/uk/gateway/configuration) щодо змінних шаблонів. +Див. [Configuration](/uk/gateway/configuration) щодо змінних шаблонів. ## Блокове потокове передавання -Керуйте тим, чи відповіді надсилатимуться як одне повідомлення, чи потоково блоками: +Керуйте тим, чи надсилаються відповіді як одне повідомлення, чи потоково блоками: ```json5 { @@ -366,38 +414,38 @@ OpenClaw може показувати _короткі_ ID повідомлен } ``` -## Медіа + ліміти +## Медіа + обмеження - Вхідні вкладення завантажуються та зберігаються в кеші медіа. -- Ліміт медіа задається через `channels.bluebubbles.mediaMaxMb` для вхідних і вихідних медіа (типово: 8 MB). -- Вихідний текст розбивається на фрагменти відповідно до `channels.bluebubbles.textChunkLimit` (типово: 4000 символів). +- Обмеження медіа через `channels.bluebubbles.mediaMaxMb` для вхідних і вихідних медіа (типово: 8 MB). +- Вихідний текст ділиться на частини відповідно до `channels.bluebubbles.textChunkLimit` (типово: 4000 символів). -## Довідник з конфігурації +## Довідник із конфігурації -Повна конфігурація: [Конфігурація](/uk/gateway/configuration) +Повна конфігурація: [Configuration](/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`: Шлях кінцевої точки Webhook (типово: `/bluebubbles-webhook`). - `channels.bluebubbles.dmPolicy`: `pairing | allowlist | open | disabled` (типово: `pairing`). -- `channels.bluebubbles.allowFrom`: Список дозволених для DM (ідентифікатори, email-адреси, номери E.164, `chat_id:*`, `chat_guid:*`). +- `channels.bluebubbles.allowFrom`: allowlist для DM (дескриптори, електронні адреси, номери E.164, `chat_id:*`, `chat_guid:*`). - `channels.bluebubbles.groupPolicy`: `open | allowlist | disabled` (типово: `allowlist`). -- `channels.bluebubbles.groupAllowFrom`: Список дозволених відправників для груп. -- `channels.bluebubbles.enrichGroupParticipantsFromContacts`: На macOS необов’язково збагачує безіменних учасників групи з локальних Contacts після проходження перевірок. Типово: `false`. +- `channels.bluebubbles.groupAllowFrom`: allowlist відправників для груп. +- `channels.bluebubbles.enrichGroupParticipantsFromContacts`: У macOS необов’язково збагачує неіменованих учасників групи з локальних Contacts після проходження обмежень. Типове значення: `false`. - `channels.bluebubbles.groups`: Конфігурація для окремих груп (`requireMention` тощо). - `channels.bluebubbles.sendReadReceipts`: Надсилати сповіщення про прочитання (типово: `true`). -- `channels.bluebubbles.blockStreaming`: Увімкнути блокове потокове передавання (типово: `false`; потрібне для потокових відповідей). +- `channels.bluebubbles.blockStreaming`: Увімкнути блокове потокове передавання (типово: `false`; обов’язково для потокових відповідей). - `channels.bluebubbles.textChunkLimit`: Розмір вихідного фрагмента в символах (типово: 4000). -- `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`: Ліміт вхідних/вихідних медіа в MB (типово: 8). -- `channels.bluebubbles.mediaLocalRoots`: Явний список дозволених абсолютних локальних директорій для вихідних шляхів до локальних медіа. Надсилання локальних шляхів типово заборонене, якщо це не налаштовано. Перевизначення для окремого облікового запису: `channels.bluebubbles.accounts..mediaLocalRoots`. -- `channels.bluebubbles.historyLimit`: Максимальна кількість групових повідомлень для контексту (0 вимикає). -- `channels.bluebubbles.dmHistoryLimit`: Ліміт історії DM. -- `channels.bluebubbles.actions`: Увімкнути/вимкнути окремі дії. +- `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`: Обмеження вхідних/вихідних медіа в MB (типово: 8). +- `channels.bluebubbles.mediaLocalRoots`: Явний allowlist абсолютних локальних каталогів, дозволених для вихідних локальних шляхів до медіа. Надсилання локальних шляхів типово заборонено, якщо це не налаштовано. Перевизначення для окремого облікового запису: `channels.bluebubbles.accounts..mediaLocalRoots`. +- `channels.bluebubbles.historyLimit`: Максимум групових повідомлень для контексту (0 вимикає). +- `channels.bluebubbles.dmHistoryLimit`: Обмеження історії DM. +- `channels.bluebubbles.actions`: Увімкнення/вимкнення окремих дій. - `channels.bluebubbles.accounts`: Конфігурація кількох облікових записів. Пов’язані глобальні параметри: @@ -409,35 +457,35 @@ OpenClaw може показувати _короткі_ ID повідомлен Для стабільної маршрутизації надавайте перевагу `chat_guid`: -- `chat_guid:iMessage;-;+15555550123` (переважно для груп) +- `chat_guid:iMessage;-;+15555550123` (рекомендовано для груп) - `chat_id:123` - `chat_identifier:...` -- Прямі ідентифікатори: `+15555550123`, `user@example.com` - - Якщо для прямого ідентифікатора немає наявного DM-чату, OpenClaw створить його через `POST /api/v1/chat/new`. Для цього потрібно, щоб у BlueBubbles було ввімкнено Private API. +- Прямі дескриптори: `+15555550123`, `user@example.com` + - Якщо для прямого дескриптора немає наявного чату DM, OpenClaw створить його через `POST /api/v1/chat/new`. Для цього потрібно, щоб був увімкнений BlueBubbles Private API. ## Безпека - Запити Webhook автентифікуються шляхом порівняння параметрів запиту `guid`/`password` або заголовків із `channels.bluebubbles.password`. -- Зберігайте пароль API і endpoint Webhook у таємниці (ставтеся до них як до облікових даних). -- Для автентифікації Webhook BlueBubbles немає обходу через localhost. Якщо ви проксіюєте трафік Webhook, зберігайте пароль BlueBubbles у запиті наскрізно. `gateway.trustedProxies` тут не замінює `channels.bluebubbles.password`. Див. [Безпека Gateway](/uk/gateway/security#reverse-proxy-configuration). -- Увімкніть HTTPS і правила фаєрвола на сервері BlueBubbles, якщо відкриваєте його поза межами вашої LAN. +- Зберігайте пароль API та кінцеву точку Webhook у таємниці (ставтеся до них як до облікових даних). +- Для автентифікації Webhook BlueBubbles немає обходу localhost. Якщо ви проксіюєте трафік Webhook, зберігайте пароль BlueBubbles у запиті наскрізно. `gateway.trustedProxies` тут не замінює `channels.bluebubbles.password`. Див. [Безпека Gateway](/uk/gateway/security#reverse-proxy-configuration). +- Якщо сервер BlueBubbles доступний за межами вашої LAN, увімкніть HTTPS + правила брандмауера. ## Усунення проблем -- Якщо події набору/прочитання перестали працювати, перевірте журнали Webhook BlueBubbles і переконайтеся, що шлях Gateway збігається з `channels.bluebubbles.webhookPath`. +- Якщо події набору тексту/прочитання перестали працювати, перевірте журнали Webhook BlueBubbles і переконайтеся, що шлях Gateway відповідає `channels.bluebubbles.webhookPath`. - Коди сполучення спливають через одну годину; використовуйте `openclaw pairing list bluebubbles` і `openclaw pairing approve bluebubbles `. -- Для реакцій потрібен BlueBubbles private API (`POST /api/v1/message/react`); переконайтеся, що версія сервера його надає. -- Для редагування/скасування надсилання потрібні macOS 13+ і сумісна версія сервера BlueBubbles. На macOS 26 (Tahoe) редагування наразі не працює через зміни в private API. +- Реакції потребують BlueBubbles private API (`POST /api/v1/message/react`); переконайтеся, що версія сервера його надає. +- Редагування/скасування надсилання потребують macOS 13+ і сумісної версії сервера BlueBubbles. На macOS 26 (Tahoe) редагування наразі не працює через зміни private API. - Оновлення значка групи можуть бути нестабільними на macOS 26 (Tahoe): API може повертати успіх, але новий значок не синхронізується. -- OpenClaw автоматично приховує відомі непрацюючі дії на основі версії macOS сервера BlueBubbles. Якщо редагування все ще відображається на macOS 26 (Tahoe), вимкніть його вручну через `channels.bluebubbles.actions.edit=false`. -- Для перегляду інформації про статус/стан: `openclaw status --all` або `openclaw status --deep`. +- OpenClaw автоматично приховує відомі несправні дії на основі версії macOS сервера BlueBubbles. Якщо редагування все ще відображається на macOS 26 (Tahoe), вимкніть його вручну через `channels.bluebubbles.actions.edit=false`. +- Для інформації про стан/працездатність: `openclaw status --all` або `openclaw status --deep`. -Загальний довідник щодо роботи каналів див. у [Channels](/uk/channels) і в посібнику [Plugins](/uk/tools/plugin). +Загальний довідник щодо робочих процесів каналів див. у [Channels](/uk/channels) і в посібнику [Plugins](/uk/tools/plugin). ## Пов’язане -- [Огляд Channels](/uk/channels) — усі підтримувані канали +- [Огляд каналів](/uk/channels) — усі підтримувані канали - [Сполучення](/uk/channels/pairing) — автентифікація DM і процес сполучення -- [Групи](/uk/channels/groups) — поведінка групових чатів і mention gating +- [Групи](/uk/channels/groups) — поведінка групових чатів і обмеження за згадуванням - [Маршрутизація каналів](/uk/channels/channel-routing) — маршрутизація сесій для повідомлень - [Безпека](/uk/gateway/security) — модель доступу та посилення захисту