iMessage

​

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

brew install steipete/tap/imsg
brew update && brew upgrade 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>

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

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

imsg chats --limit 1
# або
imsg send <handle> "test"

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

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

​

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

• Базовий режим (типовий, не потребує змін 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, а також індикаторів набору тексту та сповіщень про прочитання.

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

​

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

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

​

Коли 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: { "*": { "requireMention": true } },
    },
  },
}

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

​

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

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

• нормалізований дескриптор приватного повідомлення, як-от +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,
    },
  },
}

​

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

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

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

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

​

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

​

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

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

​

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

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

​

Міграція

​

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

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
• Сполучення

​

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

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