OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Mainstream messaging

Переход с BlueBubbles

Поддержка BlueBubbles удалена. OpenClaw поддерживает iMessage только через встроенный плагин imessage, который управляет steipete/imsg по JSON-RPC и предоставляет доступ к тому же набору закрытых API, что и BlueBubbles (react, edit, unsend, reply, sendWithEffect, нативные опросы, управление группами, вложения). Один исполняемый файл CLI заменяет сервер BlueBubbles, клиентское приложение и инфраструктуру вебхуков: без конечной точки REST и без аутентификации вебхуков.

В этом руководстве описан перенос старых конфигураций channels.bluebubbles в channels.imessage. Других поддерживаемых путей миграции нет. В текущей версии OpenClaw оставшийся блок channels.bluebubbles неактивен — ни один компонент среды выполнения его не читает.

Контрольный список миграции

Кратчайший безопасный путь, если вы уже знакомы со своей старой конфигурацией BlueBubbles:

  1. Проверьте imsg непосредственно на Mac, где работает Messages.app (imsg chats, imsg history, imsg send, imsg rpc --help).
  2. Скопируйте ключи поведения из channels.bluebubbles в channels.imessage: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups, includeAttachments, attachmentRoots, mediaMaxMb, textChunkLimit, coalesceSameSenderDms и actions.
  3. Удалите больше не существующие ключи транспорта: serverUrl, password, URL-адреса вебхуков и настройки сервера BlueBubbles.
  4. Если Gateway работает не на том Mac, где запущен Messages, задайте для channels.imessage.cliPath SSH-обёртку и настройте remoteHost для удалённого получения вложений.
  5. Включите channels.imessage, перезапустите Gateway, затем выполните openclaw channels status --probe --channel imessage.
  6. Проверьте одно личное сообщение, одну разрешённую группу, вложения, если они включены, и каждое действие закрытого API, которое должен использовать агент.
  7. Удалите сервер BlueBubbles и старую конфигурацию channels.bluebubbles после проверки пути iMessage.

Что делает imsg

imsg — локальный CLI для Messages в macOS. OpenClaw запускает imsg rpc как дочерний процесс и обменивается с ним данными по JSON-RPC через stdin/stdout. Нет ни HTTP-сервера, ни URL-адреса вебхука, ни фонового демона, ни агента запуска, ни порта, который нужно открывать.

  • Чтение выполняется из ~/Library/Messages/chat.db с помощью дескриптора SQLite, открытого только для чтения.
  • Входящие сообщения в реальном времени поступают из imsg watch / watch.subscribe, который отслеживает события файловой системы chat.db, используя опрос в качестве резервного механизма.
  • Обычные текстовые сообщения и файлы отправляются посредством автоматизации Messages.app.
  • Для расширенных действий используется imsg launch, который внедряет вспомогательный модуль imsg в Messages.app. Именно это обеспечивает уведомления о прочтении, индикаторы набора текста, форматированную отправку, редактирование, отмену отправки, ответы в ветках, реакции, опросы и управление группами.
  • Сборки Linux могут исследовать скопированный chat.db, но не могут отправлять сообщения, следить за активной базой данных Mac или управлять Messages.app. Для работы OpenClaw с iMessage запускайте imsg на Mac с выполненным входом в систему или через SSH-обёртку для этого Mac.

