iMessage

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

Метод внедрения вспомогательного компонента использует собственную библиотеку dylib 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 через 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 как к платформенному исполняемому файлу, поэтому вспомогательный компонент с подписью ad hoc отклоняется (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: для внедрения вспомогательного компонента во всех версиях от 26.0 до 26.5.x достаточно отключённого SIP вместе с приведённой выше командой DisableLibraryValidation. Параметры 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 отклоняет вспомогательный компонент с подписью ad hoc при загрузке, поэтому мост не переходит в состояние готовности, а запуск завершается по тайм-ауту. Именно с таким тайм-аутом чаще всего сталкиваются в 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> requires the imsg private API bridge", снова выполните imsg launch — вспомогательный компонент может отключиться из-за перезапуска Messages.app, обновления ОС и т. п., а кэшированное состояние available: true продолжит объявлять действия до следующего обновления проверки.

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

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

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

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