Переход с 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

• Чтение выполняется из ~/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:
   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:
   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.
3. Включите мост закрытого API. Настоятельно рекомендуется сделать это для iMessage в OpenClaw, поскольку от него зависят ответы, реакции, эффекты, опросы, ответы на вложения и действия с группами:
   imsg launch
   imsg status --json
   
   Для imsg launch требуется отключить SIP (а в современных версиях macOS также ослабить проверку библиотек — см. Включение закрытого API imsg). Базовая отправка, история и отслеживание работают без imsg launch, но полный набор действий OpenClaw для iMessage — нет.
4. После включения channels.imessage и запуска Gateway проверьте мост через OpenClaw:
   openclaw channels status --probe
   
   Учётная запись iMessage должна сообщать works; при наличии --json полезная нагрузка проверки содержит privateApi.available: true. Если она сообщает false, сначала устраните эту проблему — см. Определение возможностей. Для проверки требуется доступный Gateway (иначе CLI возвращает только вывод на основе конфигурации); проверяются только настроенные и включённые учётные записи.
5. Создайте резервную копию конфигурации:
   cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
   

​

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

​

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

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: { "*": { ... } }: этот фильтр пропускает все группы.

• Один раз для каждой учётной записи при запуске, когда задано 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 с указанием точного ключа, который нужно добавить.

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

​

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

1. Преобразуйте конфигурацию. Во время редактирования оставьте новый блок отключённым; старый блок channels.bluebubbles игнорируется текущей версией OpenClaw и может оставаться рядом для справки:
   {
     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 и убедитесь, что канал сообщает об исправном состоянии:
   openclaw gateway restart
   openclaw 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.

​

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

​

Сопряжение, сеансы и привязки 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 через imsg — краткое объявление и сводка для оператора.
• iMessage — полный справочник по каналу iMessage, включая настройку imsg launch и определение возможностей.
• /channels/bluebubbles — устаревший URL, перенаправляющий на это руководство по миграции.
• Сопряжение — аутентификация личных сообщений и процесс сопряжения.
• Маршрутизация каналов — как Gateway выбирает канал для исходящих ответов.