Перехід із 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

• Читання виконується з ~/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/imsg
   brew update && brew upgrade imsg
   imsg --version
   imsg 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 -s
   imsg history --chat-id 42 --limit 10 --attachments --json | jq -s
   imsg watch --chat-id 42 --reactions --json
   imsg 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 launch
   imsg 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
   

​

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

​

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

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: { "*": { ... } }: кожна група проходить цей фільтр.

• Один раз для кожного облікового запису під час запуску, коли задано 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, із зазначенням точного ключа, який потрібно додати.

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

​

Покроково

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 restart
   openclaw 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.

​

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

​

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