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)

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

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

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

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

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

Розширені можливості, як-от read, typing, launch, розширене надсилання через міст, зміна повідомлень і керування чатами, вмикаються явно. Вони потребують вимкненого 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, бо базова вимога Apple залежить від ОС і обладнання:

   • 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 26 / Tahoe: політики library-validation і перевірки приватних entitlement для imagent стали ще суворішими; imsg може потребувати оновленої збірки, щоб не відставати. Якщо інжекція imsg launch або конкретні selectors починають повертати false після великого оновлення macOS, перевірте примітки до випуску imsg, перш ніж вважати, що крок SIP успішно виконано.

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

3. Інжектуйте helper. Коли SIP вимкнено і в Messages.app виконано вхід:

   imsg launch

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

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

   openclaw channels status --probe

   Запис iMessage має повідомляти works, а imsg status --json | jq '.selectors' має показувати retractMessagePart: true плюс ті селектори редагування / введення / прочитання, які надає ваша збірка macOS. Поштучне gating методів у Plugin OpenClaw в actions.ts рекламує лише дії, базовий селектор яких дорівнює true, тож поверхня дій, яку ви бачите в списку інструментів агента, відображає те, що міст реально може виконати на цьому хості.

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

Коли ви не можете вимкнути SIP

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

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

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

{  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 може використовувати:

• нормалізований ідентифікатор DM, наприклад +15555550123 або [email protected]
• 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: "[email protected]",      includeAttachments: true,      dbPath: "/Users/bot/Library/Messages/chat.db",    },  },}

#!/usr/bin/env bashexec ssh -T [email protected] imsg "$@"

Медіа, розбиття на частини та цілі доставлення

imsg chats --limit 20

Дії Private 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,      },    },  },}

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

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

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

Вимкнути:

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

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

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

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

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

channels.imessage.coalesceSameSenderDms вмикає для DM об’єднання послідовних рядків від того самого відправника в один крок агента. Групові чати й далі надсилаються повідомлення за повідомленням, щоб зберегти структуру кроків із кількома користувачами.

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

{  messages: {    inbound: {      byChannel: {        // 2500 ms works for most setups; raise to 4000 ms if your Mac is        // slow or under memory pressure (observed gap can stretch past 2 s        // then).        imessage: 2500,      },    },  },}

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

Надолуження після простою Gateway

Коли Gateway офлайн (збій, перезапуск, сон Mac, вимкнена машина), imsg watch після повернення Gateway відновлюється з поточного стану chat.db — усе, що надійшло під час прогалини, за замовчуванням ніколи не буде побачено. Catchup відтворює ці повідомлення під час наступного запуску, щоб агент не пропускав вхідний трафік мовчки.

Catchup вимкнено за замовчуванням. Увімкніть його для окремого каналу:

channels: {  imessage: {    catchup: {      enabled: true,             // master switch (default: false)      maxAgeMinutes: 120,        // skip rows older than now - 2h (default: 120, clamp 1..720)      perRunLimit: 50,           // max rows replayed per startup (default: 50, clamp 1..500)      firstRunLookbackMinutes: 30, // first run with no cursor: look back 30 min (default: 30)      maxFailureRetries: 10,     // give up on a wedged guid after 10 dispatch failures (default: 10)    },  },}

Як це виконується

Один прохід на кожен запуск monitorIMessageProvider, послідовність така: готовність imsg launch → watch.subscribe → performIMessageCatchup → цикл live-надсилання. Сам Catchup використовує chats.list + messages.history для кожного чату через той самий JSON-RPC-клієнт, який використовує imsg watch. Усе, що надходить під час проходу Catchup, проходить через live-надсилання у звичайному режимі; наявний кеш inbound-dedupe поглинає будь-яке перекриття з відтвореними рядками.

Кожен відтворений рядок подається через live-шлях надсилання (evaluateIMessageInbound + dispatchInboundMessage), тож allowlist, політика груп, debouncer, echo cache і сповіщення про прочитання поводяться однаково для відтворених і live-повідомлень.

Семантика курсора й повторів

Catchup зберігає курсор для кожного облікового запису в <openclawStateDir>/imessage/catchup/<account>__<hash>.json (каталог стану OpenClaw за замовчуванням — ~/.openclaw, можна перевизначити через OPENCLAW_STATE_DIR):

{  "lastSeenMs": 1717900800000,  "lastSeenRowid": 482910,  "updatedAt": 1717900801234,  "failureRetries": { "<guid>": 1 }}

• Курсор просувається після кожного успішного надсилання й утримується, коли надсилання рядка кидає помилку — наступний запуск повторює той самий рядок із утриманого курсора.
• Після maxFailureRetries послідовних помилок для того самого guid, Catchup записує warn і примусово просуває курсор повз застрягле повідомлення, щоб подальші запуски могли рухатися далі.
• GUID, щодо яких уже відмовилися, пропускаються відразу (без спроби надсилання) у подальших запусках і враховуються в skippedGivenUp у підсумку запуску.

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

imessage catchup: replayed=N skippedFromMe=… skippedGivenUp=… failed=… givenUp=… fetchedCount=…imessage catchup: giving up on guid=<guid> after &lt;N&gt; failures; advancing cursor past itimessage catchup: fetched &lt;X&gt; rows across chats, capped to perRunLimit=&lt;Y&gt;

Рядок WARN ... capped to perRunLimit означає, що один запуск не вичерпав увесь backlog. Збільште perRunLimit (макс. 500), якщо ваші прогалини регулярно перевищують стандартний прохід у 50 рядків.

Коли залишити вимкненим

• Gateway працює безперервно з автоматичним перезапуском через watchdog, а прогалини завжди < кількох секунд — стандартне вимкнене значення підходить.
• Обсяг DM низький, і пропущені повідомлення не змінять поведінку агента — початкове вікно firstRunLookbackMinutes може надіслати неочікуваний старий контекст під час першого ввімкнення.

Коли ви вмикаєте Catchup, перший запуск без курсора дивиться назад лише на firstRunLookbackMinutes (30 хв за замовчуванням), а не на повне вікно maxAgeMinutes — це запобігає відтворенню довгої історії повідомлень, що передували ввімкненню.

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

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

#!/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 — автентифікація DM і потік pairing
• Групи — поведінка групових чатів і gating згадок
• Маршрутизація каналів — маршрутизація сеансів для повідомлень
• Безпека — модель доступу й зміцнення