iMessage (застаріле: imsg)

Для нових розгортань iMessage використовуйте BlueBubbles.Інтеграція imsg є застарілою та може бути видалена в одному з майбутніх випусків.

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

BlueBubbles (рекомендовано)

Бажаний шлях iMessage для нових налаштувань.

Прив’язка

Для приватних повідомлень iMessage типово використовується режим прив’язки.

Довідник з конфігурації

Повний довідник полів iMessage.

Швидке налаштування

Локальний Mac (швидкий шлях)
Віддалений Mac через SSH

Установіть і перевірте imsg

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

Налаштуйте OpenClaw

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

Запустіть gateway

openclaw gateway

Підтвердьте першу прив’язку приватного повідомлення (типова `dmPolicy`)

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

Запити на прив’язку спливають через 1 годину.

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).
Для надсилання повідомлень через Messages.app потрібен дозвіл Automation.

Дозволи надаються для кожного контексту процесу окремо. Якщо gateway працює без графічного інтерфейсу (LaunchAgent/SSH), виконайте одноразову інтерактивну команду в цьому самому контексті, щоб викликати підказки:

imsg chats --limit 1
# або
imsg send <handle> "test"

Керування доступом і маршрутизація

Політика приватних повідомлень
Політика груп + згадки
Сесії та детерміновані відповіді

channels.imessage.dmPolicy керує прямими повідомленнями:

pairing (типово)
allowlist
open (потрібно, щоб allowFrom включав "*")
disabled

Поле allowlist: channels.imessage.allowFrom.Записи allowlist можуть бути дескрипторами або цілями чату (chat_id:*, chat_guid:*, chat_identifier:*).

channels.imessage.groupPolicy керує обробкою груп:

allowlist (типово, якщо налаштовано)
open
disabled

Allowlist відправників груп: channels.imessage.groupAllowFrom.Резервний механізм під час виконання: якщо groupAllowFrom не задано, перевірки відправників груп iMessage повертаються до allowFrom, якщо він доступний. Примітка щодо виконання: якщо channels.imessage повністю відсутній, середовище виконання повертається до groupPolicy="allowlist" і записує попередження в журнал (навіть якщо задано channels.defaults.groupPolicy).Керування згадками для груп:

iMessage не має вбудованих метаданих згадок
виявлення згадок використовує regex-шаблони (agents.list[].groupChat.mentionPatterns, резервно — messages.groupChat.mentionPatterns)
без налаштованих шаблонів керування згадками неможливо забезпечити

Керівні команди від авторизованих відправників можуть обходити вимогу згадки в групах.

Для приватних повідомлень використовується пряма маршрутизація; для груп — групова.
За типовим session.dmScope=main приватні повідомлення iMessage зводяться до основної сесії агента.
Групові сесії ізольовані (agent:<agentId>:imessage:group:<chat_id>).
Відповіді маршрутизуються назад в iMessage з використанням метаданих каналу/цілі походження.

Поведінка потоків, схожих на групові:Деякі багатокористувацькі потоки iMessage можуть надходити з is_group=false. Якщо такий chat_id явно налаштований у channels.imessage.groups, OpenClaw обробляє його як груповий трафік (керування групами + ізоляція групової сесії).

Прив’язки розмов ACP

Застарілі чати iMessage також можна прив’язувати до сесій ACP. Швидкий операторський сценарій:

Виконайте /acp spawn codex --bind here у приватному повідомленні або дозволеному груповому чаті.
Подальші повідомлення в цій самій розмові iMessage маршрутизуються до створеної сесії ACP.
/new і /reset скидають цю саму прив’язану сесію ACP на місці.
/acp close закриває сесію ACP і видаляє прив’язку.

Налаштовані постійні прив’язки підтримуються через записи верхнього рівня bindings[] з type: "acp" і match.channel: "imessage". match.peer.id може використовувати:

нормалізований дескриптор приватного повідомлення, наприклад +15555550123 або user@example.com
chat_id:<id> (рекомендовано для стабільних групових прив’язок)
chat_guid:<guid>
chat_identifier:<identifier>

Приклад:

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: { agent: "codex", backend: "acpx", mode: "persistent" },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "imessage",
        accountId: "default",
        peer: { kind: "group", id: "chat_id:123" },
      },
      acp: { label: "codex-group" },
    },
  ],
}

Див. ACP Agents щодо спільної поведінки прив’язок ACP.

Сценарії розгортання

Виділений користувач macOS для бота (окрема ідентичність iMessage)

