Перехід із 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. Коли Gateway зупинено, увімкніть channels.imessage, а потім виконайте openclaw channels status --probe --channel imessage.
6. Протестуйте одне особисте повідомлення, одну дозволену групу, вкладення, якщо вони ввімкнені, і кожну дію приватного API, яку, як ви очікуєте, використовуватиме агент.
7. Видаліть сервер BlueBubbles і стару конфігурацію channels.bluebubbles після перевірки шляху iMessage.

​

Коли ця міграція має сенс

• Ви вже запускаєте imsg на тому самому Mac (або на доступному через SSH), де виконано вхід у Messages.app.
• Ви хочете на один рухомий компонент менше — без окремого сервера BlueBubbles, без кінцевої точки REST для автентифікації, без обв’язки Webhook. Один бінарний файл CLI замість сервера + клієнтського застосунку + допоміжного компонента.
• Ви використовуєте підтримувану збірку macOS / imsg, де перевірка приватного API повідомляє available: true.

​

Що робить imsg

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

​

Перш ніж почати

1. Установіть imsg на Mac, де працює Messages.app:
   brew install steipete/tap/imsg
   imsg --version
   imsg chats --limit 3
   
   Якщо 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, якщо вам потрібні розширені дії:
   imsg launch
   imsg status --json
   
   imsg launch вимагає вимкненого SIP. Базове надсилання, історія та спостереження працюють без imsg launch; розширені дії — ні.
4. Після додавання ввімкненої конфігурації channels.imessage перевірте міст через OpenClaw:
   openclaw channels status --probe
   
   Вам потрібно imessage.privateApi.available: true. Якщо повідомляється false, спершу виправте це — див. Виявлення можливостей. channels status --probe перевіряє лише налаштовані й увімкнені облікові записи.
5. Зробіть знімок конфігурації:
   cp ~/.openclaw/openclaw.json5 ~/.openclaw/openclaw.json5.bak
   

​

Переклад конфігурації

​

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

1. Allowlist відправника / цілі чату (channels.imessage.groupAllowFrom) — перевіряється isAllowedIMessageSender. Зіставляє вхідні повідомлення за handle відправника, chat_guid, chat_identifier або chat_id. Та сама форма, що й у BlueBubbles.
2. Реєстр груп (channels.imessage.groups) — перевіряється resolveChannelGroupPolicy з inbound-processing.ts:199. З groupPolicy: "allowlist" цей шлюз вимагає одне з такого:
   • wildcard-запис groups: { "*": { ... } } (встановлює allowAll = true), або
   • явний запис для окремого chat_id у groups.

• Одноразовий стартовий warn для кожного облікового запису, коли задано groupPolicy: "allowlist", але channels.imessage.groups порожній (немає wildcard "*", немає записів для окремих chat_id) — спрацьовує до надходження будь-яких повідомлень.
• Одноразовий warn для кожного chat_id під час першого відкидання конкретної групи в runtime, із зазначенням chat_id і точного ключа, який потрібно додати до groups, щоб дозволити її.

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

​

Покроково

1. Додайте блок iMessage поруч з наявним блоком BlueBubbles. Тримайте його вимкненим, поки Gateway усе ще маршрутизує трафік BlueBubbles:
   {
     channels: {
       bluebubbles: {
         enabled: true,
         // ... existing config ...
       },
       imessage: {
         enabled: false,
         cliPath: "/opt/homebrew/bin/imsg",
         dmPolicy: "pairing",
         allowFrom: ["+15555550123"], // copy from bluebubbles.allowFrom
         groupPolicy: "allowlist",
         groupAllowFrom: [], // copy from bluebubbles.groupAllowFrom
         groups: { "*": { requireMention: true } }, // copy from bluebubbles.groups — silently drops groups if missing, see "Group registry footgun" above
         actions: {
           reactions: true,
           edit: true,
           unsend: true,
           reply: true,
           sendWithEffect: true,
           sendAttachment: true,
         },
       },
     },
   }
   
2. Перевірте до того, як трафік стане важливим — зупиніть Gateway, тимчасово увімкніть блок iMessage і підтвердьте, що iMessage повідомляє про справний стан із CLI:
   openclaw gateway stop
   # edit config: channels.imessage.enabled = true
   openclaw channels status --probe --channel imessage   # expect imessage.privateApi.available: true
   
   channels status --probe перевіряє лише налаштовані, увімкнені облікові записи. Не перезапускайте Gateway з одночасно увімкненими BlueBubbles та iMessage, якщо ви навмисно не хочете, щоб працювали обидва монітори каналів. Якщо ви не перемикаєтесь негайно, встановіть channels.imessage.enabled назад у false перед перезапуском Gateway. Використовуйте прямі команди imsg у Перед початком, щоб перевірити Mac перед увімкненням трафіку OpenClaw.
3. Перемкніться. Коли увімкнений обліковий запис iMessage повідомляє про справний стан, видаліть конфігурацію BlueBubbles і залиште iMessage увімкненим:
   {
     channels: {
       imessage: { enabled: true /* ... */ },
     },
   }
   
   Перезапустіть Gateway. Вхідний трафік iMessage тепер проходить через вбудований Plugin.
4. Перевірте приватні повідомлення. Надішліть агенту пряме повідомлення; підтвердьте, що відповідь доставлена.
5. Перевірте групи окремо. Приватні повідомлення й групи проходять різними шляхами коду — успіх приватного повідомлення не доводить, що групи маршрутизуються. Надішліть агенту повідомлення в спарений груповий чат і підтвердьте, що відповідь доставлена. Якщо група замовкає (немає відповіді агента, немає помилки), перевірте журнал Gateway на imessage: dropping group message from chat_id=<id> або стартовий рядок imessage: groupPolicy="allowlist" but channels.imessage.groups is empty — обидва з’являються на типовому рівні журналювання. Якщо з’являється будь-який із них, ваш блок groups відсутній або порожній — див. «пастку реєстру груп» вище.
6. Перевірте поверхню дій — зі спареного приватного повідомлення попросіть агента поставити реакцію, відредагувати, скасувати надсилання, відповісти, надіслати фото, а також (у групі) перейменувати групу / додати або видалити учасника. Кожна дія має нативно з’явитися в Messages.app. Якщо будь-що видає “iMessage <action> requires the imsg private API bridge”, знову запустіть imsg launch і оновіть channels status --probe.
7. Видаліть сервер і конфігурацію BlueBubbles, коли приватні повідомлення iMessage, групи й дії перевірено. OpenClaw не використовуватиме channels.bluebubbles.

​

Стислий огляд паритету дій

​

Спарювання, сеанси та прив’язки ACP

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

​

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

​

Пов’язане

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