Перехід із BlueBubbles

Підтримку BlueBubbles вилучено. OpenClaw підтримує iMessage лише через вбудований плагін imessage, який керує steipete/imsg через JSON-RPC і надає доступ до тих самих приватних API, що й BlueBubbles (react, edit, unsend, reply, sendWithEffect, нативні опитування, керування групами, вкладення). Один виконуваний файл CLI замінює сервер BlueBubbles, клієнтський застосунок та інфраструктуру Webhook: без кінцевої точки REST і без автентифікації Webhook.

У цьому посібнику описано перенесення старих конфігурацій channels.bluebubbles до channels.imessage. Іншого підтримуваного шляху міграції немає. У поточній версії OpenClaw залишковий блок channels.bluebubbles неактивний — жоден компонент середовища виконання його не читає.

Контрольний список міграції

Найкоротший безпечний шлях, якщо ви вже знаєте свою стару конфігурацію BlueBubbles:

1. Перевірте imsg безпосередньо на Mac, де працює Messages.app (imsg chats, imsg history, imsg send, imsg rpc --help).
2. Скопіюйте ключі поведінки з channels.bluebubbles до channels.imessage: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups, includeAttachments, attachmentRoots, mediaMaxMb, textChunkLimit, coalesceSameSenderDms і actions.
3. Вилучіть транспортні ключі, яких більше не існує: serverUrl, password, URL-адреси Webhook і налаштування сервера BlueBubbles.
4. Якщо Gateway працює не на тому Mac, де запущено Messages, установіть для channels.imessage.cliPath значення обгортки SSH, а для віддаленого отримання вкладень налаштуйте remoteHost.
5. Увімкніть channels.imessage, перезапустіть Gateway, а потім виконайте openclaw channels status --probe --channel imessage.
6. Перевірте одне особисте повідомлення, одну дозволену групу, вкладення, якщо їх увімкнено, і кожну дію приватного API, яку має використовувати агент.
7. Після перевірки шляху iMessage видаліть сервер BlueBubbles і стару конфігурацію channels.bluebubbles.

Що робить imsg

imsg — це локальний CLI для Messages у macOS. OpenClaw запускає imsg rpc як дочірній процес і обмінюється даними через JSON-RPC за допомогою stdin/stdout. Немає HTTP-сервера, URL-адреси Webhook, фонового демона, агента запуску чи порту, який потрібно відкривати.

• Читання виконується з ~/Library/Messages/chat.db через дескриптор SQLite лише для читання.
• Вхідні повідомлення в реальному часі надходять із imsg watch / watch.subscribe, який відстежує події файлової системи для chat.db із резервним опитуванням.
• Для звичайного надсилання тексту й файлів використовується автоматизація Messages.app.
• Розширені дії використовують imsg launch, щоб впровадити допоміжний компонент imsg у Messages.app. Саме це надає сповіщення про прочитання, індикатори введення, форматоване надсилання, редагування, скасування надсилання, відповіді в гілках, реакції, опитування та керування групами.
• Збірки для Linux можуть переглядати скопійовану базу даних chat.db, але не можуть надсилати повідомлення, відстежувати активну базу даних Mac або керувати Messages.app. Для роботи iMessage в OpenClaw запускайте imsg на Mac із виконаним входом або через обгортку SSH до цього Mac.

Перед початком

1. Установіть imsg на Mac, де працює Messages.app:

   brew install steipete/tap/imsgbrew update && brew upgrade imsgimsg --versionimsg chats --limit 3

   Для звичайного локального налаштування майстер налаштування OpenClaw може запропонувати підтверджене користувачем установлення або оновлення imsg через Homebrew на Mac із виконаним входом у Messages. Ручне налаштування й топології з обгорткою SSH залишаються під керуванням оператора: повторіть оновлення Homebrew у тому самому локальному або віддаленому контексті користувача, у якому запускатиметься imsg. Якщо imsg chats завершується помилкою unable to open database file, повертає порожній результат або повідомлення authorization denied, надайте повний доступ до диска терміналу, редактору, процесу Node, службі Gateway або батьківському процесу SSH, який запускає imsg, а потім перезапустіть цей батьківський процес.

2. Перевірте можливості читання, спостереження, надсилання та RPC, перш ніж змінювати конфігурацію OpenClaw:

   imsg chats --limit 10 --json | jq -simsg history --chat-id 42 --limit 10 --attachments --json | jq -simsg watch --chat-id 42 --reactions --jsonimsg send --chat-id 42 --text "OpenClaw imsg test"imsg rpc --help

   Замініть 42 справжнім ідентифікатором чату з imsg chats. Для надсилання потрібен дозвіл на автоматизацію Messages.app. Якщо OpenClaw працюватиме через SSH, виконуйте ці команди через ту саму обгортку SSH або в тому самому контексті користувача, який використовуватиме OpenClaw. Якщо читання працює, але надсилання завершується помилкою AppleEvents -1743, перевірте, чи дозвіл на автоматизацію надано /usr/libexec/sshd-keygen-wrapper; див. Збій надсилання через обгортку SSH із помилкою AppleEvents -1743.

