chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
2788967898
commit
40a108887b
@ -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.
|
||||
|
||||
<Note>
|
||||
Поточні випуски OpenClaw вбудовують BlueBubbles, тому звичайні пакетовані збірки не потребують окремого кроку `openclaw plugins install`.
|
||||
Поточні випуски OpenClaw постачають BlueBubbles у комплекті, тому звичайні пакетовані збірки не потребують окремого кроку `openclaw plugins install`.
|
||||
</Note>
|
||||
|
||||
## Огляд
|
||||
|
||||
- Працює на 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 могли "згадати" їх перед відповіддю.
|
||||
- Розширені можливості: редагування, скасування надсилання, гілки відповідей, ефекти повідомлень, керування групами.
|
||||
|
||||
## Швидкий старт
|
||||
|
||||
<Steps>
|
||||
<Step title="Установіть BlueBubbles">
|
||||
Установіть сервер BlueBubbles на свій Mac (дотримуйтесь інструкцій на [bluebubbles.app/install](https://bluebubbles.app/install)).
|
||||
<Step title="Install BlueBubbles">
|
||||
Установіть сервер BlueBubbles на ваш Mac (дотримуйтесь інструкцій на [bluebubbles.app/install](https://bluebubbles.app/install)).
|
||||
</Step>
|
||||
<Step title="Увімкніть web API">
|
||||
У конфігурації BlueBubbles увімкніть web API і задайте пароль.
|
||||
<Step title="Enable the web API">
|
||||
У конфігурації BlueBubbles увімкніть web API та встановіть пароль.
|
||||
</Step>
|
||||
<Step title="Налаштуйте OpenClaw">
|
||||
<Step title="Configure OpenClaw">
|
||||
Запустіть `openclaw onboard` і виберіть BlueBubbles або налаштуйте вручну:
|
||||
|
||||
```json5
|
||||
@ -59,29 +59,29 @@ x-i18n:
|
||||
```
|
||||
|
||||
</Step>
|
||||
<Step title="Спрямуйте вебхуки на Gateway">
|
||||
Спрямуйте вебхуки BlueBubbles на свій Gateway (приклад: `https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`).
|
||||
<Step title="Point webhooks at the gateway">
|
||||
Спрямуйте webhooks BlueBubbles на ваш gateway (приклад: `https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`).
|
||||
</Step>
|
||||
<Step title="Запустіть Gateway">
|
||||
Запустіть Gateway; він зареєструє обробник вебхука й почне сполучення.
|
||||
<Step title="Start the gateway">
|
||||
Запустіть gateway; він зареєструє обробник webhook і почне сполучення.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Warning>
|
||||
**Безпека**
|
||||
|
||||
- Завжди задавайте пароль вебхука.
|
||||
- Автентифікація Webhook завжди обов'язкова. OpenClaw відхиляє запити Webhook BlueBubbles, якщо вони не містять password/guid, що збігається з `channels.bluebubbles.password` (наприклад `?password=<password>` або `x-password`), незалежно від топології loopback/proxy.
|
||||
- Автентифікація паролем перевіряється перед читанням/розбором повних тіл вебхуків.
|
||||
- Завжди встановлюйте пароль webhook.
|
||||
- Автентифікація webhook завжди обов’язкова. OpenClaw відхиляє webhook-запити BlueBubbles, якщо вони не містять пароль/guid, що відповідає `channels.bluebubbles.password` (наприклад, `?password=<password>` або `x-password`), незалежно від топології loopback/proxy.
|
||||
- Автентифікація паролем перевіряється перед читанням/розбором повних тіл webhook.
|
||||
|
||||
</Warning>
|
||||
|
||||
## Підтримання Messages.app активним (VM / headless-налаштування)
|
||||
|
||||
У деяких macOS VM / постійно ввімкнених налаштуваннях Messages.app може переходити в "idle" (вхідні події зупиняються, доки застосунок не відкриють або не виведуть на передній план). Простий обхідний шлях — **штовхати Messages кожні 5 хвилин** за допомогою AppleScript + LaunchAgent.
|
||||
У деяких VM macOS / постійно ввімкнених налаштуваннях Messages.app може переходити в стан "idle" (вхідні події зупиняються, доки застосунок не відкриють або не виведуть на передній план). Простий обхідний шлях — **підштовхувати Messages кожні 5 хвилин** за допомогою AppleScript + LaunchAgent.
|
||||
|
||||
<Steps>
|
||||
<Step title="Збережіть AppleScript">
|
||||
<Step title="Save the AppleScript">
|
||||
Збережіть це як `~/Scripts/poke-messages.scpt`:
|
||||
|
||||
```applescript
|
||||
@ -100,7 +100,7 @@ x-i18n:
|
||||
```
|
||||
|
||||
</Step>
|
||||
<Step title="Установіть LaunchAgent">
|
||||
<Step title="Install a LaunchAgent">
|
||||
Збережіть це як `~/Library/LaunchAgents/com.user.poke-messages.plist`:
|
||||
|
||||
```xml
|
||||
@ -132,10 +132,10 @@ x-i18n:
|
||||
</plist>
|
||||
```
|
||||
|
||||
Це запускається **кожні 300 секунд** і **під час входу в систему**. Перший запуск може викликати запити **Automation** у macOS (`osascript` → Messages). Підтвердьте їх у тому самому сеансі користувача, у якому працює LaunchAgent.
|
||||
Це запускається **кожні 300 секунд** і **під час входу в систему**. Перший запуск може спричинити запити macOS **Automation** (`osascript` → Messages). Схваліть їх у тому самому сеансі користувача, у якому працює LaunchAgent.
|
||||
|
||||
</Step>
|
||||
<Step title="Завантажте його">
|
||||
<Step title="Load it">
|
||||
```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.
|
||||
</ParamField>
|
||||
<ParamField path="Webhook path" type="string" default="/bluebubbles-webhook">
|
||||
Шлях кінцевої точки Webhook.
|
||||
Шлях кінцевої точки webhook.
|
||||
</ParamField>
|
||||
<ParamField path="DM policy" type="string">
|
||||
`pairing`, `allowlist`, `open` або `disabled`.
|
||||
</ParamField>
|
||||
<ParamField path="Allow list" type="string[]">
|
||||
Номери телефонів, електронні адреси або цілі чатів.
|
||||
Номери телефонів, електронні адреси або цілі чату.
|
||||
</ParamField>
|
||||
|
||||
Ви також можете додати BlueBubbles через CLI:
|
||||
@ -178,30 +178,30 @@ openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --passwor
|
||||
## Контроль доступу (DM + групи)
|
||||
|
||||
<Tabs>
|
||||
<Tab title="DM">
|
||||
- Типово: `channels.bluebubbles.dmPolicy = "pairing"`.
|
||||
- Невідомі відправники отримують код сполучення; повідомлення ігноруються, доки їх не схвалять (коди спливають через 1 годину).
|
||||
- Схвалення через:
|
||||
<Tab title="DMs">
|
||||
- За замовчуванням: `channels.bluebubbles.dmPolicy = "pairing"`.
|
||||
- Невідомі відправники отримують код сполучення; повідомлення ігноруються, доки їх не буде схвалено (коди спливають через 1 годину).
|
||||
- Схвалити через:
|
||||
- `openclaw pairing list bluebubbles`
|
||||
- `openclaw pairing approve bluebubbles <CODE>`
|
||||
- Сполучення — це типовий обмін токенами. Докладніше: [Сполучення](/uk/channels/pairing)
|
||||
- Сполучення є типовим обміном токенами. Докладніше: [Сполучення](/uk/channels/pairing)
|
||||
|
||||
</Tab>
|
||||
<Tab title="Групи">
|
||||
- `channels.bluebubbles.groupPolicy = open | allowlist | disabled` (типово: `allowlist`).
|
||||
- `channels.bluebubbles.groupAllowFrom` керує тим, хто може запускати в групах, коли встановлено `allowlist`.
|
||||
<Tab title="Groups">
|
||||
- `channels.bluebubbles.groupPolicy = open | allowlist | disabled` (за замовчуванням: `allowlist`).
|
||||
- `channels.bluebubbles.groupAllowFrom` контролює, хто може запускати agent у групах, коли встановлено `allowlist`.
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### Збагачення імен контактів (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:<id>`
|
||||
- `chat_guid:<guid>`
|
||||
- `chat_identifier:<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 підтримує розширені дії з повідомлен
|
||||
```
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Available actions">
|
||||
- **react**: додати/видалити реакції tapback (`messageId`, `emoji`, `remove`). Вбудований набір tapback в iMessage: `love`, `like`, `dislike`, `laugh`, `emphasize` і `question`. Коли агент вибирає emoji поза цим набором (наприклад, `👀`), інструмент реакцій повертається до `love`, щоб tapback усе одно відобразився замість збою всього запиту. Налаштовані реакції підтвердження все ще перевіряються суворо й повертають помилку для невідомих значень.
|
||||
<Accordion title="Доступні дії">
|
||||
- **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` є канонічною назвою дії.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### Ідентифікатори повідомлень (короткі та повні)
|
||||
### 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 може показувати _короткі_ ідентифікато
|
||||
|
||||
<a id="coalescing-split-send-dms-command--url-in-one-composition"></a>
|
||||
|
||||
## Об'єднання 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 від того самого відправника в один хід агента. Групові чати й далі прив’язуються до окремих повідомлень, щоб зберегти структуру ходів кількох користувачів.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="When to enable">
|
||||
<Tab title="Коли вмикати">
|
||||
Увімкніть, коли:
|
||||
|
||||
- Ви постачаєте skills, які очікують `command + payload` в одному повідомленні (dump, paste, save, queue тощо).
|
||||
- Ви постачаєте Skills, які очікують `command + payload` в одному повідомленні (dump, paste, save, queue тощо).
|
||||
- Ваші користувачі вставляють URL, зображення або довгий вміст разом із командами.
|
||||
- Ви можете прийняти додаткову затримку ходу DM (див. нижче).
|
||||
|
||||
Залиште вимкненим, коли:
|
||||
|
||||
- Вам потрібна мінімальна затримка команди для однослівних тригерів DM.
|
||||
- Усі ваші потоки — одноразові команди без подальших payload.
|
||||
- Вам потрібна мінімальна затримка команд для однословних тригерів DM.
|
||||
- Усі ваші потоки є одноразовими командами без наступних payload.
|
||||
|
||||
</Tab>
|
||||
<Tab title="Enabling">
|
||||
<Tab title="Увімкнення">
|
||||
```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 може показувати _короткі_ ідентифікато
|
||||
```
|
||||
|
||||
</Tab>
|
||||
<Tab title="Trade-offs">
|
||||
- **Додаткова затримка для керівних команд DM.** Коли прапорець увімкнено, повідомлення керівних команд DM (як-от `Dump`, `Save` тощо) тепер очікують до кінця вікна debounce перед відправленням на обробку, на випадок якщо надходить webhook із payload. Команди в групових чатах зберігають миттєве відправлення.
|
||||
- **Об'єднаний вивід обмежений** — об'єднаний текст обмежується 4000 символами з явним маркером `…[truncated]`; вкладення — 20; записи джерел — 10 (понад це зберігаються перший і найновіший). Кожен вихідний `messageId` усе ще потрапляє до дедуплікації вхідних повідомлень, тому пізніший повтор будь-якої окремої події MessagePoller розпізнається як дублікат.
|
||||
- **Увімкнення окремо для каналу.** Інші канали (Telegram, WhatsApp, Slack, …) не зачіпаються.
|
||||
<Tab title="Компроміси">
|
||||
- **Додана затримка для керівних команд DM.** Коли прапорець увімкнено, повідомлення керівних команд DM (наприклад `Dump`, `Save` тощо) тепер чекають до завершення debounce-вікна перед dispatch, на випадок якщо надходить Webhook із payload. Команди групового чату зберігають миттєвий dispatch.
|
||||
- **Об’єднаний вивід обмежений** — об’єднаний текст обмежується 4000 символами з явним маркером `…[truncated]`; вкладення обмежуються 20; записи джерел обмежуються 10 (понад це зберігаються перший і найновіший). Кожен вихідний `messageId` усе одно доходить до inbound-dedupe, тож пізніший replay MessagePoller будь-якої окремої події розпізнається як дублікат.
|
||||
- **Opt-in, для окремого каналу.** Інші канали (Telegram, WhatsApp, Slack, …) не зачіпаються.
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### Сценарії та що бачить агент
|
||||
### Сценарії й те, що бачить агент
|
||||
|
||||
| Користувач складає повідомлення | 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 і далі надходять як два ходи, перевірте кожен рівень:
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Config actually loaded">
|
||||
<Accordion title="Конфігурацію справді завантажено">
|
||||
```
|
||||
grep coalesceSameSenderDms ~/.openclaw/openclaw.json
|
||||
```
|
||||
|
||||
Потім `openclaw gateway restart` — прапорець читається під час створення реєстру debouncer.
|
||||
Потім `openclaw gateway restart` — прапорець зчитується під час створення debouncer-registry.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Debounce window wide enough for your setup">
|
||||
<Accordion title="Debounce-вікно достатньо широке для вашого налаштування">
|
||||
Перегляньте журнал сервера 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`, щоб із запасом покрити цей проміжок.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Session JSONL timestamps ≠ webhook arrival">
|
||||
Мітки часу подій сеансу (`~/.openclaw/agents/<id>/sessions/*.jsonl`) відображають момент, коли Gateway передає повідомлення агенту, **а не** момент надходження webhook. Друге повідомлення в черзі з позначкою `[Queued messages while agent was busy]` означає, що перший хід усе ще виконувався, коли надійшов другий webhook — bucket об'єднання вже було скинуто. Налаштовуйте вікно за журналом сервера BB, а не за журналом сеансу.
|
||||
<Accordion title="Позначки часу Session JSONL ≠ надходження Webhook">
|
||||
Позначки часу подій сеансу (`~/.openclaw/agents/<id>/sessions/*.jsonl`) відображають момент, коли Gateway передає повідомлення агенту, **а не** момент надходження Webhook. Друге повідомлення в черзі, позначене `[Queued messages while agent was busy]`, означає, що перший хід усе ще виконувався, коли надійшов другий Webhook — bucket об’єднання вже було скинуто. Налаштовуйте вікно за журналом сервера BB, а не за журналом сеансу.
|
||||
</Accordion>
|
||||
<Accordion title="Memory pressure slowing reply dispatch">
|
||||
На менших машинах (8 ГБ) ходи агента можуть тривати достатньо довго, щоб bucket об'єднання скинувся до завершення відповіді, і URL потрапив як другий хід у черзі. Перевірте `memory_pressure` і `ps -o rss -p $(pgrep openclaw-gateway)`; якщо Gateway має понад ~500 МБ RSS і компресор активний, закрийте інші важкі процеси або перейдіть на більший хост.
|
||||
<Accordion title="Тиск пам’яті сповільнює dispatch відповіді">
|
||||
На менших машинах (8 ГБ) ходи агента можуть тривати достатньо довго, щоб bucket об’єднання скинувся до завершення відповіді, і URL потрапив як другий хід у черзі. Перевірте `memory_pressure` і `ps -o rss -p $(pgrep openclaw-gateway)`; якщо Gateway використовує понад ~500 МБ RSS і compressor активний, закрийте інші важкі процеси або перейдіть на більший хост.
|
||||
</Accordion>
|
||||
<Accordion title="Reply-quote sends are a different path">
|
||||
Якщо користувач натиснув `Dump` як **відповідь** на наявну URL-бульбашку (iMessage показує бейдж "1 Reply" на бульбашці Dump), URL міститься в `replyToBody`, а не в другому webhook. Об'єднання не застосовується — це питання skill/промпта, а не debouncer.
|
||||
<Accordion title="Надсилання reply-quote йдуть іншим шляхом">
|
||||
Якщо користувач натиснув `Dump` як **відповідь** на наявну URL-бульбашку (iMessage показує бейдж "1 Reply" на бульбашці Dump), URL міститься в `replyToBody`, а не в другому Webhook. Об’єднання не застосовується — це питання skill/prompt, а не debouncer.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Блокове потокове передавання
|
||||
|
||||
Керуйте тим, чи відповіді надсилаються як одне повідомлення, чи потоково блоками:
|
||||
Керує тим, чи відповіді надсилаються як одне повідомлення, чи потоково блоками:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -551,47 +551,48 @@ OpenClaw може показувати _короткі_ ідентифікато
|
||||
|
||||
- Вхідні вкладення завантажуються та зберігаються в кеші медіа.
|
||||
- Обмеження медіа через `channels.bluebubbles.mediaMaxMb` для вхідних і вихідних медіа (типово: 8 МБ).
|
||||
- Вихідний текст розбивається на фрагменти за `channels.bluebubbles.textChunkLimit` (типово: 4000 символів).
|
||||
- Вихідний текст розбивається на частини за `channels.bluebubbles.textChunkLimit` (типово: 4000 символів).
|
||||
|
||||
## Довідник конфігурації
|
||||
|
||||
Повна конфігурація: [Конфігурація](/uk/gateway/configuration)
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Connection and webhook">
|
||||
<Accordion title="Підключення та Webhook">
|
||||
- `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`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Access policy">
|
||||
<Accordion title="Політика доступу">
|
||||
- `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` тощо).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Доставка та фрагментація">
|
||||
- `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.<accountId>.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.<accountId>.sendTimeoutMs`.
|
||||
- `channels.bluebubbles.chunkMode`: `length` (типово) розбиває лише за перевищення `textChunkLimit`; `newline` розбиває за порожніми рядками (межами абзаців) перед розбиттям за довжиною.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Медіа та історія">
|
||||
- `channels.bluebubbles.mediaMaxMb`: Обмеження вхідних/вихідних медіа в МБ (типово: 8).
|
||||
- `channels.bluebubbles.mediaLocalRoots`: Явний список дозволених абсолютних локальних каталогів, дозволених для вихідних локальних шляхів до медіа. Надсилання локальних шляхів типово заборонено, якщо це не налаштовано. Перевизначення для окремого облікового запису: `channels.bluebubbles.accounts.<accountId>.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.<accountId>.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.<accountId>.replyContextApiFallback`. Налаштування рівня каналу поширюється на облікові записи, які пропускають цей прапорець.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Дії та облікові записи">
|
||||
- `channels.bluebubbles.actions`: Увімкнути/вимкнути певні дії.
|
||||
- `channels.bluebubbles.actions`: Увімкнути/вимкнути конкретні дії.
|
||||
- `channels.bluebubbles.accounts`: Конфігурація кількох облікових записів.
|
||||
|
||||
</Accordion>
|
||||
@ -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 <code>`.
|
||||
- Для реакцій потрібен приватний 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) — модель доступу та посилення захисту
|
||||
|
||||
Loading…
Reference in New Issue
Block a user