iMessage

Статус: нативная интеграция с внешним CLI. Gateway запускает imsg rpc и взаимодействует через JSON-RPC по stdio (без отдельного демона/порта). Расширенные действия требуют imsg launch и успешной проверки private 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, требуется Full Disk Access (доступ к БД Messages).
• Для отправки сообщений через Messages.app требуется разрешение Automation.
• Для расширенных действий (реакция / редактирование / отмена отправки / ответ в ветке / эффекты / операции с группами) System Integrity Protection должен быть отключен — см. Включение private API imsg ниже. Базовая отправка и получение текста и медиа работают без этого.

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

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

Включение private API imsg

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

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

Чтобы получить поверхность расширенных действий, описанную на этой странице канала, нужен режим private API. README imsg прямо указывает это требование:

Расширенные функции, такие как read, typing, launch, расширенная отправка через мост, изменение сообщений и управление чатами, включаются явно. Они требуют отключенного SIP и внедрения вспомогательной dylib в Messages.app. imsg launch отказывается выполнять внедрение, когда SIP включен.

Техника внедрения вспомогательной библиотеки использует собственную dylib imsg для доступа к private API Messages. В пути OpenClaw iMessage нет стороннего сервера или runtime 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) Library Validation. Внедрение вспомогательной dylib не от Apple в подписанное Apple приложение Messages.app требует отключенного SIP и ослабленной проверки библиотек. Шаг SIP в Recovery Mode зависит от версии 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 все еще применяет library validation к Messages.app как к platform binary, поэтому helper с adhoc-подписью отклоняется (Library Validation failed: ... platform binary, but mapped file is not) даже при отключенном SIP. После отключения SIP также отключите library validation и перезагрузитесь:

   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 при загрузке, поэтому мост так и не становится готовым, а запуск завершается по таймауту. Именно с этим таймаутом чаще всего сталкиваются на Tahoe, и исправление — plist выше, а не более радикальные меры.

   Это было подтверждено контролируемой проверкой до/после на macOS 26.5.1 (Apple Silicon): с plist dylib отображается в Messages.app, и мост запускается; удалите plist и перезагрузитесь — и imsg launch выдает указанную выше ошибку таймаута, а dylib не отображается.

   Если внедрение imsg launch или конкретные selectors начинают возвращать false после обновления macOS, эта проверка обычно является причиной. Проверьте состояние SIP и library validation, прежде чем считать, что сам шаг SIP не удался. Если эти настройки корректны, но мост всё равно не может выполнить внедрение, соберите imsg status --json вместе с выводом imsg launch и сообщите об этом в проект imsg, а не ослабляйте дополнительные общесистемные механизмы безопасности.

   Следуйте процессу Apple в режиме Recovery для вашего 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 '.selectors' должна показывать retractMessagePart: true плюс те селекторы редактирования / набора / прочтения, которые предоставляет ваша сборка macOS. Проверка OpenClaw plugin по методам в actions.ts объявляет только действия, чей базовый селектор равен true, поэтому набор действий, который вы видите в списке инструментов агента, отражает то, что мост действительно может делать на этом хосте.

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

Когда нельзя отключить SIP

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

• imsg возвращается к базовому режиму — только текст + медиа + получение.
• OpenClaw plugin всё ещё объявляет отправку текста/медиа и мониторинг входящих сообщений; он просто скрывает react, edit, unsend, reply, sendWithEffect и групповые операции из поверхности действий (согласно проверке возможностей по методам).
• Можно запустить отдельный 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 внутри личного сообщения или разрешенного группового чата.
• Будущие сообщения в том же разговоре 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: {        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,    },  },}

Объединение личных сообщений с раздельной отправкой (команда + URL в одной композиции)

Когда пользователь вводит команду и URL вместе — например, Dump https://example.com/article — приложение «Сообщения» Apple разделяет отправку на две отдельные строки 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, // opt in (default: false)    },  },}

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

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

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

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

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

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

Восстановление работает как с локальными, так и с удаленными настройками cliPath, потому что повторное воспроизведение since_rowid идет через то же RPC-соединение imsg. Разница в окне: когда Gateway может читать chat.db (локально), он привязывает границу rowid запуска, ограничивает диапазон повторного воспроизведения и доставляет пропущенные сообщения возрастом до пары часов. При удаленном SSH cliPath он не может читать базу данных, поэтому повторное воспроизведение не ограничено, а каждая строка использует живой возрастной барьер — недавно пропущенные сообщения все равно восстанавливаются, а старый бэклог все равно подавляется, просто с более узким живым окном. Запускайте Gateway на Mac с Messages, чтобы получить более широкое окно восстановления.

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

Подавленный бэклог логируется на уровне по умолчанию и никогда не отбрасывается молча (флаг recovery показывает, какое окно применялось):

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

Миграция

channels.imessage.catchup.* устарел — восстановление после простоя теперь автоматическое и не требует конфигурации для новых установок. Существующие конфигурации с catchup.enabled: true продолжают учитываться как профиль совместимости для окна повторного воспроизведения восстановления. Отключенные блоки catchup (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 и путь imsg для iMessage — объявление и сводка миграции
• Переход с BlueBubbles — таблица перевода конфигурации и пошаговое переключение
• Сопряжение — аутентификация DM и поток сопряжения
• Группы — поведение групповых чатов и ограничение по упоминаниям
• Маршрутизация каналов — маршрутизация сеансов для сообщений
• Безопасность — модель доступа и усиление защиты