Перед началом

  1. Установите imsg на Mac, где работает Messages.app:

    bash
    brew install steipete/tap/imsgbrew update && brew upgrade imsgimsg --versionimsg chats --limit 3

    При обычной локальной настройке мастер настройки OpenClaw может предложить подтверждаемую пользователем установку или обновление imsg через Homebrew на Mac с выполненным входом в Messages. Ручная настройка и топологии с SSH-обёрткой остаются под управлением оператора: повторите обновление Homebrew в том же локальном или удалённом пользовательском контексте, в котором будет запускаться imsg. Если imsg chats завершается с ошибкой unable to open database file, пустым выводом или authorization denied, предоставьте полный доступ к диску терминалу, редактору, процессу Node, службе Gateway или родительскому процессу SSH, который запускает imsg, а затем перезапустите этот родительский процесс.

  2. Перед изменением конфигурации OpenClaw проверьте интерфейсы чтения, отслеживания, отправки и RPC:

    bash
    imsg chats --limit 10 --json | jq -simsg history --chat-id 42 --limit 10 --attachments --json | jq -simsg watch --chat-id 42 --reactions --jsonimsg send --chat-id 42 --text "OpenClaw imsg test"imsg rpc --help

    Замените 42 реальным идентификатором чата из imsg chats. Для отправки требуется разрешение на автоматизацию Messages.app. Если OpenClaw будет работать через SSH, выполняйте эти команды через ту же SSH-обёртку или в том же пользовательском контексте, который будет использовать OpenClaw. Если чтение работает, но отправка завершается ошибкой AppleEvents -1743, проверьте, предоставлено ли разрешение на автоматизацию для /usr/libexec/sshd-keygen-wrapper; см. Сбой отправки через SSH-обёртку с ошибкой AppleEvents -1743.

  3. Включите мост закрытого API. Настоятельно рекомендуется сделать это для iMessage в OpenClaw, поскольку от него зависят ответы, реакции, эффекты, опросы, ответы на вложения и действия с группами:

    bash
    imsg launchimsg status --json

    Для imsg launch требуется отключить SIP (а в современных версиях macOS также ослабить проверку библиотек — см. Включение закрытого API imsg). Базовая отправка, история и отслеживание работают без imsg launch, но полный набор действий OpenClaw для iMessage — нет.

  4. После включения channels.imessage и запуска Gateway проверьте мост через OpenClaw:

    bash
    openclaw channels status --probe

    Учётная запись iMessage должна сообщать works; при наличии --json полезная нагрузка проверки содержит privateApi.available: true. Если она сообщает false, сначала устраните эту проблему — см. Определение возможностей. Для проверки требуется доступный Gateway (иначе CLI возвращает только вывод на основе конфигурации); проверяются только настроенные и включённые учётные записи.

  5. Создайте резервную копию конфигурации:

    bash
    cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak

Перенос конфигурации

iMessage и BlueBubbles используют большинство одинаковых ключей поведения на уровне канала. Различаются транспорт (REST-сервер или локальный CLI) и формат ключей реестра групп.

