iMessage

Статус: нативная интеграция с внешним CLI. Gateway запускает imsg rpc и обменивается данными по JSON-RPC через стандартные потоки ввода-вывода — отдельный демон или порт не требуется. Для полноценного канала 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, требуется полный доступ к диску (для доступа к базе данных Messages).
• Для отправки сообщений через Messages.app требуется разрешение на автоматизацию.
• Для расширенных действий (реакции / редактирование / отмена отправки / ответы в ветке / эффекты / опросы / групповые операции) необходимо отключить 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 внедряет вспомогательную динамическую библиотеку в 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 и внедрить вспомогательную динамическую библиотеку в Messages.app. imsg launch отказывается выполнять внедрение, если SIP включен.

Метод внедрения вспомогательной библиотеки использует собственную динамическую библиотеку 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. Отключите System Integrity Protection и (в современных версиях macOS) Library Validation. Для внедрения вспомогательной библиотеки dylib не от Apple в подписанный Apple процесс Messages.app необходимо отключить SIP и ослабить проверку библиотек. Шаг с SIP в режиме восстановления зависит от версии macOS:

   • macOS 10.13–10.15 (Sierra–Catalina): отключите Library Validation через Терминал, перезагрузитесь в режим восстановления, выполните csrutil disable, затем перезапустите систему.
   • macOS 11+ (Big Sur и более поздние версии), Intel: загрузитесь в режим восстановления (или Internet Recovery), выполните 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. Параметры 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 отклоняет вспомогательный модуль с произвольной подписью при загрузке, поэтому мост не переходит в состояние готовности, а запуск завершается по тайм-ауту. Именно с таким тайм-аутом чаще всего сталкиваются пользователи 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. Плагин OpenClaw объявляет только действия, поддерживаемые кэшированным результатом проверки, а при пустом кэше действует оптимистично и выполняет проверку при первой отправке.

Если openclaw channels status --probe сообщает, что канал находится в состоянии works, но отдельные действия при отправке вызывают ошибку "Для iMessage <action> требуется мост закрытого API imsg", снова выполните imsg launch — вспомогательный модуль может выгрузиться (после перезапуска Messages.app, обновления ОС и т. п.), а кэшированный статус available: true продолжит объявлять действия до следующего обновления проверки.

Если SIP остаётся включённым

Если отключение SIP неприемлемо для вашей модели угроз:

• imsg переходит в базовый режим — только текст, медиафайлы и получение сообщений.
• Плагин OpenClaw по-прежнему объявляет отправку текста и медиафайлов, а также мониторинг входящих сообщений; он скрывает react, edit, unsend, reply, sendWithEffect и групповые операции из набора действий (согласно проверке возможностей для каждого метода).
• Можно использовать отдельный Mac без Apple Silicon (или выделенный Mac для бота) с отключённым SIP для рабочей нагрузки iMessage, сохранив 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 с. Без объединения агент получает только команду в ходе 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 мс охватывают наблюдаемые задержки предпросмотра URL в Messages.app.        imessage: 7000,      },    },  },}

Сценарии и то, что видит агент

Столбец «Флаг включён» показывает поведение сборки imsg, создающей balloon_bundle_id. В старых сборках imsg, которые вообще не создают метаданные карточки, отмеченные ниже варианты «Два хода» / «N ходов» вместо этого используют устаревшее объединение (один ход): OpenClaw не может структурно отличить разделённую отправку от отдельных сообщений, поэтому сохраняет объединение, применявшееся до появления метаданных. Точное разделение включается, когда сборка начинает создавать метаданные карточки.

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

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

• Устранение дубликатов при повторном воспроизведении. Каждое обработанное входящее сообщение записывается по его Apple GUID в постоянное состояние плагина (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 — таблица преобразования конфигурации и пошаговое переключение
• Сопряжение — аутентификация в личных сообщениях и процесс сопряжения
• Группы — поведение групповых чатов и ограничение по упоминаниям
• Маршрутизация каналов — маршрутизация сеансов для сообщений
• Безопасность — модель доступа и усиление защиты