iMessage (устаревший: imsg)

Предупреждение: Для новых развёртываний iMessage используйте BlueBubbles.

Интеграция imsg является устаревшей и может быть удалена в будущей версии.

Статус: устаревшая интеграция через внешний CLI. Шлюз запускает imsg rpc и взаимодействует по JSON-RPC через stdio (без отдельного демона/порта).

• BlueBubbles (рекомендуется) — Предпочтительный путь iMessage для новых установок.
• Спаривание — ЛС iMessage по умолчанию используют режим спаривания.
• Справочник конфигурации — Полный справочник полей iMessage.

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

Локальный Mac (быстрый путь)

  ### Шаг 1: Установите и проверьте imsg

brew install steipete/tap/imsg
imsg rpc --help

  ### Шаг 2: Настройте OpenClaw

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "/usr/local/bin/imsg",
      dbPath: "/Users/<you>/Library/Messages/chat.db",
    },
  },
}

  ### Шаг 3: Запустите шлюз

openclaw gateway

  ### Шаг 4: Подтвердите первое спаривание ЛС (политика dmPolicy по умолчанию)

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

    Запросы спаривания истекают через 1 час.

Удалённый Mac через SSH

OpenClaw требует только stdio-совместимый `cliPath`, поэтому можно указать `cliPath` на скрипт-обёртку, которая подключается по SSH к удалённому Mac и запускает `imsg`.

#!/usr/bin/env bash
exec ssh -T gateway-host 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"],
    },
  },
}

Если `remoteHost` не задан, OpenClaw пытается определить его автоматически, анализируя SSH-обёртку.
`remoteHost` должен быть `host` или `user@host` (без пробелов или SSH-опций).
OpenClaw использует строгую проверку ключей хоста для SCP, поэтому ключ удалённого хоста должен уже существовать в `~/.ssh/known_hosts`.
Пути вложений проверяются по разрешённым корням (`attachmentRoots` / `remoteAttachmentRoots`).

Требования и разрешения (macOS)

• Messages должен быть авторизован на Mac, где запущен imsg.
• Для контекста процесса, запускающего OpenClaw/imsg, требуется Full Disk Access (доступ к БД Messages).
• Разрешение Automation требуется для отправки сообщений через Messages.app.

Совет: Разрешения выдаются по контексту процесса. Если шлюз работает headless (LaunchAgent/SSH), выполните одноразовую интерактивную команду в том же контексте для активации запросов:

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

Контроль доступа и маршрутизация

Политика ЛС

`channels.imessage.dmPolicy` управляет прямыми сообщениями:

- `pairing` (по умолчанию)
- `allowlist`
- `open` (требуется `allowFrom` с `"*"`)
- `disabled`

Поле списка доступа: `channels.imessage.allowFrom`.

Записи списка доступа могут быть хэндлами или целями чата (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`).

Групповая политика + упоминания

`channels.imessage.groupPolicy` управляет обработкой групп:

- `allowlist` (по умолчанию при настройке)
- `open`
- `disabled`

Список доступа отправителей в группах: `channels.imessage.groupAllowFrom`.

Fallback: если `groupAllowFrom` не задан, проверки отправителей в группах iMessage используют fallback к `allowFrom` при наличии.
Примечание: если `channels.imessage` полностью отсутствует, runtime использует fallback к `groupPolicy="allowlist"` и логирует предупреждение (даже если задан `channels.defaults.groupPolicy`).

Гейтинг по упоминанию для групп:

- iMessage не имеет нативных метаданных упоминаний
- обнаружение упоминаний использует regex-паттерны (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`)
- без настроенных паттернов гейтинг по упоминанию не может быть применён

Управляющие команды от авторизованных отправителей могут обходить гейтинг по упоминанию в группах.

Сессии и детерминированные ответы

- ЛС используют прямую маршрутизацию; группы — групповую.
- При `session.dmScope=main` по умолчанию ЛС iMessage объединяются в основную сессию агента.
- Групповые сессии изолированы (`agent:<agentId>:imessage:group:<chat_id>`).
- Ответы маршрутизируются обратно в iMessage по метаданным исходного канала/цели.

Поведение «групповых» потоков:

Некоторые многопользовательские потоки iMessage могут приходить с `is_group=false`.
Если этот `chat_id` явно настроен под `channels.imessage.groups`, OpenClaw обрабатывает его как групповой трафик (групповой гейтинг + изоляция групповой сессии).

