iMessage (imsg)

Статус: внешняя интеграция CLI. Gateway запускает imsg rpc (JSON-RPC через stdio).

Быстрая настройка (для начинающих)

  1. Убедитесь, что Messages подключен на этом Mac.
  2. Установите imsg:
    • brew install steipete/tap/imsg
  3. Настройте OpenClaw с channels.imessage.cliPath и channels.imessage.dbPath.
  4. Запустите gateway и утвердите любые запросы macOS (Automation + Full Disk Access).

Минимальная конфигурация:

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

Что это

  • Канал iMessage, поддерживаемый imsg на macOS.
  • Детерминированная маршрутизация: ответы всегда возвращаются в iMessage.
  • Личные сообщения используют основную сессию агента; группы изолированы (agent:<agentId>:imessage:group:<chat_id>).
  • Если приходит поток с несколькими участниками с is_group=false, вы все равно можете изолировать его по chat_id, используя channels.imessage.groups (см. "Группоподобные потоки" ниже).

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

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

Отключите с помощью:

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

Требования

  • macOS с подключенным Messages.
  • Full Disk Access для OpenClaw + imsg (доступ к БД Messages).
  • Разрешение Automation при отправке.
  • channels.imessage.cliPath может указывать на любую команду, проксирующую stdin/stdout (например, скрипт-обертка, который использует SSH на другой Mac и запускает imsg rpc).

Настройка (быстрый путь)

  1. Убедитесь, что Messages подключен на этом Mac.
  2. Настройте iMessage и запустите gateway.

Выделенный macOS пользователь для бота (для изолированной идентичности)

Если вы хотите, чтобы бот отправлял с отдельной идентичностью iMessage (и сохранял ваш личный Messages чистым), используйте выделенный Apple ID + выделенного macOS пользователя.

  1. Создайте выделенный Apple ID (пример: [email protected]).
    • Apple может потребовать номер телефона для проверки / 2FA.
  2. Создайте macOS пользователя (пример: openclawhome) и войдите в него.
  3. Откройте Messages в этом macOS пользователе и войдите в iMessage, используя Apple ID бота.
  4. Включите Remote Login (Системные настройки → Общие → Общий доступ → Remote Login).
  5. Установите imsg:
    • brew install steipete/tap/imsg
  6. Настройте SSH так, чтобы ssh <bot-macos-user>@localhost true работал без пароля.
  7. Направьте channels.imessage.accounts.bot.cliPath на SSH-обертку, запускающую imsg как пользователь бота.

Примечание при первом запуске: отправка/получение может потребовать GUI-утверждений (Automation + Full Disk Access) в macOS пользователе бота. Если imsg rpc выглядит зависшим или завершается, войдите в этого пользователя (Screen Sharing помогает), запустите однократно imsg chats --limit 1 / imsg send ..., утвердите запросы, затем повторите.

Пример обертки (chmod +x). Замените <bot-macos-user> на ваше фактическое имя пользователя macOS:

#!/usr/bin/env bash
set -euo pipefail

# Сначала запустите интерактивный SSH один раз для принятия ключей хоста:
#   ssh <bot-macos-user>@localhost true
exec /usr/bin/ssh -o BatchMode=yes -o ConnectTimeout=5 -T <bot-macos-user>@localhost \
  "/usr/local/bin/imsg" "$@"

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

{
  channels: {
    imessage: {
      enabled: true,
      accounts: {
        bot: {
          name: "Bot",
          enabled: true,
          cliPath: "/path/to/imsg-bot",
          dbPath: "/Users/<bot-macos-user>/Library/Messages/chat.db"
        }
      }
    }
  }
}

Для настроек с одним аккаунтом используйте плоские параметры (channels.imessage.cliPath, channels.imessage.dbPath) вместо карты accounts.

Удаленный/SSH вариант (опционально)

Если вы хотите iMessage на другом Mac, установите channels.imessage.cliPath на обертку, которая запускает imsg на удаленном macOS хосте через SSH. OpenClaw нужен только stdio.

Пример обертки:

#!/usr/bin/env bash
exec ssh -T gateway-host imsg "$@"

Удаленные вложения: Когда cliPath указывает на удаленный хост через SSH, пути вложений в базе данных Messages ссылаются на файлы на удаленной машине. OpenClaw может автоматически получать их через SCP, установив channels.imessage.remoteHost:

{
  channels: {
    imessage: {
      cliPath: "~/imsg-ssh",                     // SSH-обертка на удаленный Mac
      remoteHost: "user@gateway-host",           // для передачи файлов SCP
      includeAttachments: true
    }
  }
}

Если remoteHost не установлен, OpenClaw пытается автоматически обнаружить его, разбирая команду SSH в вашем скрипте-обертке. Явная конфигурация рекомендуется для надежности.

Удаленный Mac через Tailscale (пример)

Если Gateway работает на Linux хосте/VM, но iMessage должен работать на Mac, Tailscale — самый простой мост: Gateway общается с Mac через tailnet, запускает imsg через SSH и копирует вложения обратно через SCP.

Архитектура:

┌──────────────────────────────┐          SSH (imsg rpc)          ┌──────────────────────────┐
│ Хост Gateway (Linux/VM)      │──────────────────────────────────▶│ Mac с Messages + imsg    │
│ - openclaw gateway           │          SCP (вложения)          │ - Messages подключен     │
│ - channels.imessage.cliPath  │◀──────────────────────────────────│ - Remote Login включен   │
└──────────────────────────────┘                                   └──────────────────────────┘
              ▲
              │ Tailscale tailnet (hostname или 100.x.y.z)
              ▼
        user@gateway-host

