iMessage

Стан: нативна інтеграція із зовнішнім CLI. Gateway запускає imsg rpc і взаємодіє через JSON-RPC у stdio — без окремого демона чи порту. Для повноцінного каналу iMessage наполегливо рекомендовано режим Private API; відповіді, реакції tapback, ефекти, опитування, відповіді на вкладення та групові дії потребують imsg launch й успішної перевірки Private API.

Для поширеного локального налаштування майстер OpenClaw може запропонувати підтверджене користувачем установлення або оновлення imsg через Homebrew на Mac із виконаним входом у Messages. Ручне налаштування й топології з SSH-обгорткою залишаються під керуванням оператора: установлюйте або оновлюйте imsg у тому самому користувацькому контексті, у якому працюватиме Gateway або обгортка.

Швидке налаштування

brew install steipete/tap/imsgbrew update && brew upgrade imsgimsg rpc --helpimsg launchopenclaw channels status --probe

{channels: {imessage: {enabled: true,cliPath: "/usr/local/bin/imsg",dbPath: "/Users/user/Library/Messages/chat.db",},},}

openclaw gateway

openclaw pairing list imessageopenclaw pairing approve imessage <CODE>

ssh messages-mac 'brew install steipete/tap/imsg && brew update && brew upgrade imsg'

#!/usr/bin/env bashexec ssh -T messages-mac imsg "$@"