BlueBubbles встроенный iMessage Примечания
channels.bluebubbles.enabled channels.imessage.enabled Та же семантика (по умолчанию true после появления блока).
channels.bluebubbles.serverUrl (удалено) REST-сервера нет — плагин запускает imsg rpc через stdio.
channels.bluebubbles.password (удалено) Аутентификация Webhook не требуется.
(неявно) channels.imessage.cliPath Путь к imsg (по умолчанию imsg); для SSH используйте скрипт-обёртку.
(неявно) channels.imessage.dbPath Необязательное переопределение chat.db для Messages.app; при отсутствии определяется автоматически.
(неявно) channels.imessage.remoteHost host или user@host — требуется только тогда, когда cliPath является обёрткой SSH и нужно получать вложения через SCP.
channels.bluebubbles.dmPolicy channels.imessage.dmPolicy Те же значения (pairing / allowlist / open / disabled); по умолчанию pairing.
channels.bluebubbles.allowFrom channels.imessage.allowFrom Те же форматы адресатов (+15555550123, user@example.com). Одобрения из хранилища сопряжений не переносятся — см. ниже.
channels.bluebubbles.groupPolicy channels.imessage.groupPolicy Те же значения (allowlist / open / disabled); по умолчанию allowlist.
channels.bluebubbles.groupAllowFrom channels.imessage.groupAllowFrom Аналогично. Если значение не задано, iMessage использует allowFrom; явно пустое значение groupAllowFrom: [] блокирует все группы при groupPolicy: "allowlist".
channels.bluebubbles.groups channels.imessage.groups Скопируйте запись с подстановочным знаком "*" без изменений; замените ключи записей отдельных групп на числовые chat_id iMessage — см. «Ловушка реестра групп». requireMention, tools, toolsBySender, systemPrompt переносятся без изменений.
channels.bluebubbles.sendReadReceipts channels.imessage.sendReadReceipts По умолчанию true. Со встроенным плагином срабатывает только при успешной проверке частного API.
channels.bluebubbles.includeAttachments channels.imessage.includeAttachments Та же структура, по умолчанию также отключено. Если в BlueBubbles передавались вложения, задайте это явно — до этого входящие фотографии и медиафайлы незаметно отбрасываются (без строки журнала Inbound message).
channels.bluebubbles.attachmentRoots channels.imessage.attachmentRoots Локальные корневые каталоги; те же правила подстановочных знаков.
(неприменимо) channels.imessage.remoteAttachmentRoots Используется только тогда, когда для получения через SCP задано remoteHost.
channels.bluebubbles.mediaMaxMb channels.imessage.mediaMaxMb По умолчанию в iMessage — 16 МБ (в BlueBubbles по умолчанию было 8 МБ). Задайте явно, чтобы сохранить более низкий предел.
channels.bluebubbles.textChunkLimit channels.imessage.textChunkLimit В обоих случаях по умолчанию 4000.
channels.bluebubbles.coalesceSameSenderDms channels.imessage.coalesceSameSenderDms Так же включается явно. Только для личных сообщений — в группах сохраняется отправка каждого сообщения отдельно. Если не задано messages.inbound.byChannel.imessage или глобальное значение messages.inbound.debounceMs, стандартная задержка объединения входящих сообщений увеличивается до 7000 мс. См. Объединение личных сообщений, отправленных частями.
channels.bluebubbles.enrichGroupParticipantsFromContacts (неприменимо) imsg уже предоставляет отображаемые имена отправителей из chat.db.
channels.bluebubbles.actions.* channels.imessage.actions.* Те же переключатели для отдельных действий (reactions, edit, unsend, reply, sendWithEffect, renameGroup, setGroupIcon, addParticipant, removeParticipant, leaveGroup, sendAttachment) плюс новый polls. Все включены по умолчанию; действия частного API по-прежнему требуют моста.

Конфигурации с несколькими учётными записями (channels.bluebubbles.accounts.*) однозначно преобразуются в channels.imessage.accounts.*.

Ловушка реестра групп

Встроенный плагин iMessage последовательно применяет два фильтра групп. Чтобы групповое сообщение дошло до агента, оно должно пройти оба:

  1. Список разрешённых отправителей / целевых чатов (channels.imessage.groupAllowFrom) — сопоставляет адрес отправителя или целевой чат (записи chat_id:, chat_guid:, chat_identifier:). Если groupAllowFrom не задан, этот фильтр использует allowFrom; явное значение groupAllowFrom: [] отключает такой резервный вариант и отбрасывает все групповые сообщения при groupPolicy: "allowlist".
  2. Реестр групп (channels.imessage.groups) — использует в качестве ключа числовой chat_id iMessage:
    • Блок groups отсутствует (или пуст): группы проходят этот фильтр, если в фильтре 1 действует непустой список разрешённых отправителей; доступ регулируется фильтрацией отправителей, а предупреждение при запуске об отбрасывании всех сообщений не выводится.
    • groups содержит записи, но не "*": проходят только перечисленные ключи chat_id. Добавление любой группы превращает реестр в список разрешённых даже при groupPolicy: "open".
    • groups: { "*": { ... } }: этот фильтр пропускает все группы.

Ловушка миграции: BlueBubbles использовал для записей groups ключи GUID чата / идентификаторы чата, а реестр iMessage использует числовой chat_id. Если дословно скопировать записи отдельных групп, получится непустой реестр с ключами, которые никогда не совпадут, поэтому все групповые сообщения будут отбрасываться фильтром 2. Скопируйте запись с подстановочным знаком "*" без изменений; замените ключи отдельных групп значениями chat_id из imsg chats.