Конкретный пример конфигурации (Tailscale hostname):

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

Пример обертки (~/.openclaw/scripts/imsg-ssh):

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

Примечания:

  • Убедитесь, что Mac подключен к Messages, и Remote Login включен.
  • Используйте SSH-ключи, чтобы ssh [email protected] работал без запросов.
  • remoteHost должен соответствовать цели SSH, чтобы SCP мог получать вложения.

Поддержка нескольких аккаунтов: используйте channels.imessage.accounts с конфигурацией для каждого аккаунта и опциональным name. См. gateway/configuration для общего паттерна. Не коммитьте ~/.openclaw/openclaw.json (он часто содержит токены).

Контроль доступа (личные сообщения + группы)

Личные сообщения:

  • По умолчанию: channels.imessage.dmPolicy = "pairing".
  • Неизвестные отправители получают код сопряжения; сообщения игнорируются до утверждения (коды истекают через 1 час).
  • Утвердите через:
    • openclaw pairing list imessage
    • openclaw pairing approve imessage <CODE>
  • Сопряжение — это обмен токенами по умолчанию для личных сообщений iMessage. Подробности: Сопряжение

Группы:

  • channels.imessage.groupPolicy = open | allowlist | disabled.
  • channels.imessage.groupAllowFrom контролирует, кто может вызывать в группах при установке allowlist.
  • Контроль упоминаний использует agents.list[].groupChat.mentionPatterns (или messages.groupChat.mentionPatterns), потому что iMessage не имеет нативных метаданных упоминаний.
  • Переопределение нескольких агентов: установите паттерны для каждого агента на agents.list[].groupChat.mentionPatterns.

Как это работает (поведение)

  • imsg транслирует события сообщений; gateway нормализует их в общий конверт канала.
  • Ответы всегда маршрутизируются обратно к тому же chat id или handle.

Группоподобные потоки (is_group=false)

Некоторые потоки iMessage могут иметь нескольких участников, но все равно приходить с is_group=false в зависимости от того, как Messages хранит идентификатор чата.

Если вы явно настроите chat_id в channels.imessage.groups, OpenClaw будет обрабатывать этот поток как "группу" для:

  • изоляции сессии (отдельный ключ сессии agent:<agentId>:imessage:group:<chat_id>)
  • поведения белых списков групп / контроля упоминаний

Пример:

{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: {
        "42": { "requireMention": false }
      }
    }
  }
}

Это полезно, когда вы хотите изолированную личность/модель для конкретного потока (см. Маршрутизация нескольких агентов). Для изоляции файловой системы см. Sandboxing.

Медиа + лимиты

  • Опциональный прием вложений через channels.imessage.includeAttachments.
  • Ограничение медиа через channels.imessage.mediaMaxMb.

Ограничения

  • Исходящий текст разбивается на части до channels.imessage.textChunkLimit (по умолчанию 4000).
  • Опциональное разбиение по новым строкам: установите channels.imessage.chunkMode="newline" для разделения на пустых строках (границы параграфов) перед разбиением по длине.
  • Загрузки медиа ограничены channels.imessage.mediaMaxMb (по умолчанию 16).

Адресация / цели доставки

Предпочитайте chat_id для стабильной маршрутизации:

  • chat_id:123 (предпочтительно)
  • chat_guid:...
  • chat_identifier:...
  • прямые handles: imessage:+1555 / sms:+1555 / [email protected]

Список чатов:

imsg chats --limit 20

Справочник конфигурации (iMessage)

Полная конфигурация: Конфигурация

Параметры провайдера:

  • channels.imessage.enabled: включить/отключить запуск канала.
  • channels.imessage.cliPath: путь к imsg.
  • channels.imessage.dbPath: путь к БД Messages.
  • channels.imessage.remoteHost: SSH хост для передачи вложений SCP, когда cliPath указывает на удаленный Mac (например, user@gateway-host). Автоматически обнаруживается из SSH-обертки, если не установлен.
  • channels.imessage.service: imessage | sms | auto.
  • channels.imessage.region: регион SMS.
  • channels.imessage.dmPolicy: pairing | allowlist | open | disabled (по умолчанию: pairing).
  • channels.imessage.allowFrom: белый список личных сообщений (handles, email, номера E.164 или chat_id:*). open требует "*". iMessage не имеет имен пользователей; используйте handles или цели чата.
  • channels.imessage.groupPolicy: open | allowlist | disabled (по умолчанию: allowlist).
  • channels.imessage.groupAllowFrom: белый список отправителей группы.
  • channels.imessage.historyLimit / channels.imessage.accounts.*.historyLimit: макс сообщений группы для включения в качестве контекста (0 отключает).
  • channels.imessage.dmHistoryLimit: лимит истории личных сообщений в пользовательских обращениях. Переопределения для конкретного пользователя: channels.imessage.dms["<handle>"].historyLimit.
  • channels.imessage.groups: значения по умолчанию для каждой группы + белый список (используйте "*" для глобальных значений по умолчанию).
  • channels.imessage.includeAttachments: принимать вложения в контекст.
  • channels.imessage.mediaMaxMb: ограничение входящих/исходящих медиа (МБ).
  • channels.imessage.textChunkLimit: размер исходящего фрагмента (символы).
  • channels.imessage.chunkMode: length (по умолчанию) или newline для разделения на пустых строках (границы параграфов) перед разбиением по длине.

Связанные глобальные параметры:

  • agents.list[].groupChat.mentionPatterns (или messages.groupChat.mentionPatterns).
  • messages.responsePrefix.
← Назад к документации