iMessage

Status: natywna integracja z zewnętrznym CLI. Gateway uruchamia imsg rpc i komunikuje się przez JSON-RPC na stdio (bez osobnego demona/portu). Zaawansowane akcje wymagają imsg launch oraz pomyślnej sondy prywatnego API.

Szybka konfiguracja

brew install steipete/tap/imsgimsg rpc --helpimsg launchopenclaw channels status --probe

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

openclaw gateway

openclaw pairing list imessageopenclaw pairing approve imessage <CODE>

#!/usr/bin/env bashexec 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"],},},}

Wymagania i uprawnienia (macOS)

• Messages musi być zalogowane na Macu uruchamiającym imsg.
• Full Disk Access jest wymagany dla kontekstu procesu uruchamiającego OpenClaw/imsg (dostęp do bazy danych Messages).
• Uprawnienie Automation jest wymagane do wysyłania wiadomości przez Messages.app.
• W przypadku zaawansowanych akcji (reakcja / edycja / cofnięcie wysłania / odpowiedź w wątku / efekty / operacje na grupach) funkcja System Integrity Protection musi być wyłączona — zobacz poniżej Włączanie prywatnego API imsg. Podstawowe wysyłanie/odbieranie tekstu i multimediów działa bez tego.

Włączanie prywatnego API imsg

imsg działa w dwóch trybach operacyjnych:

• Tryb podstawowy (domyślny, bez zmian SIP): tekst i multimedia wychodzące przez send, obserwacja/historia przychodząca, lista czatów. To otrzymujesz od razu po świeżej instalacji brew install steipete/tap/imsg oraz przyznaniu standardowych uprawnień macOS opisanych wyżej.
• Tryb prywatnego API: imsg wstrzykuje pomocniczą bibliotekę dylib do Messages.app, aby wywoływać wewnętrzne funkcje IMCore. To odblokowuje react, edit, unsend, reply (wątek), sendWithEffect, renameGroup, setGroupIcon, addParticipant, removeParticipant, leaveGroup, a także wskaźniki pisania i potwierdzenia odczytu.

Aby uzyskać dostęp do zaawansowanego obszaru akcji dokumentowanego na tej stronie kanału, potrzebujesz trybu prywatnego API. README imsg jasno wskazuje wymaganie:

Zaawansowane funkcje, takie jak read, typing, launch, rozbudowane wysyłanie wspierane przez bridge, mutacja wiadomości i zarządzanie czatami, są opcjonalne. Wymagają wyłączenia SIP oraz wstrzyknięcia pomocniczej biblioteki dylib do Messages.app. imsg launch odmawia wstrzyknięcia, gdy SIP jest włączone.

Technika wstrzykiwania helpera używa własnej biblioteki dylib imsg, aby dotrzeć do prywatnych API Messages. W ścieżce OpenClaw iMessage nie ma serwera zewnętrznego ani środowiska uruchomieniowego BlueBubbles.

Konfiguracja

1. Zainstaluj (lub zaktualizuj) imsg na Macu, na którym działa Messages.app:

   brew install steipete/tap/imsgimsg --versionimsg status --json

   Wynik imsg status --json raportuje bridge_version, rpc_methods oraz selectors dla poszczególnych metod, dzięki czemu możesz sprawdzić, co obsługuje bieżąca kompilacja, zanim zaczniesz.

2. Wyłącz System Integrity Protection. Jest to zależne od wersji macOS, ponieważ podstawowe wymaganie Apple zależy od systemu operacyjnego i sprzętu:

   • macOS 10.13–10.15 (Sierra–Catalina): wyłącz Library Validation przez Terminal, uruchom ponownie w trybie Recovery Mode, uruchom csrutil disable, zrestartuj.
   • macOS 11+ (Big Sur i nowsze), Intel: Recovery Mode (albo Internet Recovery), csrutil disable, restart.
   • macOS 11+, Apple Silicon: sekwencja uruchamiania przyciskiem zasilania, aby wejść do Recovery; w nowszych wersjach macOS przytrzymaj klawisz Left Shift, gdy klikasz Continue, a następnie csrutil disable. Konfiguracje maszyn wirtualnych używają osobnej procedury — najpierw zrób snapshot VM.
   • macOS 26 / Tahoe: zasady library-validation i kontrole prywatnych uprawnień imagent zostały jeszcze bardziej zaostrzone; imsg może wymagać zaktualizowanej kompilacji, aby nadążyć. Jeśli po dużej aktualizacji macOS wstrzyknięcie imsg launch albo konkretne selectors zaczynają zwracać false, sprawdź informacje o wydaniu imsg, zanim uznasz, że krok SIP się powiódł.

   Wykonaj procedurę Apple dla trybu Recovery odpowiednią dla Twojego Maca, aby wyłączyć SIP przed uruchomieniem imsg launch.