Оба пути отбрасывания видны при стандартном уровне журналирования в строках warn:

  • Один раз для каждой учётной записи при запуске, когда задано groupPolicy: "allowlist", а действующий список разрешённых отправителей групп пуст: imessage: groupPolicy="allowlist" for account "<id>" but no group sender allowlist is configured .... Задайте groupAllowFrom (или allowFrom), чтобы разрешить отправителей; одного добавления groups недостаточно для прохождения фильтра отправителей.
  • Один раз для каждого chat_id во время работы, когда реестр отбрасывает группу: imessage: dropping group message from chat_id=<id> ... not in channels.imessage.groups allowlist с указанием точного ключа, который нужно добавить.

Личные сообщения продолжают работать в любом случае — они обрабатываются другим путём, поэтому успешная работа личных сообщений не подтверждает правильную маршрутизацию групп.

Минимальная конфигурация с ограничением по отправителям при groupPolicy: "allowlist":

json5
{  channels: {    imessage: {      groupPolicy: "allowlist",      groupAllowFrom: ["+15555550123", "chat_guid:any;-;..."],    },  },}

Эта конфигурация разрешает указанным отправителям писать в любой группе. Добавьте записи groups, чтобы ограничить разрешённые чаты или задать параметры отдельных чатов, например requireMention; скопируйте запись BlueBubbles "*" без изменений, но замените ключи отдельных записей числовыми значениями chat_id iMessage.

