iMessage

​

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

brew install steipete/tap/imsg
imsg rpc --help
imsg launch
openclaw channels status --probe

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

openclaw gateway

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

#!/usr/bin/env bash
exec 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 нижче. Базове надсилання/отримання тексту й медіа працює без цього.

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

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

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

​

Увімкнення приватного API 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, а також індикатори набору тексту й прочитання.

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

​

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

1. Установіть (або оновіть) imsg на Mac, де працює Messages.app:
   brew install steipete/tap/imsg
   imsg --version
   imsg 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 оголошує лише дії, підтримані кешованою перевіркою, тоді як порожній кеш залишається оптимістичним і виконує перевірку під час першого надсилання.

​

Коли неможливо вимкнути 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: { "*": { "requireMention": true } },
    },
  },
}

{
  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

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

• нормалізований 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" },
    },
  ],
}

​

Шаблони розгортання

{
  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 bash
exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"

​

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

imsg chats --limit 20

​

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

{
  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,
    },
  },
}

​

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

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

​

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

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

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

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

​

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

​

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

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

​

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

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

​

Міграція

​

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

imsg rpc --help
imsg status --json
openclaw channels status --probe

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

launchctl kickstart -k system/com.apple.apsd
launchctl kickstart -k gui/$(id -u)/com.apple.CommCenter
launchctl kickstart -k gui/$(id -u)/com.apple.identityservicesd
launchctl kickstart -k gui/$(id -u)/com.apple.imagent
imsg launch
openclaw gateway restart

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

openclaw channels status --probe --channel imessage

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

​

Посилання на довідник конфігурації

• Довідник конфігурації - iMessage
• Конфігурація Gateway
• Pairing

​

Пов’язане

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