3. Wstrzyknij helper. Przy wyłączonym SIP i zalogowanym Messages.app:

   imsg launch

   imsg launch odmawia wstrzyknięcia, gdy SIP nadal jest włączone, więc działa to również jako potwierdzenie, że krok 2 został wykonany.

4. Zweryfikuj bridge z OpenClaw:

   openclaw channels status --probe

   Wpis iMessage powinien raportować works, a imsg status --json | jq '.selectors' powinien pokazywać retractMessagePart: true oraz wszystkie selektory edycji / pisania / odczytu ujawniane przez Twoją kompilację macOS. Bramkowanie poszczególnych metod Pluginu OpenClaw w actions.ts reklamuje tylko akcje, których bazowy selektor ma wartość true, więc obszar akcji widoczny na liście narzędzi agenta odzwierciedla to, co bridge może faktycznie zrobić na tym hoście.

Jeśli openclaw channels status --probe raportuje kanał jako works, ale konkretne akcje zgłaszają błąd „iMessage <action> requires the imsg private API bridge” w czasie wysyłania, uruchom ponownie imsg launch — helper może zniknąć (restart Messages.app, aktualizacja systemu itd.), a buforowany status available: true będzie nadal reklamować akcje do czasu, aż następna sonda go odświeży.

Gdy nie możesz wyłączyć SIP

Jeśli wyłączenie SIP nie jest akceptowalne dla Twojego modelu zagrożeń:

• imsg wraca do trybu podstawowego — tylko tekst + multimedia + odbiór.
• Plugin OpenClaw nadal reklamuje wysyłanie tekstu/multimediów i monitorowanie przychodzące; po prostu ukrywa react, edit, unsend, reply, sendWithEffect oraz operacje na grupach z obszaru akcji (zgodnie z bramką możliwości dla poszczególnych metod).
• Możesz uruchomić osobnego Maca bez Apple Silicon (albo dedykowanego Maca bota) z wyłączonym SIP dla obciążenia iMessage, pozostawiając SIP włączony na swoich głównych urządzeniach. Zobacz poniżej Dedykowany użytkownik macOS bota (osobna tożsamość iMessage).

Kontrola dostępu i routing

{  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: "",        },      },    },  },}

Powiązania konwersacji ACP

Starsze czaty iMessage można także powiązać z sesjami ACP.

Szybki przepływ operatora:

• Uruchom /acp spawn codex --bind here w DM-ie lub dozwolonym czacie grupowym.
• Przyszłe wiadomości w tej samej konwersacji iMessage będą kierowane do utworzonej sesji ACP.
• /new i /reset resetują tę samą powiązaną sesję ACP w miejscu.
• /acp close zamyka sesję ACP i usuwa powiązanie.

Skonfigurowane trwałe powiązania są obsługiwane przez wpisy najwyższego poziomu bindings[] z type: "acp" i match.channel: "imessage".

match.peer.id może używać:

• znormalizowanego uchwytu DM, takiego jak +15555550123 lub [email protected]
• chat_id:<id> (zalecane dla stabilnych powiązań grupowych)
• chat_guid:<guid>
• chat_identifier:<identifier>

Przykład:

{  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" },    },  ],}

Zobacz Agenci ACP, aby poznać wspólne zachowanie powiązań ACP.

Wzorce wdrożenia

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

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

Multimedia, dzielenie i targety dostarczania

imsg chats --limit 20

Akcje prywatnego API

Gdy działa imsg launch, a openclaw channels status --probe zgłasza privateApi.available: true, narzędzie wiadomości może używać natywnych akcji iMessage oprócz zwykłych wysyłek tekstowych.

{  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,    },  },}

Zapisy konfiguracji

iMessage domyślnie zezwala na zapisy konfiguracji inicjowane przez kanał (dla /config set|unset, gdy commands.config: true).

Wyłącz:

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

Scalanie dzielonych wysyłek DM-ów (polecenie + URL w jednej kompozycji)

Gdy użytkownik wpisze razem polecenie i URL — np. Dump https://example.com/article — aplikacja Messages firmy Apple dzieli wysyłkę na dwa osobne wiersze chat.db:

1. Wiadomość tekstową ("Dump").
2. Dymek podglądu URL ("https://...") z obrazami podglądu OG jako załącznikami.

Dwa wiersze docierają do OpenClaw w odstępie około 0,8-2,0 s w większości konfiguracji. Bez scalania agent otrzymuje samo polecenie w turze 1, odpowiada (często „wyślij mi URL”) i widzi URL dopiero w turze 2 — wtedy kontekst polecenia jest już utracony. To wynika z potoku wysyłania Apple, a nie z czegokolwiek, co wprowadza OpenClaw lub imsg.

