iMessage

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

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

brew install steipete/tap/imsg
imsg rpc --help
imsg launch
openclaw channels status --probe

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

openclaw gateway

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

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

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "user@gateway-host", // used for SCP attachment fetches
      includeAttachments: true,
      // Optional: override allowed attachment roots.
      // Defaults include /Users/*/Library/Messages/Attachments
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
    },
  },
}

​

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

• На Mac, де запускається imsg, має бути виконано вхід у Messages.
• Для контексту процесу, що запускає OpenClaw/imsg, потрібен повний доступ до диска (доступ до БД Messages).
• Для надсилання повідомлень через Messages.app потрібен дозвіл на автоматизацію.
• Для розширених дій (реакція / редагування / скасування надсилання / відповідь у треді / ефекти / групові операції) потрібно вимкнути System Integrity Protection — див. Увімкнення приватного API imsg нижче. Базове надсилання й отримання тексту та медіа працює без цього.

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

​

Увімкнення приватного API imsg

• Базовий режим (типовий, зміни SIP не потрібні): вихідні текст і медіа через send, вхідне спостереження/історія, список чатів. Це те, що ви отримуєте одразу після свіжого brew install steipete/tap/imsg плюс стандартні дозволи macOS, наведені вище.
• Режим приватного API: imsg інжектує допоміжну dylib у Messages.app, щоб викликати внутрішні функції IMCore. Саме це розблоковує react, edit, unsend, reply (у треді), sendWithEffect, renameGroup, setGroupIcon, addParticipant, removeParticipant, leaveGroup, а також індикатори введення та сповіщення про прочитання.

Розширені можливості, як-от read, typing, launch, розширене надсилання через міст, зміна повідомлень і керування чатами, вмикаються явно. Вони потребують вимкненого SIP і допоміжної dylib, інжектованої в Messages.app. imsg launch відмовляється виконувати інжекцію, коли SIP увімкнено.

​

Налаштування

1. Установіть (або оновіть) imsg на Mac, де працює Messages.app:
   brew install steipete/tap/imsg
   imsg --version
   imsg status --json
   
   Вивід imsg status --json повідомляє bridge_version, rpc_methods і selectors для кожного методу, щоб ви могли побачити, що підтримує поточна збірка, перш ніж почати.
2. Вимкніть System Integrity Protection. Це залежить від версії macOS, бо базова вимога Apple залежить від ОС і обладнання:
   • macOS 10.13–10.15 (Sierra–Catalina): вимкніть Library Validation через Terminal, перезавантажтеся в Recovery Mode, виконайте csrutil disable, перезапустіть.
   • macOS 11+ (Big Sur і новіші), Intel: Recovery Mode (або Internet Recovery), csrutil disable, перезапустіть.
   • macOS 11+, Apple Silicon: послідовність запуску з кнопкою живлення для входу в Recovery; у новіших версіях macOS утримуйте клавішу Left Shift, коли натискаєте Continue, потім csrutil disable. Налаштування віртуальних машин мають окремий процес — спочатку зробіть знімок VM.
   • macOS 26 / Tahoe: політики library-validation і перевірки приватних entitlement для imagent стали ще суворішими; imsg може потребувати оновленої збірки, щоб не відставати. Якщо інжекція imsg launch або конкретні selectors починають повертати false після великого оновлення macOS, перевірте примітки до випуску imsg, перш ніж вважати, що крок SIP успішно виконано.
   Дотримуйтеся процесу Apple Recovery-mode для вашого Mac, щоб вимкнути SIP перед запуском imsg launch.
3. Інжектуйте helper. Коли SIP вимкнено і в Messages.app виконано вхід:
   imsg launch
   
   imsg launch відмовляється виконувати інжекцію, коли SIP досі увімкнено, тож це також слугує підтвердженням, що крок 2 спрацював.
4. Перевірте міст з OpenClaw:
   openclaw channels status --probe
   
   Запис iMessage має повідомляти works, а imsg status --json | jq '.selectors' має показувати retractMessagePart: true плюс ті селектори редагування / введення / прочитання, які надає ваша збірка macOS. Поштучне gating методів у Plugin OpenClaw в actions.ts рекламує лише дії, базовий селектор яких дорівнює true, тож поверхня дій, яку ви бачите в списку інструментів агента, відображає те, що міст реально може виконати на цьому хості.

​

Коли ви не можете вимкнути SIP

• imsg повертається до базового режиму — лише текст + медіа + отримання.
• Plugin OpenClaw усе ще рекламує надсилання тексту/медіа та моніторинг вхідних повідомлень; він просто приховує react, edit, unsend, reply, sendWithEffect і групові операції з поверхні дій (відповідно до gate можливостей для кожного методу).
• Ви можете запустити окремий Mac без Apple Silicon (або виділений bot Mac) з вимкненим SIP для навантаження iMessage, залишивши SIP увімкненим на основних пристроях. Див. Виділений користувач macOS для бота (окрема ідентичність iMessage) нижче.

