Перехід із BlueBubbles

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

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

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

​

Що робить imsg

• Читання відбувається з ~/Library/Messages/chat.db через read-only SQLite handle.
• Живі вхідні повідомлення надходять із imsg watch / watch.subscribe, який відстежує події файлової системи chat.db із резервним опитуванням.
• Надсилання використовує автоматизацію Messages.app для звичайного тексту й надсилання файлів.
• Розширені дії використовують imsg launch, щоб інʼєктувати допоміжний компонент imsg у Messages.app. Саме це відкриває сповіщення про прочитання, індикатори введення, розширене надсилання, редагування, скасування надсилання, відповіді в гілках, tapbacks і керування групами.
• Збірки 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, надайте Full Disk Access терміналу, редактору, процесу 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 на справжній chat id з imsg chats. Для надсилання потрібен дозвіл Automation для Messages.app. Якщо OpenClaw працюватиме через SSH, виконайте ці команди через ту саму SSH-обгортку або в тому самому контексті користувача, який використовуватиме OpenClaw.
3. Увімкніть міст приватного API, коли потрібні розширені дії:
   imsg launch
   imsg status --json
   
   imsg launch потребує вимкненого SIP. Базове надсилання, історія та спостереження працюють без imsg launch; розширені дії — ні.
4. Перевірте міст через OpenClaw:
   openclaw channels status --probe
   
   Вам потрібно imessage.privateApi.available: true. Якщо повідомляється false, спочатку виправте це — див. Виявлення можливостей.
5. Зробіть знімок конфігурації:
   cp ~/.openclaw/openclaw.json5 ~/.openclaw/openclaw.json5.bak
   

​

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

​

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

1. Allowlist відправника / цільового чату (channels.imessage.groupAllowFrom) — перевіряється isAllowedIMessageSender. Зіставляє вхідні повідомлення за дескриптором відправника, 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, коли конкретну групу вперше відкинуто під час виконання, із назвою chat_id та точним ключем, який треба додати до groups, щоб дозволити її.

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

​

Покроково

1. Додайте блок iMessage поруч з наявним блоком BlueBubbles. Залиште старий блок лише як джерело для копіювання, доки новий шлях не буде перевірено:
   {
     channels: {
       bluebubbles: {
         enabled: true,
         // ... existing config ...
       },
       imessage: {
         enabled: false, // turn on after the dry run below
         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 повідомляє про справний стан:
   openclaw gateway
   openclaw channels status
   openclaw channels status --probe   # expect imessage.privateApi.available: true
   
   Оскільки imessage.enabled усе ще false, вхідний трафік iMessage ще не маршрутизується — але --probe перевіряє міст, щоб ви виявили проблеми з дозволами або встановленням до перемикання.
3. Перемкніться. Видаліть конфігурацію 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.

​

Огляд паритету дій

​

Pairing, сесії та прив’язки ACP

• Схвалення pairing переносяться за 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:, bare handle) ідентичні.

​

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

​

Пов’язане

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