channels.imessage.coalesceSameSenderDms włącza dla DM scalanie kolejnych wierszy od tego samego nadawcy w jedną turę agenta. Czaty grupowe nadal są wysyłane osobno dla każdej wiadomości, aby zachować strukturę tur wielu użytkowników.

{  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,      },    },  },}

Scenariusze i to, co widzi agent

Nadrabianie po przestoju Gateway

Gdy Gateway jest offline (awaria, restart, uśpienie Maca, wyłączona maszyna), imsg watch wznawia działanie od bieżącego stanu chat.db, gdy Gateway ponownie się uruchomi — wszystko, co dotarło podczas przerwy, domyślnie nigdy nie zostanie zobaczone. Nadrabianie odtwarza te wiadomości przy następnym uruchomieniu, aby agent nie pominął po cichu ruchu przychodzącego.

Nadrabianie jest domyślnie wyłączone. Włącz je per kanał:

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)    },  },}

Jak to działa

Jedno przejście na każde uruchomienie monitorIMessageProvider, w sekwencji: gotowe imsg launch → watch.subscribe → performIMessageCatchup → pętla wysyłania na żywo. Samo nadrabianie używa chats.list + per-czatowego messages.history wobec tego samego klienta JSON-RPC, którego używa imsg watch. Wszystko, co dotrze podczas przebiegu nadrabiania, normalnie przechodzi przez wysyłanie na żywo; istniejąca pamięć podręczna deduplikacji przychodzącej pochłania wszelkie nakładanie się z odtwarzanymi wierszami.

Każdy odtwarzany wiersz jest przekazywany przez ścieżkę wysyłania na żywo (evaluateIMessageInbound + dispatchInboundMessage), więc listy dozwolonych, zasady grup, debouncer, pamięć podręczna echa i potwierdzenia odczytu zachowują się identycznie dla wiadomości odtwarzanych i wiadomości na żywo.

Semantyka kursora i ponawiania

Nadrabianie utrzymuje kursor per konto w <openclawStateDir>/imessage/catchup/<account>__<hash>.json (katalog stanu OpenClaw domyślnie to ~/.openclaw, można go nadpisać przez OPENCLAW_STATE_DIR):

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

• Kursor przesuwa się po każdym udanym wysłaniu i jest zatrzymywany, gdy wysłanie wiersza rzuci błąd — następne uruchomienie ponawia ten sam wiersz od zatrzymanego kursora.
• Po maxFailureRetries kolejnych rzutach błędu dla tego samego guid nadrabianie zapisuje warn i wymusza przesunięcie kursora poza zablokowaną wiadomość, aby kolejne uruchomienia mogły iść naprzód.
• GUID-y, dla których już się poddano, są pomijane po wykryciu (bez próby wysłania) w późniejszych uruchomieniach i liczone pod skippedGivenUp w podsumowaniu przebiegu.

Sygnały widoczne dla operatora

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

Wiersz WARN ... capped to perRunLimit oznacza, że pojedyncze uruchomienie nie opróżniło całego backlogu. Zwiększ perRunLimit (maks. 500), jeśli Twoje przerwy regularnie przekraczają domyślny przebieg 50 wierszy.

Kiedy pozostawić wyłączone

• Gateway działa ciągle z automatycznym restartem przez watchdog, a przerwy są zawsze krótsze niż kilka sekund — domyślne wyłączenie jest w porządku.
• Wolumen DM jest niski, a pominięte wiadomości nie zmieniłyby zachowania agenta — początkowe okno firstRunLookbackMinutes może wysłać zaskakujący stary kontekst przy pierwszym włączeniu.

Gdy włączysz nadrabianie, pierwsze uruchomienie bez kursora patrzy wstecz tylko o firstRunLookbackMinutes (domyślnie 30 min), a nie o pełne okno maxAgeMinutes — zapobiega to odtwarzaniu długiej historii wiadomości sprzed włączenia.

Rozwiązywanie problemów

imsg rpc --helpimsg status --jsonopenclaw channels status --probe

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

openclaw channels status --probe --channel imessage

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

Wskaźniki referencji konfiguracji

• Referencja konfiguracji - iMessage
• Konfiguracja Gateway
• Parowanie

Powiązane

• Przegląd kanałów — wszystkie obsługiwane kanały
• Usunięcie BlueBubbles i ścieżka imsg iMessage — ogłoszenie i podsumowanie migracji
• Przejście z BlueBubbles — tabela tłumaczenia konfiguracji i instrukcja przełączenia krok po kroku
• Parowanie — uwierzytelnianie DM i przepływ parowania
• Grupy — zachowanie czatu grupowego i bramkowanie wzmianek
• Routing kanałów — routing sesji dla wiadomości
• Bezpieczeństwo — model dostępu i utwardzanie