iMessage

Стан: нативна інтеграція із зовнішнім CLI. Gateway запускає imsg rpc і обмінюється даними через JSON-RPC у stdio (без окремого демона/порту). Розширені дії потребують imsg launch і успішної перевірки приватного API.

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

brew install steipete/tap/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>

#!/usr/bin/env bashexec ssh -T gateway-host imsg "$@"

{channels: {imessage: {  enabled: true,  cliPath: "~/.openclaw/scripts/imsg-ssh",  remoteHost: "user@gateway-host", // used for SCP attachment fetches  includeAttachments: true,  // Optional: override allowed attachment roots.  // Defaults include /Users/*/Library/Messages/Attachments  attachmentRoots: ["/Users/*/Library/Messages/Attachments"],  remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],},},}

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

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

Not authorized to send Apple events to Messages. (-1743)

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

Увімкнення приватного API imsg

imsg постачається у двох робочих режимах:

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

Щоб отримати доступ до розширеної поверхні дій, яку документує ця сторінка каналу, вам потрібен режим приватного API. README imsg прямо вказує вимогу:

Розширені можливості, як-от read, typing, launch, bridge-backed rich send, мутація повідомлень і керування чатами, є опційними. Вони потребують вимкнення SIP та інжектування допоміжної dylib у Messages.app. imsg launch відмовляється інжектувати, коли SIP увімкнено.

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

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

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

   brew install steipete/tap/imsgimsg --versionimsg status --json

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

2. Вимкніть System Integrity Protection і (на сучасних macOS) Library Validation. Інжектування не-Apple helper dylib у підписаний Apple Messages.app потребує вимкненого SIP і послабленої перевірки бібліотек. Крок SIP у режимі Recovery залежить від версії macOS:

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

   На macOS 11 і новіших одного csrutil disable зазвичай недостатньо. Apple усе ще застосовує перевірку бібліотек до Messages.app як до платформного бінарного файлу, тому adhoc-підписаний helper відхиляється (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 вище достатні для інжектування helper у версіях від 26.0 до 26.5.x. Жодні boot-args не потрібні. 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 відхиляє adhoc helper під час завантаження, тому bridge так і не стає готовим, а запуск завершується за таймаутом. Саме цей таймаут є симптомом, з яким більшість стикається на Tahoe, і виправленням є plist вище, а не щось радикальніше.

   Це було підтверджено контрольованим порівнянням до/після на macOS 26.5.1 (Apple Silicon): з plist dylib мапиться в Messages.app, і bridge запускається; якщо вилучити plist і перезавантажитися, imsg launch видає наведену вище помилку таймауту, а dylib не мапиться.

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

   Дотримуйтеся процедури Apple у Recovery Mode для вашого Mac, щоб вимкнути SIP перед запуском imsg launch.

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 і групові операції з поверхні дій (відповідно до контрольного бар’єра можливостей для кожного методу).
• Ви можете запустити окремий Mac не на Apple Silicon (або виділений Mac для бота) з вимкненим SIP для навантаження iMessage, залишивши SIP увімкненим на основних пристроях. Див. Dedicated bot macOS user (separate iMessage identity) нижче.

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

{  channels: {    imessage: {      groupPolicy: "allowlist",      groupAllowFrom: ["+15555550123"],      groups: {        "*": { systemPrompt: "Use British spelling." },        "8421": {          requireMention: true,          systemPrompt: "This is the on-call rotation chat. Keep replies under 3 sentences.",        },        "9907": {          // explicit suppression: the wildcard "Use British spelling." does not apply here          systemPrompt: "",        },      },    },  },}

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

Застарілі чати iMessage також можна прив’язувати до сесій ACP.

Швидкий операторський потік:

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

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

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

• нормалізований handle DM, як-от +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: {        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,    },  },}

Об’єднання розділених DM-відправлень (команда + URL в одній композиції)

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

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

На більшості налаштувань ці два рядки надходять до OpenClaw з інтервалом приблизно 0,8-2,0 с. Без об’єднання агент отримує лише команду на зверненні 1, відповідає (часто "надішліть мені URL") і бачить URL лише на зверненні 2 — коли контекст команди вже втрачено. Це конвеєр надсилання Apple, а не щось, що додає OpenClaw або imsg.

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

{  channels: {    imessage: {      coalesceSameSenderDms: true, // opt in (default: false)    },  },}

{  messages: {    inbound: {      byChannel: {        // 7000 ms covers observed Messages.app URL-preview delays.        imessage: 7000,      },    },  },}

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

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

Вхідне відновлення після перезапуску bridge або Gateway

iMessage відновлює повідомлення, пропущені, поки Gateway був недоступний, і водночас пригнічує застарілу "backlog bomb", яку Apple може скинути після відновлення Push. Типова поведінка завжди ввімкнена й побудована на вхідній дедуплікації.

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

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

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

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

imessage: suppressed stale inbound backlog account=<id> sent=<iso> recovery=<bool> (&lt;N&gt; suppressed since start)

Міграція

channels.imessage.catchup.* застаріло — відновлення після простою тепер автоматичне й не потребує конфігурації для нових налаштувань. Наявні конфігурації з catchup.enabled: true залишаються чинними як профіль сумісності для вікна recovery replay. Вимкнені блоки catchup (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
• Pairing

Пов’язане

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