​

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

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

{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: {
        "*": { systemPrompt: "Use British spelling." },
        "8421": {
          requireMention: true,
          systemPrompt: "This is the on-call rotation chat. Keep replies under 3 sentences.",
        },
        "9907": {
          // explicit suppression: the wildcard "Use British spelling." does not apply here
          systemPrompt: "",
        },
      },
    },
  },
}

​

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

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

• нормалізований ідентифікатор DM, наприклад +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" },
    },
  ],
}

​

Шаблони розгортання

{
  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 "$@"

​

Медіа, розбиття на частини та цілі доставлення

imsg chats --limit 20

​

Дії Private API

{
  channels: {
    imessage: {
      actions: {
        reactions: true,
        edit: true,
        unsend: true,
        reply: true,
        sendWithEffect: true,
        sendAttachment: true,
        renameGroup: true,
        setGroupIcon: true,
        addParticipant: true,
        removeParticipant: true,
        leaveGroup: true,
      },
    },
  },
}

{
  channels: {
    imessage: {
      sendReadReceipts: false,
    },
  },
}

​

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

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

​

Об’єднання розділених DM (команда + URL в одній композиції)

1. Текстове повідомлення ("Dump").
2. Кулька попереднього перегляду URL ("https://...") із зображеннями OG-preview як вкладеннями.

{
  channels: {
    imessage: {
      coalesceSameSenderDms: true, // opt in (default: false)
    },
  },
}

{
  messages: {
    inbound: {
      byChannel: {
        // 2500 ms works for most setups; raise to 4000 ms if your Mac is
        // slow or under memory pressure (observed gap can stretch past 2 s
        // then).
        imessage: 2500,
      },
    },
  },
}

​

Сценарії та що бачить агент

​

Надолуження після простою Gateway

channels: {
  imessage: {
    catchup: {
      enabled: true,             // master switch (default: false)
      maxAgeMinutes: 120,        // skip rows older than now - 2h (default: 120, clamp 1..720)
      perRunLimit: 50,           // max rows replayed per startup (default: 50, clamp 1..500)
      firstRunLookbackMinutes: 30, // first run with no cursor: look back 30 min (default: 30)
      maxFailureRetries: 10,     // give up on a wedged guid after 10 dispatch failures (default: 10)
    },
  },
}

​

Як це виконується

​

Семантика курсора й повторів

{
  "lastSeenMs": 1717900800000,
  "lastSeenRowid": 482910,
  "updatedAt": 1717900801234,
  "failureRetries": { "<guid>": 1 }
}

• Курсор просувається після кожного успішного надсилання й утримується, коли надсилання рядка кидає помилку — наступний запуск повторює той самий рядок із утриманого курсора.
• Після maxFailureRetries послідовних помилок для того самого guid, Catchup записує warn і примусово просуває курсор повз застрягле повідомлення, щоб подальші запуски могли рухатися далі.
• GUID, щодо яких уже відмовилися, пропускаються відразу (без спроби надсилання) у подальших запусках і враховуються в skippedGivenUp у підсумку запуску.

​

Сигнали, видимі оператору

imessage catchup: replayed=N skippedFromMe=… skippedGivenUp=… failed=… givenUp=… fetchedCount=…
imessage catchup: giving up on guid=<guid> after <N> failures; advancing cursor past it
imessage catchup: fetched <X> rows across chats, capped to perRunLimit=<Y>

​

Коли залишити вимкненим

• Gateway працює безперервно з автоматичним перезапуском через watchdog, а прогалини завжди < кількох секунд — стандартне вимкнене значення підходить.
• Обсяг DM низький, і пропущені повідомлення не змінять поведінку агента — початкове вікно firstRunLookbackMinutes може надіслати неочікуваний старий контекст під час першого ввімкнення.

​

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

imsg rpc --help
imsg status --json
openclaw channels status --probe

#!/usr/bin/env bash
exec ssh -T messages-mac imsg "$@"

openclaw channels status --probe --channel imessage

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

​

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

• Довідник конфігурації - iMessage
• Конфігурація Gateway
• Pairing

​

Пов’язане

• Огляд каналів — усі підтримувані канали
• Вилучення BlueBubbles і шлях imsg iMessage — оголошення й підсумок міграції
• Перехід із BlueBubbles — таблиця перекладу конфігурації та покрокове перемикання
• Pairing — автентифікація DM і потік pairing
• Групи — поведінка групових чатів і gating згадок
• Маршрутизація каналів — маршрутизація сеансів для повідомлень
• Безпека — модель доступу й зміцнення