BlueBubbles

Статус: вбудований застарілий plugin, який спілкується із сервером BlueBubbles для macOS через HTTP. Наявні налаштування BlueBubbles продовжують працювати, але для нових розгортань OpenClaw iMessage варто віддавати перевагу нативному plugin iMessage, коли його вимоги підходять для вашого хоста.

# Огляд

• Працює на macOS через допоміжний застосунок BlueBubbles (bluebubbles.app).
• Застарілий резервний варіант для інсталяцій, які вже покладаються на ідентифікатори каналів BlueBubbles, стан webhook, цілі груп, доставку cron або маршрутизацію робочих просторів.
• Рекомендовано/протестовано: macOS Sequoia (15). macOS Tahoe (26) працює; редагування наразі зламане на Tahoe, а оновлення піктограм груп можуть повідомляти про успіх, але не синхронізуватися.
• OpenClaw спілкується з ним через його REST API (GET /api/v1/ping, POST /message/text, POST /chat/:id/*).
• Вхідні повідомлення надходять через webhooks; вихідні відповіді, індикатори набору, сповіщення про прочитання й tapbacks є REST-викликами.
• Вкладення та стікери приймаються як вхідні медіа (і за можливості показуються агенту).
• Автоматичні TTS-відповіді, які синтезують аудіо MP3 або CAF, доставляються як бульбашки голосових нотаток iMessage, а не як звичайні файлові вкладення.
• Парування/список дозволених працює так само, як для інших каналів (/channels/pairing тощо), з channels.bluebubbles.allowFrom + кодами парування.
• Реакції відображаються як системні події, так само як у Slack/Telegram, щоб агенти могли «згадати» їх перед відповіддю.
• Розширені можливості: редагування, скасування надсилання, гілки відповідей, ефекти повідомлень, керування групами.

# Швидкий старт

{
  channels: {
    bluebubbles: {
      enabled: true,
      serverUrl: "http://192.168.1.100:1234",
      password: "example-password",
      webhookPath: "/bluebubbles-webhook",
    },
  },
}

# Підтримання Messages.app активним (VM / безголові налаштування)

Деякі налаштування macOS VM / always-on можуть призводити до того, що Messages.app переходить у стан «idle» (вхідні події зупиняються, доки застосунок не відкриють/не виведуть на передній план). Простий обхідний шлях — підштовхувати Messages кожні 5 хвилин за допомогою AppleScript + LaunchAgent.

try
  tell application "Messages"
    if not running then
      launch
    end if

    -- Touch the scripting interface to keep the process responsive.
    set _chatCount to (count of chats)
  end tell
on error
  -- Ignore transient failures (first-run prompts, locked session, etc).
end try

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>Label</key>
    <string>com.user.poke-messages</string>

    <key>ProgramArguments</key>
    <array>
      <string>/bin/bash</string>
      <string>-lc</string>
      <string>/usr/bin/osascript &quot;$HOME/Scripts/poke-messages.scpt&quot;</string>
    </array>

    <key>RunAtLoad</key>
    <true/>

    <key>StartInterval</key>
    <integer>300</integer>

    <key>StandardOutPath</key>
    <string>/tmp/poke-messages.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/poke-messages.err</string>
  </dict>
</plist>

launchctl unload ~/Library/LaunchAgents/com.user.poke-messages.plist 2>/dev/null || true
launchctl load ~/Library/LaunchAgents/com.user.poke-messages.plist

# Початкове налаштування

BlueBubbles доступний в інтерактивному початковому налаштуванні:

openclaw onboard

Майстер запитує:

Також можна додати BlueBubbles через CLI:

openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --password <password>

# Контроль доступу (DM + групи)

# Збагачення імен контактів (macOS, необов’язково)

Групові webhooks BlueBubbles часто містять лише сирі адреси учасників. Якщо ви хочете, щоб контекст GroupMembers натомість показував локальні імена контактів, можна увімкнути локальне збагачення з Contacts на macOS:

• channels.bluebubbles.enrichGroupParticipantsFromContacts = true вмикає пошук. За замовчуванням: false.
• Пошуки виконуються лише після того, як груповий доступ, авторизація команд і фільтрація згадок дозволили повідомлення.
• Збагачуються лише учасники з телефонними номерами без імен.
• Сирі номери телефонів залишаються резервним варіантом, коли локальний збіг не знайдено.

{
  channels: {
    bluebubbles: {
      enrichGroupParticipantsFromContacts: true,
    },
  },
}

# Фільтрація згадок (групи)

BlueBubbles підтримує фільтрацію згадок для групових чатів, відповідно до поведінки iMessage/WhatsApp:

• Використовує agents.list[].groupChat.mentionPatterns (або messages.groupChat.mentionPatterns) для виявлення згадок.
• Коли requireMention увімкнено для групи, агент відповідає лише тоді, коли його згадано.
• Команди керування від авторизованих відправників обходять фільтрацію згадок.

Конфігурація для окремої групи:

{
  channels: {
    bluebubbles: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: {
        "*": { requireMention: true }, // default for all groups
        "iMessage;-;chat123": { requireMention: false }, // override for specific group
      },
    },
  },
}

# Фільтрація команд

• Команди керування (наприклад, /config, /model) потребують авторизації.
• Використовує allowFrom і groupAllowFrom, щоб визначити авторизацію команд.
• Авторизовані відправники можуть запускати команди керування навіть без згадки в групах.

# Системна підказка для окремої групи

Кожен запис у channels.bluebubbles.groups.* приймає необов’язковий рядок systemPrompt. Значення вставляється в системну підказку агента на кожному ході, який обробляє повідомлення в цій групі, тож можна задавати персоналію або поведінкові правила для окремої групи без редагування підказок агента:

{
  channels: {
    bluebubbles: {
      groups: {
        "iMessage;-;chat123": {
          systemPrompt: "Keep responses under 3 sentences. Mirror the group's casual tone.",
        },
      },
    },
  },
}

Ключ відповідає тому, що BlueBubbles повідомляє як chatGuid / chatIdentifier / числовий chatId для групи, а запис із wildcard "*" надає значення за замовчуванням для кожної групи без точного збігу (той самий шаблон використовується requireMention і політиками інструментів для окремих груп). Точні збіги завжди мають перевагу над wildcard. DM ігнорують це поле; натомість використовуйте налаштування підказок на рівні агента або облікового запису.

# Робочий приклад: гілкові відповіді та реакції tapback (приватний API)

Коли приватний API BlueBubbles увімкнено, вхідні повідомлення надходять із короткими ідентифікаторами повідомлень (наприклад, [[reply_to:5]]), і агент може викликати action=reply, щоб відповісти в гілці конкретного повідомлення, або action=react, щоб додати tapback. systemPrompt для окремої групи — надійний спосіб утримати агента у виборі правильного інструмента:

{
  channels: {
    bluebubbles: {
      groups: {
        "iMessage;+;chat-family": {
          systemPrompt: "When replying in this group, always call action=reply with the [[reply_to:N]] messageId from context so your response threads under the triggering message. Never send a new unlinked message. For short acknowledgements ('ok', 'got it', 'on it'), use action=react with an appropriate tapback emoji (❤️, 👍, 😂, ‼️, ❓) instead of sending a text reply.",
        },
      },
    },
  },
}

Реакції tapback і гілкові відповіді обидві потребують приватного API BlueBubbles; див. Розширені дії і Ідентифікатори повідомлень щодо базової механіки.

# Прив’язки розмов ACP

Чати BlueBubbles можна перетворити на довговічні робочі простори ACP без зміни транспортного рівня.

Швидкий потік оператора:

• Запустіть /acp spawn codex --bind here у DM або дозволеному груповому чаті.
• Майбутні повідомлення в тій самій розмові BlueBubbles маршрутизуються до породженої сесії ACP.
• /new і /reset скидають ту саму прив’язану сесію ACP на місці.
• /acp close закриває сесію ACP і видаляє прив’язку.

Налаштовані сталі прив’язки також підтримуються через записи верхнього рівня bindings[] з type: "acp" і match.channel: "bluebubbles".

match.peer.id може використовувати будь-яку підтримувану форму цілі BlueBubbles:

• нормалізований DM-ідентифікатор, як-от +15555550123 або [email protected]
• chat_id:<id>
• chat_guid:<guid>
• chat_identifier:<identifier>

Для стабільних прив’язок груп надавайте перевагу chat_id:* або chat_identifier:*.

Приклад:

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: { agent: "codex", backend: "acpx", mode: "persistent" },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "bluebubbles",
        accountId: "default",
        peer: { kind: "dm", id: "+15555550123" },
      },
      acp: { label: "codex-imessage" },
    },
  ],
}

Див. ACP Agents щодо спільної поведінки прив’язок ACP.

# Індикатори набору + сповіщення про прочитання

• Індикатори набору: надсилаються автоматично до та під час генерації відповіді.
• Сповіщення про прочитання: керуються channels.bluebubbles.sendReadReceipts (типово: true).
• Індикатори набору: OpenClaw надсилає події початку набору; BlueBubbles автоматично очищає індикатор набору під час надсилання або після тайм-ауту (ручна зупинка через DELETE ненадійна).

{
  channels: {
    bluebubbles: {
      sendReadReceipts: false, // disable read receipts
    },
  },
}

# Розширені дії

BlueBubbles підтримує розширені дії з повідомленнями, якщо їх увімкнено в конфігурації:

{
  channels: {
    bluebubbles: {
      actions: {
        reactions: true, // tapbacks (default: true)
        edit: true, // edit sent messages (macOS 13+, broken on macOS 26 Tahoe)
        unsend: true, // unsend messages (macOS 13+)
        reply: true, // reply threading by message GUID
        sendWithEffect: true, // message effects (slam, loud, etc.)
        renameGroup: true, // rename group chats
        setGroupIcon: true, // set group chat icon/photo (flaky on macOS 26 Tahoe)
        addParticipant: true, // add participants to groups
        removeParticipant: true, // remove participants from groups
        leaveGroup: true, // leave group chats
        sendAttachment: true, // send attachments/media
      },
    },
  },
}

# ID повідомлень (короткі та повні)

OpenClaw може показувати короткі ID повідомлень (наприклад, 1, 2), щоб заощаджувати токени.

• MessageSid / ReplyToId можуть бути короткими ID.
• MessageSidFull / ReplyToIdFull містять повні ID провайдера.
• Короткі ID зберігаються в пам’яті; вони можуть застаріти після перезапуску або витіснення з кешу.
• Дії приймають короткий або повний messageId, але короткі ID даватимуть помилку, якщо вони більше недоступні.

Використовуйте повні ID для довговічних автоматизацій і зберігання:

• Шаблони: {{MessageSidFull}}, {{ReplyToIdFull}}
• Контекст: MessageSidFull / ReplyToIdFull у вхідних payload

Див. Конфігурація щодо змінних шаблонів.

# Об’єднання split-send DM (команда + URL в одному введенні)

Коли користувач вводить команду та URL разом в iMessage - наприклад Dump https://example.com/article - Apple розбиває надсилання на дві окремі доставки webhook:

1. Текстове повідомлення ("Dump").
2. Бульбашка URL-перегляду ("https://...") із зображеннями OG-перегляду як вкладеннями.

У більшості налаштувань ці два webhooks надходять до OpenClaw з інтервалом приблизно 0.8-2.0 с. Без об’єднання агент отримує лише команду на ході 1, відповідає (часто «надішліть мені URL») і бачить URL лише на ході 2 - коли контекст команди вже втрачено.

channels.bluebubbles.coalesceSameSenderDms вмикає для DM злиття послідовних webhooks від того самого відправника в один хід агента. Групові чати й надалі ключуються за окремими повідомленнями, щоб зберегти структуру ходів із багатьма користувачами.

{
  channels: {
    bluebubbles: {
      coalesceSameSenderDms: true, // opt in (default: false)
    },
  },
}

{
  messages: {
    inbound: {
      byChannel: {
        // 2500 ms works for most setups; raise to 4000 ms if your Mac is slow
        // or under memory pressure (observed gap can stretch past 2 s then).
        bluebubbles: 2500,
      },
    },
  },
}

# Сценарії та що бачить агент

# Усунення проблем з об’єднанням split-send

Якщо прапорець увімкнено, але split-send усе одно надходять як два ходи, перевірте кожен шар:

grep coalesceSameSenderDms ~/.openclaw/openclaw.json

grep -E "Dispatching event to webhook" main.log | tail -20

# Блокове streaming

Керуйте тим, чи відповіді надсилаються одним повідомленням, чи streamed блоками:

{
  channels: {
    bluebubbles: {
      blockStreaming: true, // enable block streaming (off by default)
    },
  },
}

# Медіа + ліміти

• Вхідні вкладення завантажуються й зберігаються в media cache.
• Ліміт медіа через channels.bluebubbles.mediaMaxMb для вхідних і вихідних медіа (типово: 8 MB).
• Вихідний текст ділиться на фрагменти за channels.bluebubbles.textChunkLimit (типово: 4000 символів).

# Довідник конфігурації

Повна конфігурація: Конфігурація

Пов’язані глобальні параметри:

• agents.list[].groupChat.mentionPatterns (або messages.groupChat.mentionPatterns).
• messages.responsePrefix.

# Адресація / цілі доставки

Надавайте перевагу chat_guid для стабільної маршрутизації:

• chat_guid:iMessage;-;+15555550123 (бажано для груп)
• chat_id:123
• chat_identifier:...
• Прямі handles: +15555550123, [email protected]
  • Якщо прямий handle не має наявного DM-чату, OpenClaw створить його через POST /api/v1/chat/new. Для цього потрібно ввімкнути BlueBubbles Private API.

# Маршрутизація iMessage і SMS

Коли той самий handle має і чат iMessage, і чат SMS на Mac (наприклад, номер телефону, зареєстрований в iMessage, але який також отримував резервні зелені SMS), OpenClaw надає перевагу чату iMessage і ніколи непомітно не понижує доставку до SMS. Щоб примусово використати чат SMS, застосуйте явний префікс цілі sms: (наприклад sms:+15555550123). Handles без відповідного чату iMessage усе одно надсилаються через будь-який чат, який повідомляє BlueBubbles.

# Безпека

• Запити Webhook автентифікуються порівнянням query-параметрів або заголовків guid/password із channels.bluebubbles.password.
• Тримайте пароль API і кінцеву точку Webhook у секреті (ставтеся до них як до облікових даних).
• Для автентифікації Webhook BlueBubbles немає обходу через localhost. Якщо ви проксіюєте трафік Webhook, зберігайте пароль BlueBubbles у запиті від початку до кінця. gateway.trustedProxies тут не замінює channels.bluebubbles.password. Див. Безпека Gateway.
• Увімкніть HTTPS + правила брандмауера на сервері BlueBubbles, якщо відкриваєте його за межі своєї LAN.

# Усунення несправностей

• Якщо події введення/прочитання перестали працювати, перевірте журнали 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) усе ще надходять як два ходи: див. контрольний список усунення несправностей об’єднання розділених надсилань - поширені причини: занадто вузьке вікно debounce, часові позначки журналу сеансу помилково сприйняті як надходження Webhook або надсилання цитати-відповіді (яке використовує replyToBody, а не другий Webhook).
• Для інформації про стан/справність: openclaw status --all або openclaw status --deep.

Загальну довідку щодо робочого процесу каналів див. у Канали та посібнику Plugins.

# Пов’язане

• Маршрутизація каналів - маршрутизація сеансів для повідомлень
• Огляд каналів - усі підтримувані канали
• Групи - поведінка групових чатів і фільтрація за згадками
• Спарювання - автентифікація DM і потік спарювання
• Безпека - модель доступу та посилення захисту