---
read_when:
    - Планирование перехода с BlueBubbles на встроенный плагин iMessage
    - Сопоставление ключей конфигурации BlueBubbles с эквивалентами iMessage
    - Проверка imsg перед включением плагина iMessage
summary: 'Перенос старых конфигураций BlueBubbles во встроенный плагин iMessage: сопоставление ключей, правила допуска для групп и проверка перехода.'
title: Переход с BlueBubbles
x-i18n:
    generated_at: "2026-07-13T17:52:29Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 24
    provider: openai
    source_hash: b9d1533c356d3901358c25f0b90e6850124f66d3c14f056d90d5723242076d22
    source_path: channels/imessage-from-bluebubbles.md
    workflow: 16
---

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

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

<Note>
Краткое объявление и сводку для операторов см. в разделе [Удаление BlueBubbles и путь iMessage через imsg](/ru/announcements/bluebubbles-imessage).
</Note>

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

Кратчайший безопасный путь, если вы уже знакомы со своей старой конфигурацией 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/imsg
   brew update && brew upgrade imsg
   imsg --version
   imsg 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 -s
   imsg history --chat-id 42 --limit 10 --attachments --json | jq -s
   imsg watch --chat-id 42 --reactions --json
   imsg 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](/ru/channels/imessage#requirements-and-permissions-macos).

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

   ```bash
   imsg launch
   imsg status --json
   ```

   Для `imsg launch` требуется отключить SIP (а в современных версиях macOS также ослабить проверку библиотек — см. [Включение закрытого API imsg](/ru/channels/imessage#enabling-the-imsg-private-api)). Базовая отправка, история и отслеживание работают без `imsg launch`, но полный набор действий OpenClaw для iMessage — нет.

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

   ```bash
   openclaw channels status --probe
   ```

   Учётная запись iMessage должна сообщать `works`; при наличии `--json` полезная нагрузка проверки содержит `privateApi.available: true`. Если она сообщает `false`, сначала устраните эту проблему — см. [Определение возможностей](/ru/channels/imessage#private-api-actions). Для проверки требуется доступный 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 мс. См. [Объединение личных сообщений, отправленных частями](/ru/channels/imessage#coalescing-split-send-dms-command--url-in-one-composition). |
| `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 restart
   openclaw channels status --probe --channel imessage   # ожидается "works"; --json показывает privateApi.available: true
   ```

   Для проверки требуется доступный Gateway; проверяются только настроенные и включённые учётные записи. Чтобы проверить сам Mac, используйте прямые команды `imsg` из раздела [Перед началом работы](#before-you-start).

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](https://github.com/openclaw/openclaw/issues/51892))       |
| Tapback (`react`)                        | ✅                 | ✅                                                                            |
| Редактирование / отмена отправки (получатели на macOS 13+) | ✅                 | ✅                                                                            |
| Отправка с экранным эффектом                        | ✅                 | ✅ (частично закрывает [#9394](https://github.com/openclaw/openclaw/issues/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](/ru/channels/imessage#inbound-recovery-after-a-bridge-or-gateway-restart).

## Сопряжение, сеансы и привязки 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`, если он существует.

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

- [Удаление BlueBubbles и переход на путь iMessage через imsg](/ru/announcements/bluebubbles-imessage) — краткое объявление и сводка для оператора.
- [iMessage](/ru/channels/imessage) — полный справочник по каналу iMessage, включая настройку `imsg launch` и определение возможностей.
- `/channels/bluebubbles` — устаревший URL, перенаправляющий на это руководство по миграции.
- [Сопряжение](/ru/channels/pairing) — аутентификация личных сообщений и процесс сопряжения.
- [Маршрутизация каналов](/ru/channels/channel-routing) — как Gateway выбирает канал для исходящих ответов.