3. Увімкніть міст приватного API. Це наполегливо рекомендовано для iMessage в OpenClaw, оскільки від нього залежать відповіді, реакції, ефекти, опитування, відповіді на вкладення та групові дії:

   imsg launchimsg status --json

   Для imsg launch потрібно вимкнути SIP (а в сучасних версіях macOS — також послабити перевірку бібліотек; див. Увімкнення приватного API imsg). Базове надсилання, перегляд історії та спостереження працюють без imsg launch, але повний набір дій iMessage у OpenClaw — ні.

4. Після ввімкнення channels.imessage і запуску Gateway перевірте міст через OpenClaw:

   openclaw channels status --probe

   Обліковий запис iMessage має повідомити works; з параметром --json дані перевірки містять privateApi.available: true. Якщо відображається false, спочатку виправте це — див. Виявлення можливостей. Для перевірки потрібен доступний Gateway (інакше CLI повертає лише дані на основі конфігурації), а перевіряються тільки налаштовані й увімкнені облікові записи.

5. Створіть резервну копію конфігурації:

   cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak

Перенесення конфігурації

iMessage і BlueBubbles мають більшість спільних ключів поведінки на рівні каналу. Змінюються транспорт (сервер REST замість локального CLI) і формат ключів реєстру груп.

Конфігурації кількох облікових записів (channels.bluebubbles.accounts.*) переносяться один до одного в channels.imessage.accounts.*.

Пастка реєстру груп

Вбудований Plugin iMessage послідовно застосовує два фільтри груп. Щоб групове повідомлення дійшло до агента, воно має пройти обидва:

1. Список дозволених відправників / цільових чатів (channels.imessage.groupAllowFrom) — зіставляється з ідентифікатором відправника або цільовим чатом (записи chat_id:, chat_guid:, chat_identifier:). Якщо groupAllowFrom не задано, цей фільтр використовує allowFrom; явний groupAllowFrom: [] вимикає цей резервний варіант і відкидає кожне групове повідомлення за groupPolicy: "allowlist".
2. Реєстр груп (channels.imessage.groups) — ключами є числові chat_id iMessage:
   • Блоку groups немає (або він порожній): групи проходять цей фільтр, якщо фільтр 1 має непорожній ефективний список дозволених відправників; доступ визначається фільтрацією відправників, а попередження під час запуску про відкидання всіх повідомлень не з’являється.
   • groups містить записи, але не "*": проходять лише перелічені ключі chat_id. Додавання будь-якої групи перетворює реєстр на список дозволених навіть за groupPolicy: "open".
   • groups: { "*": { ... } }: кожна група проходить цей фільтр.

Пастка міграції: у BlueBubbles ключами записів groups були GUID чату / ідентифікатор чату, тоді як у реєстрі iMessage ключами є числові chat_id. Дослівно скопійовані записи окремих груп створюють непорожній реєстр, ключі якого ніколи не збігаються, тому кожне групове повідомлення відкидається на фільтрі 2. Скопіюйте шаблон "*" дослівно; для окремих записів груп використайте як ключі значення chat_id з imsg chats.

Обидва шляхи відкидання видимі за типового рівня журналювання в рядках warn:

• Один раз для кожного облікового запису під час запуску, коли задано groupPolicy: "allowlist", а ефективний список дозволених відправників груп порожній: imessage: groupPolicy="allowlist" for account "<id>" but no group sender allowlist is configured .... Задайте groupAllowFrom (або allowFrom), щоб дозволити відправників; додавання лише groups не задовольняє фільтр відправників.
• Один раз для кожного chat_id під час виконання, коли реєстр відкидає групу: imessage: dropping group message from chat_id=<id> ... not in channels.imessage.groups allowlist, із зазначенням точного ключа, який потрібно додати.

Приватні повідомлення продовжують працювати в обох випадках — вони проходять іншим шляхом у коді, тому успішна робота приватних повідомлень не підтверджує маршрутизацію групових повідомлень.

Мінімальна конфігурація з обмеженням за відправниками для groupPolicy: "allowlist":

{  channels: {    imessage: {      groupPolicy: "allowlist",      groupAllowFrom: ["+15555550123", "chat_guid:any;-;..."],    },  },}

Це дозволяє налаштованих відправників у будь-якій групі. Додайте записи groups, щоб обмежити дозволені чати або задати параметри окремих чатів, як-от requireMention; скопіюйте запис BlueBubbles "*" дослівно, але змініть ключі окремих записів на числові значення chat_id iMessage.

Покроково

