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, требуется полный доступ к диску (для доступа к базе данных Messages).
• Для отправки сообщений через Messages.app требуется разрешение на автоматизацию.
• Для расширенных действий (реакция / редактирование / отмена отправки / ответ в ветке / эффекты / опросы / групповые операции) необходимо отключить 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. Отключите защиту целостности системы (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 объявляет только действия, поддерживаемые кэшированной проверкой, но при пустом кэше исходит из оптимистичных предположений и выполняет проверку при первой отправке.

​

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

• imsg переходит в базовый режим — только текст, мультимедиа и получение сообщений.
• Плагин 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 мс покрывают наблюдаемые задержки предпросмотра URL в Messages.app.
        imessage: 7000,
      },
    },
  },
}

​

Сценарии и данные, видимые агенту

​

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

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