Пошаговая инструкция

  1. Преобразуйте конфигурацию. Во время редактирования оставьте новый блок отключённым; старый блок channels.bluebubbles игнорируется текущей версией OpenClaw и может оставаться рядом для справки:

    json5
    {  channels: {    imessage: {      enabled: false, // переключите на true, когда будете готовы к переходу      cliPath: "/opt/homebrew/bin/imsg",      dmPolicy: "pairing",      allowFrom: ["+15555550123"], // скопируйте из bluebubbles.allowFrom      groupPolicy: "allowlist",      groupAllowFrom: [], // скопируйте из bluebubbles.groupAllowFrom      groups: { "*": { requireMention: true } }, // подстановочный знак копируется дословно; измените ключи записей отдельных чатов на chat_id      // действия по умолчанию включены; чтобы отключить отдельные действия, задайте соответствующим переключателям false    },  },}

  2. Выполните переход и проверку. Задайте channels.imessage.enabled: true, перезапустите Gateway и убедитесь, что канал сообщает об исправном состоянии:

    bash
    openclaw gateway restartopenclaw channels status --probe --channel imessage   # ожидается "works"; --json показывает privateApi.available: true

    Для проверки требуется доступный Gateway; проверяются только настроенные и включённые учётные записи. Чтобы проверить сам Mac, используйте прямые команды imsg из раздела Перед началом работы.

  3. Проверьте личные сообщения. Отправьте агенту личное сообщение и убедитесь, что ответ доставлен.

  4. Проверьте группы отдельно. Личные сообщения и группы обрабатываются разными путями кода — успешная работа личных сообщений не подтверждает маршрутизацию групповых. Отправьте сообщение в разрешённый групповой чат и убедитесь, что ответ доставлен. Если группа перестала отвечать (нет ни ответа агента, ни ошибки), найдите в журнале Gateway две строки warn из раздела «Опасная особенность реестра групп» выше. Предупреждение при запуске означает, что фактический список разрешённых отправителей пуст; предупреждение для конкретного chat_id означает, что заполненный реестр groups не содержит этот чат.

  5. Проверьте доступные действия. В сопряжённом личном чате попросите агента добавить реакцию, отредактировать и отменить отправку сообщения, ответить, отправить фотографию, а также (в группе) переименовать группу или добавить/удалить участника. Каждое действие должно выполняться нативно в Messages.app. Если какое-либо действие выдаёт iMessage <action> requires the imsg private API bridge, снова выполните imsg launch и обновите с помощью openclaw channels status --probe.

  6. Удалите сервер BlueBubbles и блок channels.bluebubbles, когда проверите личные сообщения, группы и действия iMessage. OpenClaw не читает channels.bluebubbles.

Краткое сравнение доступных действий

Действие устаревший BlueBubbles встроенный iMessage
Отправка текста / резервная отправка через SMS ✅ ✅
Отправка медиафайлов (фото, видео, файл, голосовое сообщение) ✅ ✅
Ответ в ветке (reply_to_guid) ✅ ✅ (закрывает #51892)
Tapback (react) ✅ ✅
Редактирование / отмена отправки (получатели на macOS 13+) ✅ ✅
Отправка с экранным эффектом ✅ ✅ (частично закрывает #9394)
Форматирование текста: полужирный / курсив / подчёркивание / зачёркивание ✅ ✅ (форматирование типизированных сегментов через attributedBody)
Нативные опросы Messages (создание и голосование) ❌ ✅ (actions.polls; для нативного отображения получателям требуется iOS/macOS 26+)
Переименование группы / установка значка группы ✅ ✅
Добавление / удаление участника, выход из группы ✅ ✅
Уведомления о прочтении и индикатор набора текста ✅ ✅ (доступность определяется проверкой закрытого API)
Объединение личных сообщений от одного отправителя ✅ ✅ (только для личных сообщений; включается через channels.imessage.coalesceSameSenderDms)
Восстановление входящих сообщений после перезапуска ✅ ✅ (автоматически: повторное воспроизведение since_rowid + дедупликация по GUID; более широкое окно при локальном развёртывании)

iMessage восстанавливает сообщения, пропущенные во время простоя Gateway: при запуске он повторно воспроизводит сообщения начиная с последнего отправленного rowid через imsg watch.subscribe since_rowid, устраняет дубликаты по GUID, а ограничение по возрасту устаревшей очереди предотвращает «взрыв очереди» при сбросе Push. Это выполняется через RPC-соединение imsg, поэтому работает и в удалённых конфигурациях cliPath через SSH; локальные конфигурации получают более широкое окно восстановления, поскольку могут читать chat.db. См. Восстановление входящих сообщений после перезапуска моста или Gateway.

Сопряжение, сеансы и привязки ACP

  • Списки разрешений переносятся по идентификатору. channels.imessage.allowFrom распознаёт те же строки +15555550123 / user@example.com, которые использовал BlueBubbles, — скопируйте их дословно.
  • Одобрения из хранилища сопряжений не переносятся. Хранилище сопряжений создаётся отдельно для каждого канала, и старое хранилище BlueBubbles не мигрирует. Отправители, одобренные только через сопряжение, должны ещё раз выполнить сопряжение в iMessage, либо вы можете добавить их идентификаторы в allowFrom.
  • Сеансы по-прежнему ограничены конкретным агентом и чатом. При стандартном session.dmScope=main личные сообщения объединяются в основном сеансе агента; групповые сеансы остаются изолированными по chat_id (agent:<agentId>:imessage:group:<chat_id>). Старая история переписки, сохранённая под ключами сеансов BlueBubbles, не переносится в сеансы iMessage.
  • В привязках ACP, ссылающихся на match.channel: "bluebubbles", необходимо заменить значение на "imessage". Форматы match.peer.id (chat_id:, chat_guid:, chat_identifier:, идентификатор без дополнительных элементов) остаются прежними.

Канал для отката отсутствует

Поддерживаемой среды выполнения BlueBubbles, на которую можно вернуться, нет. Если проверка iMessage завершается неудачно, задайте channels.imessage.enabled: false, перезапустите Gateway, устраните препятствие imsg и повторите переход.

Кеш ответов хранится в состоянии плагина SQLite. openclaw doctor --fix импортирует и архивирует старый вспомогательный файл imessage/reply-cache.jsonl, если он существует.

Связанные материалы

Was this useful?
On this page

On this page