{channels: {imessage: {  enabled: true,  cliPath: "~/.openclaw/scripts/imsg-ssh",  remoteHost: "user@gateway-host", // використовується для отримання вкладень через SCP  includeAttachments: true,  // Необов’язково: додаткові дозволені кореневі каталоги вкладень (об’єднуються з типовим  // /Users/*/Library/Messages/Attachments).  attachmentRoots: ["/Users/*/Library/Messages/Attachments"],  remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],},},}

Вимоги та дозволи (macOS)

• На Mac, де працює imsg, має бути виконано вхід у Messages.
• Для контексту процесу, у якому працює OpenClaw/imsg, потрібен Full Disk Access (для доступу до бази даних Messages).
• Для надсилання повідомлень через Messages.app потрібен дозвіл Automation.
• Для розширених дій (реакція / редагування / скасування надсилання / відповідь у гілці / ефекти / опитування / групові операції) потрібно вимкнути System Integrity Protection — див. Увімкнення Private API imsg. Базове надсилання й отримання тексту та медіафайлів працює без цього.

Немає дозволу надсилати події Apple до Messages. (-1743)

kTCCServiceAppleEvents | /usr/libexec/sshd-keygen-wrapper | auth_value=0 | com.apple.MobileSMS

Увімкнення Private API imsg

imsg постачається у двох режимах роботи. Для OpenClaw рекомендовано режим Private API, оскільки він надає каналу нативні дії iMessage, на які очікують користувачі. Базовий режим залишається корисним для встановлень із низьким ризиком, початкової перевірки або хостів, де SIP неможливо вимкнути.

• Базовий режим (типовий, не потребує змін SIP): вихідні текстові й медіаповідомлення через send, спостереження за вхідними повідомленнями та історією, список чатів. Це доступно одразу після нового встановлення brew install steipete/tap/imsg і надання стандартних дозволів macOS, зазначених вище.
• Режим Private API: imsg впроваджує допоміжну dylib у Messages.app для виклику внутрішніх функцій IMCore. Це відкриває доступ до react, edit, unsend, reply (у гілці), sendWithEffect, poll і poll-vote (нативні опитування Messages), renameGroup, setGroupIcon, addParticipant, removeParticipant, leaveGroup, а також індикаторів набору тексту та сповіщень про прочитання.

Рекомендований на цій сторінці набір дій потребує режиму Private API. README для imsg прямо зазначає цю вимогу:

Розширені функції, як-от read, typing, launch, розширене надсилання через міст, зміна повідомлень і керування чатами, є необов’язковими. Для них потрібно вимкнути SIP і впровадити допоміжну dylib у Messages.app. imsg launch відмовляється виконувати впровадження, коли SIP увімкнено.

Метод впровадження допоміжної бібліотеки використовує власну dylib компонента imsg для доступу до приватних API Messages. У шляху iMessage для OpenClaw немає стороннього сервера чи середовища виконання BlueBubbles.

Налаштування

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

   brew install steipete/tap/imsgbrew update && brew upgrade imsgimsg --versionimsg status --json

   Вивід imsg status --json повідомляє про bridge_version, rpc_methods і selectors для кожного методу, щоб перед початком роботи можна було побачити, що підтримує поточна збірка.

2. Вимкніть захист цілісності системи, а в сучасних версіях macOS — також перевірку бібліотек. Для впровадження допоміжної бібліотеки dylib не від Apple у підписаний Apple процес Messages.app потрібно вимкнути SIP і послабити перевірку бібліотек. Крок із SIP у режимі відновлення залежить від версії macOS:

   • macOS 10.13–10.15 (Sierra–Catalina): вимкніть перевірку бібліотек через Terminal, перезавантажтеся в режим відновлення, виконайте csrutil disable, перезапустіть систему.
   • macOS 11+ (Big Sur і новіші), Intel: перейдіть у режим відновлення (або відновлення через інтернет), виконайте csrutil disable, перезапустіть систему.
   • macOS 11+, Apple Silicon: скористайтеся послідовністю запуску кнопкою живлення, щоб увійти в режим відновлення; у нових версіях macOS утримуйте клавішу Left Shift, коли натискаєте Continue, а потім виконайте csrutil disable. Для віртуальних машин діє окрема процедура, тому спочатку створіть знімок віртуальної машини.

   У macOS 11 і новіших версіях одного csrutil disable зазвичай недостатньо. Apple усе одно застосовує перевірку бібліотек до Messages.app як до платформного виконуваного файла, тому допоміжний компонент зі спеціальним підписом відхиляється (Library Validation failed: ... platform binary, but mapped file is not) навіть за вимкненого SIP. Після вимкнення SIP також вимкніть перевірку бібліотек і перезавантажте систему:

   sudo defaults write /Library/Preferences/com.apple.security.libraryvalidation.plist DisableLibraryValidation -bool true

   macOS 26 (Tahoe), перевірено у версії 26.5.1: вимкненого SIP разом із наведеною вище командою DisableLibraryValidation достатньо для впровадження допоміжного компонента у версіях від 26.0 до 26.5.x. Жодні параметри завантаження не потрібні. Вирішальним чинником є файл plist, і саме цей крок найчастіше пропускають, коли впровадження в Tahoe завершується невдало:

   • З файлом plist: imsg launch виконує впровадження, а imsg status повідомляє advanced_features: true.
   • Без файла plist (навіть за вимкненого SIP): imsg launch завершується помилкою Failed to launch: Timeout waiting for Messages.app to initialize. AMFI відхиляє допоміжний компонент зі спеціальним підписом під час завантаження, тому міст не переходить у стан готовності, а запуск завершується через перевищення часу очікування. Саме з таким симптомом найчастіше стикаються в Tahoe; виправленням є наведений вище файл plist, а не радикальніше послаблення захисту.

   Якщо після оновлення macOS впровадження imsg launch або певні selectors починають повертати false, звичайною причиною є ця перевірка. Перш ніж припускати, що сам крок із SIP не спрацював, перевірте стан SIP і перевірки бібліотек. Якщо ці параметри правильні, але міст усе одно не може виконати впровадження, зберіть imsg status --json разом із виводом imsg launch і повідомте про це в проєкт imsg, замість того щоб додатково послаблювати загальносистемні засоби захисту.

3. Впровадьте допоміжний компонент. Коли SIP вимкнено, а в Messages.app виконано вхід:

   imsg launch

   imsg launch відмовляється виконувати впровадження, якщо SIP усе ще ввімкнено, тож це також підтверджує успішність кроку 2.

4. Перевірте міст з OpenClaw:

   openclaw channels status --probe

   Запис iMessage має повідомити works, а imsg status --json | jq '{rpc_methods, selectors}' — показати можливості, доступні у вашій збірці macOS. Для створення опитувань потрібен selectors.pollPayloadMessage; для голосування потрібні і selectors.pollVoteMessage, і метод RPC poll.vote. Plugin OpenClaw оголошує лише дії, підтримувані кешованою перевіркою, тоді як за порожнього кешу він оптимістично вважає їх доступними та виконує перевірку під час першого надсилання.

Якщо openclaw channels status --probe повідомляє, що канал має стан works, але певні дії під час надсилання спричиняють помилку "iMessage <action> requires the imsg private API bridge", знову виконайте imsg launch — допоміжний компонент може від'єднатися (через перезапуск Messages.app, оновлення ОС тощо), а кешований стан available: true продовжуватиме оголошувати дії до наступного оновлення перевірки.

Коли SIP залишається ввімкненим

Якщо вимкнення SIP неприйнятне для вашої моделі загроз:

• imsg переходить у базовий режим — лише текст, медіафайли та отримання.
• Plugin OpenClaw усе одно оголошує надсилання тексту й медіафайлів та моніторинг вхідних повідомлень; він приховує react, edit, unsend, reply, sendWithEffect і групові операції з поверхні дій (відповідно до перевірки можливостей для кожного методу).
• Для навантаження iMessage можна використовувати окремий Mac без Apple Silicon (або спеціалізований Mac для бота) з вимкненим SIP, залишивши SIP увімкненим на основних пристроях. Див. нижче Спеціалізований користувач macOS для бота (окрема ідентичність iMessage).

Керування доступом і маршрутизація

{  channels: {    imessage: {      groupPolicy: "allowlist",      groupAllowFrom: ["+15555550123"],      groups: {        "*": { systemPrompt: "Використовуйте британський правопис." },        "8421": {          requireMention: true,          systemPrompt: "Це чат чергування. Відповіді мають містити не більше 3 речень.",        },        "9907": {          // явне скасування: шаблон "Використовуйте британський правопис." тут не застосовується          systemPrompt: "",        },      },    },  },}

Прив'язки розмов ACP

Чати iMessage можна прив'язувати до сеансів ACP.

Швидка процедура для оператора:

• Виконайте /acp spawn codex --bind here у приватному повідомленні або дозволеному груповому чаті.
• Подальші повідомлення в тій самій розмові iMessage спрямовуватимуться до створеного сеансу ACP.
• /new і /reset скидають той самий прив'язаний сеанс ACP без його заміни.
• /acp close закриває сеанс ACP і видаляє прив'язку.

Налаштовані постійні прив'язки використовують записи верхнього рівня bindings[] з type: "acp" і match.channel: "imessage".

match.peer.id може використовувати:

• нормалізований дескриптор приватного повідомлення, як-от +15555550123 або user@example.com
• chat_id:<id> (рекомендовано для стабільних групових прив'язок)
• chat_guid:<guid>
• chat_identifier:<identifier>

Приклад:

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

Спільну поведінку прив'язок ACP описано в розділі Агенти ACP.

Схеми розгортання

{  channels: {    imessage: {      enabled: true,      cliPath: "~/.openclaw/scripts/imsg-ssh",      remoteHost: "bot@mac-mini.tailnet-1234.ts.net",      includeAttachments: true,      dbPath: "/Users/bot/Library/Messages/chat.db",    },  },}

#!/usr/bin/env bashexec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"

Медіафайли, поділ на фрагменти та цілі доставлення

imsg chats --limit 20

Дії приватного API

Коли imsg launch працює, а openclaw channels status --probe повідомляє privateApi.available: true, інструмент повідомлень може використовувати нативні дії iMessage на додачу до звичайного надсилання тексту.

Усі дії типово ввімкнено; використовуйте channels.imessage.actions, щоб вимкнути окремі дії:

{  channels: {    imessage: {      actions: {        reactions: true,        edit: true,        unsend: true,        reply: true,        sendWithEffect: true,        sendAttachment: true,        renameGroup: true,        setGroupIcon: true,        addParticipant: true,        removeParticipant: true,        leaveGroup: true,        polls: true,      },    },  },}

{  channels: {    imessage: {      sendReadReceipts: false,    },  },}

Запис конфігурації

iMessage за замовчуванням дозволяє ініційований каналом запис конфігурації (для /config set|unset, коли commands.config: true).

Щоб вимкнути:

{  channels: {    imessage: {      configWrites: false,    },  },}

Об’єднання розділених надсилань у приватних повідомленнях (команда + URL в одному введенні)

Коли користувач вводить разом команду та URL — наприклад, Dump https://example.com/article — застосунок Apple Messages розділяє надсилання на два окремі рядки chat.db:

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

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

channels.imessage.coalesceSameSenderDms вмикає для приватної розмови буферизацію послідовних рядків від одного відправника. Коли imsg надає структурний маркер попереднього перегляду URL balloon_bundle_id: "com.apple.messages.URLBalloonProvider" в одному з вихідних рядків, OpenClaw об’єднує лише це справжнє розділене надсилання, а всі інші буферизовані рядки залишає окремими ходами. У старіших збірках imsg, які взагалі не надають метаданих бульбашки, OpenClaw не може відрізнити розділене надсилання від окремих надсилань, тому натомість об’єднує весь пакет. Це зберігає поведінку до появи метаданих і не допускає регресії, за якої розділені надсилання Dump <url> знову оброблялися б у два ходи. Групові чати й надалі обробляють кожне повідомлення окремо, щоб зберегти структуру ходів за участю кількох користувачів.

{  channels: {    imessage: {      coalesceSameSenderDms: true, // увімкнення за бажанням (за замовчуванням: false)    },  },}

{  messages: {    inbound: {      byChannel: {        // 7000 ms охоплює спостережувані затримки попереднього перегляду URL у Messages.app.        imessage: 7000,      },    },  },}

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

Стовпець «Прапорець увімкнено» показує поведінку збірки imsg, яка надає balloon_bundle_id. У старіших збірках imsg, які взагалі не надають метаданих бульбашки, позначені нижче рядки «Два ходи» / «N ходів» натомість використовують застаріле об’єднання (один хід): OpenClaw не може структурно відрізнити розділене надсилання від окремих надсилань, тому зберігає об’єднання, що застосовувалося до появи метаданих. Точне розділення активується, коли збірка починає надавати метадані бульбашки.

Відновлення вхідних повідомлень після перезапуску мосту або Gateway

iMessage відновлює повідомлення, пропущені під час простою Gateway, і водночас пригнічує застарілу «лавину накопичених повідомлень», яку Apple може надіслати після відновлення Push. Ця типова поведінка завжди ввімкнена й побудована на усуненні дублікатів вхідних повідомлень.

• Усунення дублікатів повторного відтворення. Кожне оброблене вхідне повідомлення записується за його Apple GUID у постійному стані Plugin (imessage.inbound-dedupe): резервується під час приймання та фіксується після обробки (звільняється в разі тимчасової помилки, щоб повторити спробу). Усе вже оброблене відкидається замість повторної обробки. Завдяки цьому відновлення може активно повторно відтворювати повідомлення без окремого обліку кожного з них.
• Відновлення після простою. Під час запуску монітор пам’ятає останній оброблений rowid chat.db (збережений курсор для кожного облікового запису) і передає його до imsg watch.subscribe як since_rowid, тому imsg повторно відтворює рядки, що надійшли під час простою Gateway, а потім переходить до відстеження в реальному часі. Повторне відтворення обмежене 500 найновішими рядками та повідомленнями віком до ~2 годин, а механізм усунення дублікатів відкидає все вже оброблене.
• Часова межа для застарілих накопичених повідомлень. Рядки вище початкової межі справді надходять у реальному часі; якщо дата надсилання одного з них більш ніж на ~15 хвилин передує часу його надходження, це накопичені повідомлення після Push-відновлення, і вони пригнічуються. Для повторно відтворених рядків (на межі або нижче неї) натомість використовується ширше вікно відновлення, тому нещодавно пропущене повідомлення доставляється, а давня історія — ні.

Відновлення працює як у локальних, так і у віддалених конфігураціях cliPath, оскільки повторне відтворення since_rowid виконується через те саме RPC-з’єднання imsg. Відмінність полягає у вікні: коли Gateway може читати chat.db (локально), він прив’язується до початкової межі rowid, обмежує діапазон повторного відтворення й доставляє пропущені повідомлення віком до кількох годин. Через віддалений SSH cliPath він не може читати базу даних, тому повторне відтворення не обмежується, а до кожного рядка застосовується часова межа реального часу — нещодавно пропущені повідомлення все одно відновлюються, а старі накопичені повідомлення пригнічуються, але з вужчим вікном реального часу. Для ширшого вікна відновлення запускайте Gateway на комп’ютері Mac із Messages.

Сигнал, видимий оператору

Пригнічені накопичені повідомлення реєструються на типовому рівні й ніколи не відкидаються без повідомлення (прапорець recovery указує, яке вікно застосовано):

imessage: пригнічено застарілі вхідні накопичені повідомлення account=<id> sent=<iso> recovery=<bool> (&lt;N&gt; пригнічено від запуску)

Міграція

channels.imessage.catchup.* застарів — відновлення після простою виконується автоматично й не потребує конфігурації для нових установок. Наявні конфігурації з catchup.enabled: true і надалі підтримуються як профіль сумісності для вікна повторного відтворення під час відновлення. Вимкнені блоки наздоганяння (enabled: false або без enabled: true) вилучено; openclaw doctor --fix видаляє їх.

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

imsg rpc --helpimsg status --jsonopenclaw channels status --probe

imsg chats --limit 10 --jsonimsg watch --chat-id <chat-id> --jsonsqlite3 ~/Library/Messages/chat.db \"select datetime(max(date)/1000000000 + 978307200, 'unixepoch', 'localtime'), max(ROWID) from message;"

launchctl kickstart -k system/com.apple.apsdlaunchctl kickstart -k gui/$(id -u)/com.apple.CommCenterlaunchctl kickstart -k gui/$(id -u)/com.apple.identityservicesdlaunchctl kickstart -k gui/$(id -u)/com.apple.imagentimsg launchopenclaw gateway restart

#!/usr/bin/env bashexec ssh -T messages-mac imsg "$@"

openclaw channels status --probe --channel imessage

imsg chats --limit 1imsg send <handle> "test"

Посилання на довідник із налаштування

• Довідник із налаштування — iMessage
• Налаштування Gateway
• Сполучення

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

• Огляд каналів — усі підтримувані канали
• Вилучення BlueBubbles і шлях iMessage через imsg — оголошення та огляд міграції
• Перехід із BlueBubbles — таблиця перетворення конфігурації та покрокове перемикання
• Сполучення — автентифікація в особистих повідомленнях і процес сполучення
• Групи — поведінка групових чатів і обмеження за згадками
• Маршрутизація каналів — маршрутизація сеансів для повідомлень
• Безпека — модель доступу та посилення захисту