Паттерны развёртывания

Используйте выделенный Apple ID и пользователя macOS для изоляции трафика бота от личного профиля Messages.

Типичный процесс:

1. Создайте/войдите под выделенным пользователем macOS.
2. Войдите в Messages с Apple ID бота в этом пользователе.
3. Установите `imsg` для этого пользователя.
4. Создайте SSH-обёртку, чтобы OpenClaw мог запускать `imsg` в контексте этого пользователя.
5. Укажите `channels.imessage.accounts.<id>.cliPath` и `.dbPath` на профиль этого пользователя.

Первый запуск может потребовать GUI-подтверждений (Automation + Full Disk Access) в сессии бот-пользователя.

Типичная топология:

- шлюз работает на Linux/VM
- iMessage + `imsg` работают на Mac в вашем tailnet
- `cliPath`-обёртка использует SSH для запуска `imsg`
- `remoteHost` включает загрузку вложений через SCP

Пример:

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "[email protected]",
      includeAttachments: true,
      dbPath: "/Users/bot/Library/Messages/chat.db",
    },
  },
}

#!/usr/bin/env bash
exec ssh -T [email protected] imsg "$@"

Используйте SSH-ключи для неинтерактивности SSH и SCP.
Сначала убедитесь, что ключ хоста доверен (например, `ssh [email protected]`), чтобы `known_hosts` был заполнен.

iMessage поддерживает конфигурацию по аккаунтам через `channels.imessage.accounts`.

Каждый аккаунт может переопределять поля: `cliPath`, `dbPath`, `allowFrom`, `groupPolicy`, `mediaMaxMb`, настройки истории и корни вложений.

Медиа, разбивка и цели доставки

- загрузка входящих вложений необязательна: `channels.imessage.includeAttachments`
- удалённые пути вложений могут загружаться через SCP при задании `remoteHost`
- пути вложений должны соответствовать разрешённым корням:
  - `channels.imessage.attachmentRoots` (локальные)
  - `channels.imessage.remoteAttachmentRoots` (удалённый режим SCP)
  - паттерн корня по умолчанию: `/Users/*/Library/Messages/Attachments`
- SCP использует строгую проверку ключей хоста (`StrictHostKeyChecking=yes`)
- размер исходящего медиа: `channels.imessage.mediaMaxMb` (по умолчанию 16 МБ)

- лимит текстового чанка: `channels.imessage.textChunkLimit` (по умолчанию 4000)
- режим разбивки: `channels.imessage.chunkMode`
  - `length` (по умолчанию)
  - `newline` (разделение по абзацам)

Предпочтительные явные цели:

- `chat_id:123` (рекомендуется для стабильной маршрутизации)
- `chat_guid:...`
- `chat_identifier:...`

Цели по хэндлам также поддерживаются:

- `imessage:+1555...`
- `sms:+1555...`
- `[email protected]`

imsg chats --limit 20

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

iMessage по умолчанию разрешает запись конфигурации из канала (для /config set|unset при commands.config: true).

Отключение:

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

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

Проверьте бинарник и поддержку RPC:

imsg rpc --help
openclaw channels status --probe

Если probe сообщает, что RPC не поддерживается, обновите `imsg`.

Проверьте:

- `channels.imessage.dmPolicy`
- `channels.imessage.allowFrom`
- подтверждения спаривания (`openclaw pairing list imessage`)

Проверьте:

- `channels.imessage.groupPolicy`
- `channels.imessage.groupAllowFrom`
- поведение списка доступа `channels.imessage.groups`
- конфигурацию паттернов упоминания (`agents.list[].groupChat.mentionPatterns`)

Проверьте:

- `channels.imessage.remoteHost`
- `channels.imessage.remoteAttachmentRoots`
- SSH/SCP ключевую аутентификацию с хоста шлюза
- ключ хоста в `~/.ssh/known_hosts` на хосте шлюза
- читаемость удалённого пути на Mac с Messages

Повторно запустите в интерактивном GUI-терминале в том же контексте пользователя/сессии и подтвердите запросы:

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

Подтвердите, что Full Disk Access + Automation предоставлены для контекста процесса, запускающего OpenClaw/`imsg`.

Ссылки на конфигурацию

• Справочник конфигурации - iMessage
• Конфигурация шлюза
• Спаривание
• BlueBubbles