Використовуйте окремий Apple ID і користувача macOS, щоб трафік бота був ізольований від вашого особистого профілю Messages.Типовий сценарій:

Створіть окремого користувача macOS і ввійдіть у нього.
Увійдіть у Messages з Apple ID бота в цьому користувачі.
Установіть imsg у цього користувача.
Створіть SSH-обгортку, щоб OpenClaw міг запускати imsg у контексті цього користувача.
Вкажіть channels.imessage.accounts.<id>.cliPath і .dbPath на профіль цього користувача.

Перший запуск може вимагати підтверджень у графічному інтерфейсі (Automation + Full Disk Access) у сесії цього користувача бота.

Віддалений Mac через Tailscale (приклад)

Поширена топологія:

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

Приклад:

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "bot@mac-mini.tailnet-1234.ts.net",
      includeAttachments: true,
      dbPath: "/Users/bot/Library/Messages/chat.db",
    },
  },
}

#!/usr/bin/env bash
exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"

Використовуйте ключі SSH, щоб і SSH, і SCP були неінтерактивними. Спочатку переконайтеся, що ключ хоста довірений (наприклад, ssh bot@mac-mini.tailnet-1234.ts.net), щоб заповнити known_hosts.

Шаблон із кількома обліковими записами

iMessage підтримує конфігурацію для кожного облікового запису окремо в channels.imessage.accounts.Для кожного облікового запису можна перевизначити такі поля, як cliPath, dbPath, allowFrom, groupPolicy, mediaMaxMb, налаштування історії та allowlist коренів вкладень.

Медіа, фрагментація та цілі доставки

Вкладення та медіа

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

Фрагментація вихідних повідомлень

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

Формати адресації

Бажані явні цілі:

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

Також підтримуються цілі-дескриптори:

imessage:+1555...
sms:+1555...
user@example.com

imsg chats --limit 20

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

iMessage типово дозволяє ініційований каналом запис конфігурації (для /config set|unset, коли commands.config: true). Вимкнення:

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

Усунення несправностей

imsg не знайдено або RPC не підтримується

Перевірте бінарний файл і підтримку 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
поведінку allowlist для channels.imessage.groups
налаштування шаблонів згадок (agents.list[].groupChat.mentionPatterns)

Віддалені вкладення не працюють

Перевірте:

channels.imessage.remoteHost
channels.imessage.remoteAttachmentRoots
автентифікацію ключами SSH/SCP з хоста gateway
наявність ключа хоста в ~/.ssh/known_hosts на хості gateway
читабельність віддаленого шляху на Mac, де працює Messages

Підказки дозволів macOS були пропущені

Повторно виконайте в інтерактивному GUI-терміналі в тому самому контексті користувача/сесії та підтвердьте підказки:

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

Переконайтеся, що Full Disk Access і Automation надано для контексту процесу, у якому працює OpenClaw/imsg.

Вказівники на довідкові матеріали з конфігурації

Пов’язане

Огляд каналів — усі підтримувані канали
Прив’язка — автентифікація приватних повідомлень і сценарій прив’язки
Групи — поведінка групового чату та керування згадками
Маршрутизація каналів — маршрутизація сесій для повідомлень
Безпека — модель доступу та посилення захисту

Overview

Messaging platforms

Configuration

iMessage

iMessage (застаріле: imsg)

BlueBubbles (рекомендовано)

Прив’язка

Довідник з конфігурації

Швидке налаштування

Вимоги та дозволи (macOS)

Керування доступом і маршрутизація

Прив’язки розмов ACP

Сценарії розгортання

Медіа, фрагментація та цілі доставки

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

Усунення несправностей

Вказівники на довідкові матеріали з конфігурації

Пов’язане

Overview

Messaging platforms

Configuration

​iMessage (застаріле: imsg)

BlueBubbles (рекомендовано)

Прив’язка

Довідник з конфігурації

​Швидке налаштування

​Вимоги та дозволи (macOS)

​Керування доступом і маршрутизація

​Прив’язки розмов ACP

​Сценарії розгортання

​Медіа, фрагментація та цілі доставки

​Запис конфігурації

​Усунення несправностей

​Вказівники на довідкові матеріали з конфігурації

​Пов’язане

iMessage (застаріле: imsg)

Швидке налаштування

Вимоги та дозволи (macOS)

Керування доступом і маршрутизація

Прив’язки розмов ACP

Сценарії розгортання

Медіа, фрагментація та цілі доставки

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

Усунення несправностей

Вказівники на довідкові матеріали з конфігурації

Пов’язане