iMessage

​

Быстрая настройка

brew install steipete/tap/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>

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

imsg chats --limit 1
# or
imsg send <handle> "test"

Not authorized to send Apple events to 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, 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
   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 в 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, поэтому набор действий, который вы видите в списке инструментов агента, отражает то, что мост действительно может делать на этом хосте.

​

Когда нельзя отключить 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: { "*": { "requireMention": true } },
    },
  },
}

{
  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

• Выполните /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,
      },
    },
  },
}

{
  channels: {
    imessage: {
      sendReadReceipts: false,
    },
  },
}

​

Запись конфигурации

{
  channels: {
    imessage: {
      configWrites: false,
    },
  },
}

​

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

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

{
  channels: {
    imessage: {
      coalesceSameSenderDms: true, // opt in (default: false)
    },
  },
}

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

​

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

​

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

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

​

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

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

​

Миграция

​

Устранение неполадок

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