1. Перенесіть конфігурацію. Під час редагування залиште новий блок вимкненим; старий блок channels.bluebubbles ігнорується поточною версією OpenClaw і може залишатися поруч як довідковий:

   {  channels: {    imessage: {      enabled: false, // змініть на true, коли будете готові до переходу      cliPath: "/opt/homebrew/bin/imsg",      dmPolicy: "pairing",      allowFrom: ["+15555550123"], // скопіюйте з bluebubbles.allowFrom      groupPolicy: "allowlist",      groupAllowFrom: [], // скопіюйте з bluebubbles.groupAllowFrom      groups: { "*": { requireMention: true } }, // шаблон копіюється дослівно; змініть ключі записів окремих чатів на chat_id      // дії ввімкнені за замовчуванням; установіть окремі перемикачі в false, щоб вимкнути їх    },  },}

2. Перейдіть і виконайте перевірку. Установіть channels.imessage.enabled: true, перезапустіть Gateway і переконайтеся, що канал повідомляє про справний стан:

   openclaw gateway restartopenclaw channels status --probe --channel imessage   # очікується "works"; --json показує privateApi.available: true

   Для перевірки потрібен доступний Gateway; перевіряються лише налаштовані й увімкнені облікові записи. Щоб перевірити сам Mac, скористайтеся безпосередніми командами imsg з розділу Перед початком.

3. Перевірте особисті повідомлення. Надішліть агенту особисте повідомлення й переконайтеся, що відповідь надійшла.

4. Перевірте групи окремо. Особисті повідомлення та групи проходять різними шляхами коду — успішна робота особистих повідомлень не підтверджує маршрутизацію груп. Надішліть повідомлення в дозволеному груповому чаті й переконайтеся, що відповідь надійшла. Якщо група не відповідає (немає ні відповіді агента, ні помилки), перевірте журнал Gateway на наявність двох рядків warn із розділу «Пастка реєстру груп» вище. Попередження під час запуску означає, що фактичний список дозволених відправників порожній; попередження для окремого chat_id означає, що заповнений реєстр groups не містить цього чату.

5. Перевірте набір дій. Із пов’язаного особистого чату попросіть агента поставити реакцію, відредагувати й скасувати надсилання повідомлення, відповісти, надіслати фотографію, а також у групі перейменувати її або додати чи видалити учасника. Кожна дія має виконуватися нативно в Messages.app. Якщо будь-яка дія спричиняє помилку iMessage <action> requires the imsg private API bridge, знову виконайте imsg launch і оновіть стан командою openclaw channels status --probe.

6. Видаліть сервер BlueBubbles і блок channels.bluebubbles, коли перевірите особисті повідомлення, групи й дії iMessage. OpenClaw не читає channels.bluebubbles.

Коротке порівняння підтримки дій

iMessage відновлює повідомлення, пропущені під час недоступності Gateway: під час запуску він повторно відтворює записи від останнього переданого rowid через imsg watch.subscribe із since_rowid, усуває дублікати за GUID, а обмеження за віком застарілої черги пригнічує «вибух черги» під час скидання Push. Це працює через RPC-з’єднання imsg, тому також підтримуються конфігурації віддаленого SSH із cliPath; локальні конфігурації отримують ширше вікно відновлення, оскільки можуть читати chat.db. Див. Відновлення вхідних повідомлень після перезапуску мосту або Gateway.

Пов’язування, сеанси та прив’язки ACP

• Списки дозволених переносяться за ідентифікатором. channels.imessage.allowFrom розпізнає ті самі рядки +15555550123 / user@example.com, які використовував BlueBubbles, — скопіюйте їх дослівно.
• Схвалення зі сховища пов’язувань не переносяться. Сховище пов’язувань окреме для кожного каналу, і старе сховище BlueBubbles не мігрується. Відправники, схвалені лише через пов’язування, мають повторно пов’язатися в iMessage, або ви можете додати їхні ідентифікатори до allowFrom.
• Сеанси залишаються окремими для кожної комбінації агента й чату. За стандартного значення session.dmScope=main особисті повідомлення об’єднуються в основному сеансі агента; групові сеанси залишаються ізольованими за chat_id (agent:<agentId>:imessage:group:<chat_id>). Стара історія розмов за ключами сеансів BlueBubbles не переноситься до сеансів iMessage.
• Прив’язки ACP, що посилаються на match.channel: "bluebubbles", потрібно змінити на "imessage". Формати match.peer.id (chat_id:, chat_guid:, chat_identifier:, ідентифікатор без префікса) ідентичні.

Каналу для відкату немає

Підтримуваного середовища виконання BlueBubbles, на яке можна повернутися, немає. Якщо перевірка iMessage завершилася невдало, установіть channels.imessage.enabled: false, перезапустіть Gateway, усуньте проблему, що блокує imsg, і повторіть перехід.

Кеш відповідей зберігається у стані Plugin у SQLite. openclaw doctor --fix імпортує й архівує старий допоміжний файл imessage/reply-cache.jsonl, якщо він наявний.

Пов’язані матеріали

• Видалення BlueBubbles і шлях iMessage через imsg — коротке оголошення та зведення для операторів.
• iMessage — повна довідка щодо каналу iMessage, зокрема налаштування imsg launch і виявлення можливостей.
• /channels/bluebubbles — застаріла URL-адреса, яка переспрямовує до цього посібника з міграції.
• Пов’язування — автентифікація особистих повідомлень і процес пов’язування.
• Маршрутизація каналів — як Gateway вибирає канал для вихідних відповідей.