iMessage

Stan: natywna integracja z zewnętrznym CLI. Gateway uruchamia imsg rpc i komunikuje się przez JSON-RPC za pośrednictwem standardowego wejścia i wyjścia — bez osobnego demona ani portu. Tryb prywatnego API jest zdecydowanie zalecany do uzyskania pełnej funkcjonalności kanału iMessage; odpowiedzi, reakcje Tapback, efekty, ankiety, odpowiedzi na załączniki i działania grupowe wymagają imsg launch oraz pomyślnego sprawdzenia prywatnego API.

W typowej konfiguracji lokalnej instalator OpenClaw może zaproponować potwierdzoną przez użytkownika instalację lub aktualizację imsg przez Homebrew na Macu zalogowanym do Wiadomości. Konfiguracja ręczna i topologie z wrapperem SSH pozostają zarządzane przez operatora: zainstaluj lub zaktualizuj imsg w tym samym kontekście użytkownika, w którym będzie działać Gateway lub wrapper.

Szybka konfiguracja

brew install steipete/tap/imsgbrew update && brew upgrade 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>

ssh messages-mac 'brew install steipete/tap/imsg && brew update && brew upgrade imsg'

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

{channels: {imessage: {  enabled: true,  cliPath: "~/.openclaw/scripts/imsg-ssh",  remoteHost: "user@gateway-host", // używane do pobierania załączników przez SCP  includeAttachments: true,  // Opcjonalnie: dodatkowe dozwolone katalogi główne załączników (łączone z domyślnym  // /Users/*/Library/Messages/Attachments).  attachmentRoots: ["/Users/*/Library/Messages/Attachments"],  remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],},},}

Wymagania i uprawnienia (macOS)

• Na Macu, na którym działa imsg, użytkownik musi być zalogowany do Wiadomości.
• Kontekst procesu uruchamiającego OpenClaw/imsg wymaga pełnego dostępu do dysku (dostęp do bazy danych Wiadomości).
• Wysyłanie wiadomości przez Messages.app wymaga uprawnienia do automatyzacji.
• W przypadku zaawansowanych działań (reakcja / edycja / cofnięcie wysłania / odpowiedź w wątku / efekty / ankiety / operacje grupowe) ochrona integralności systemu musi być wyłączona — zobacz Włączanie prywatnego API imsg. Podstawowe wysyłanie i odbieranie tekstu oraz multimediów działa bez jej wyłączania.

Brak uprawnień do wysyłania zdarzeń Apple do Wiadomości. (-1743)

kTCCServiceAppleEvents | /usr/libexec/sshd-keygen-wrapper | auth_value=0 | com.apple.MobileSMS

Włączanie prywatnego API imsg

imsg jest dostępny w dwóch trybach działania. W przypadku OpenClaw zalecaną konfiguracją jest tryb prywatnego API, ponieważ udostępnia on kanałowi natywne działania iMessage oczekiwane przez użytkowników. Tryb podstawowy pozostaje przydatny w instalacjach o niskim poziomie ryzyka, do wstępnej weryfikacji lub na hostach, na których nie można wyłączyć SIP.

• Tryb podstawowy (domyślny, nie wymaga zmian SIP): wychodzący tekst i multimedia przez send, obserwowanie i historia wiadomości przychodzących oraz lista czatów. Te funkcje są dostępne od razu po świeżej instalacji brew install steipete/tap/imsg i przyznaniu opisanych powyżej standardowych uprawnień systemu macOS.
• Tryb prywatnego API: imsg wstrzykuje pomocniczą bibliotekę dylib do Messages.app, aby wywoływać wewnętrzne funkcje IMCore. Odblokowuje to react, edit, unsend, reply (w wątku), sendWithEffect, poll i poll-vote (natywne ankiety Wiadomości), renameGroup, setGroupIcon, addParticipant, removeParticipant, leaveGroup, a także wskaźniki pisania i potwierdzenia odczytu.

Zalecany na tej stronie zakres działań wymaga trybu prywatnego API. Plik README imsg jasno określa to wymaganie:

Funkcje zaawansowane, takie jak read, typing, launch, rozbudowane wysyłanie obsługiwane przez most, modyfikowanie wiadomości i zarządzanie czatami, są opcjonalne. Wymagają wyłączenia SIP i wstrzyknięcia pomocniczej biblioteki dylib do Messages.app. imsg launch odmawia wstrzyknięcia, gdy SIP jest włączona.

Technika wstrzykiwania pomocnika wykorzystuje własną bibliotekę dylib imsg do uzyskania dostępu do prywatnych interfejsów API Wiadomości. Ścieżka iMessage w OpenClaw nie korzysta z serwera innej firmy ani środowiska wykonawczego BlueBubbles.

Konfiguracja

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

   brew install steipete/tap/imsgbrew update && brew upgrade imsgimsg --versionimsg status --json

   Dane wyjściowe imsg status --json zawierają bridge_version, rpc_methods oraz selectors dla poszczególnych metod, dzięki czemu przed rozpoczęciem można sprawdzić, co obsługuje bieżąca kompilacja.

2. Wyłącz System Integrity Protection oraz (we współczesnych wersjach macOS) Library Validation. Wstrzyknięcie pomocniczej biblioteki dylib firmy innej niż Apple do podpisanego przez Apple procesu Messages.app wymaga wyłączenia SIP oraz złagodzenia weryfikacji bibliotek. Krok dotyczący SIP w trybie odzyskiwania zależy od wersji macOS:

   • macOS 10.13–10.15 (Sierra–Catalina): wyłącz Library Validation za pomocą Terminala, uruchom ponownie komputer w trybie odzyskiwania, wykonaj csrutil disable, a następnie ponownie uruchom komputer.
   • macOS 11+ (Big Sur i nowsze), Intel: przejdź do trybu odzyskiwania (lub odzyskiwania przez Internet), wykonaj csrutil disable, a następnie ponownie uruchom komputer.
   • macOS 11+, Apple Silicon: użyj sekwencji uruchamiania przyciskiem zasilania, aby przejść do trybu odzyskiwania; w najnowszych wersjach macOS przytrzymaj klawisz Left Shift podczas klikania Continue, a następnie wykonaj csrutil disable. Konfiguracje maszyn wirtualnych wymagają osobnej procedury, dlatego najpierw utwórz migawkę maszyny wirtualnej.

   W systemie macOS 11 i nowszych samo csrutil disable zwykle nie wystarcza. Apple nadal wymusza weryfikację bibliotek dla Messages.app jako pliku binarnego platformy, dlatego pomocniczy komponent podpisany ad hoc zostaje odrzucony (Library Validation failed: ... platform binary, but mapped file is not) nawet przy wyłączonym SIP. Po wyłączeniu SIP wyłącz również weryfikację bibliotek i ponownie uruchom komputer:

   sudo defaults write /Library/Preferences/com.apple.security.libraryvalidation.plist DisableLibraryValidation -bool true

   macOS 26 (Tahoe), zweryfikowano w wersji 26.5.1: wyłączony SIP wraz z powyższym poleceniem DisableLibraryValidation wystarcza do wstrzyknięcia komponentu pomocniczego we wszystkich wersjach od 26.0 do 26.5.x. Żadne argumenty rozruchowe nie są wymagane. Plik plist jest czynnikiem decydującym i najczęściej pomijanym krokiem, gdy wstrzykiwanie w Tahoe kończy się niepowodzeniem:

   • Z plikiem plist: imsg launch wykonuje wstrzyknięcie, a imsg status zgłasza advanced_features: true.
   • Bez pliku plist (nawet przy wyłączonym SIP): imsg launch kończy się niepowodzeniem z komunikatem Failed to launch: Timeout waiting for Messages.app to initialize. AMFI odrzuca podczas ładowania komponent pomocniczy podpisany ad hoc, przez co most nigdy nie osiąga gotowości, a uruchamianie przekracza limit czasu. To przekroczenie limitu czasu jest objawem, z którym większość osób spotyka się w Tahoe; rozwiązaniem jest powyższy plik plist, a nie bardziej drastyczne działania.

   Jeśli po uaktualnieniu macOS wstrzykiwanie imsg launch lub określone selectors zaczynają zwracać wartość false, zwykle przyczyną jest ta blokada. Zanim uznasz, że sam krok dotyczący SIP się nie powiódł, sprawdź stan SIP i weryfikacji bibliotek. Jeśli te ustawienia są prawidłowe, ale most nadal nie może wykonać wstrzyknięcia, zbierz imsg status --json wraz z wynikiem imsg launch i zgłoś problem w projekcie imsg zamiast osłabiać dodatkowe zabezpieczenia całego systemu.

3. Wstrzyknij komponent pomocniczy. Po wyłączeniu SIP i zalogowaniu się w Messages.app:

   imsg launch

   imsg launch odmawia wykonania wstrzyknięcia, jeśli SIP jest nadal włączony, więc służy to również jako potwierdzenie wykonania kroku 2.

4. Zweryfikuj most z poziomu OpenClaw:

   openclaw channels status --probe

   Wpis iMessage powinien zgłaszać works, a imsg status --json | jq '{rpc_methods, selectors}' powinien przedstawiać możliwości udostępniane przez używaną kompilację macOS. Tworzenie ankiet wymaga selectors.pollPayloadMessage; głosowanie wymaga zarówno selectors.pollVoteMessage, jak i metody RPC poll.vote. Plugin OpenClaw udostępnia tylko działania obsługiwane przez wynik sondowania zapisany w pamięci podręcznej, natomiast przy pustej pamięci podręcznej zachowuje optymistyczne założenia i wykonuje sondowanie przy pierwszym wysłaniu.

Jeśli openclaw channels status --probe zgłasza kanał jako works, ale określone działania podczas wysyłania zgłaszają błąd „iMessage <action> requires the imsg private API bridge”, ponownie uruchom imsg launch — komponent pomocniczy może przestać działać (po ponownym uruchomieniu Messages.app, aktualizacji systemu operacyjnego itp.), a zapisany w pamięci podręcznej stan available: true będzie nadal udostępniać działania do czasu odświeżenia go przez kolejne sondowanie.

Gdy SIP pozostaje włączony

Jeśli wyłączenie SIP jest nieakceptowalne w danym modelu zagrożeń:

• imsg przechodzi do trybu podstawowego — obsługuje tylko tekst, multimedia i odbieranie.
• Plugin OpenClaw nadal udostępnia wysyłanie tekstu i multimediów oraz monitorowanie wiadomości przychodzących; ukrywa react, edit, unsend, reply, sendWithEffect i operacje grupowe z powierzchni działań (zgodnie z blokadą możliwości poszczególnych metod).
• Można użyć osobnego komputera Mac bez Apple Silicon (lub dedykowanego komputera Mac dla bota) z wyłączonym SIP do obsługi obciążenia iMessage, pozostawiając SIP włączony na urządzeniach głównych. Zobacz poniżej sekcję Dedykowany użytkownik macOS dla bota (osobna tożsamość iMessage).

Kontrola dostępu i trasowanie

{  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

Czaty iMessage można powiązać z sesjami ACP.

Szybka procedura operatora:

• Uruchom /acp spawn codex --bind here w wiadomości bezpośredniej lub dozwolonym czacie grupowym.
• Przyszłe wiadomości w tej samej konwersacji iMessage są kierowane do utworzonej sesji ACP.
• /new i /reset resetują tę samą powiązaną sesję ACP bez jej zastępowania.
• /acp close zamyka sesję ACP i usuwa powiązanie.

Skonfigurowane trwałe powiązania używają wpisów bindings[] najwyższego poziomu z type: "acp" i match.channel: "imessage".

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

• znormalizowanego uchwytu wiadomości bezpośredniej, takiego jak +15555550123 lub user@example.com
• 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" },    },  ],}

Opis wspólnego działania powiązań ACP znajduje się w sekcji Agenci ACP.

Wzorce wdrażania

{  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 bashexec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"

Multimedia, dzielenie na fragmenty i cele dostarczania

imsg chats --limit 20

Akcje prywatnego API

Gdy imsg launch jest uruchomiony, a openclaw channels status --probe zgłasza privateApi.available: true, narzędzie wiadomości może oprócz zwykłego wysyłania tekstu korzystać z natywnych akcji iMessage.

Wszystkie akcje są domyślnie włączone; użyj channels.imessage.actions, aby wyłączyć poszczególne akcje:

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

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

Zapisy konfiguracji

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

Wyłączanie:

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

Scalanie podzielonych wiadomości prywatnych (polecenie + adres URL w jednej kompozycji)

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

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

W większości konfiguracji oba wiersze docierają do OpenClaw w odstępie około 0,8–2,0 s. Bez scalania agent otrzymuje samo polecenie w turze 1 (i często odpowiada „wyślij adres URL”), zanim adres URL dotrze w turze 2. Wynika to z potoku wysyłania Apple, a nie z działania wprowadzonego przez OpenClaw ani imsg.

channels.imessage.coalesceSameSenderDms włącza dla wiadomości prywatnych buforowanie kolejnych wierszy od tego samego nadawcy. Gdy imsg udostępnia strukturalny znacznik podglądu adresu URL balloon_bundle_id: "com.apple.messages.URLBalloonProvider" w jednym z wierszy źródłowych, OpenClaw scala tylko tę rzeczywiście podzieloną wysyłkę, a pozostałe buforowane wiersze zachowuje jako osobne tury. W starszych kompilacjach imsg, które nie emitują żadnych metadanych dymka, OpenClaw nie potrafi odróżnić podzielonej wysyłki od osobnych wysyłek, dlatego awaryjnie scala zawartość bufora. Zachowuje to zachowanie sprzed wprowadzenia metadanych, zamiast powodować regresję polegającą na dzieleniu wysyłek Dump <url> na dwie tury. Czaty grupowe nadal przekazują każdą wiadomość osobno, aby zachować strukturę tur wielu użytkowników.

{  channels: {    imessage: {      coalesceSameSenderDms: true, // włączenie opcjonalne (domyślnie: false)    },  },}

{  messages: {    inbound: {      byChannel: {        // 7000 ms obejmuje zaobserwowane opóźnienia podglądu adresów URL w Messages.app.        imessage: 7000,      },    },  },}

Scenariusze i dane widoczne dla agenta

Kolumna „Flaga włączona” przedstawia zachowanie kompilacji imsg, która emituje balloon_bundle_id. W starszych kompilacjach imsg, które nie emitują żadnych metadanych dymka, wiersze oznaczone niżej jako „Dwie tury” / „N tur” korzystają zamiast tego ze starszego scalania awaryjnego (jedna tura): OpenClaw nie potrafi strukturalnie odróżnić podzielonej wysyłki od osobnych wysyłek, dlatego zachowuje scalanie sprzed wprowadzenia metadanych. Precyzyjne rozdzielanie włącza się, gdy kompilacja zaczyna emitować metadane dymka.

Odzyskiwanie wiadomości przychodzących po ponownym uruchomieniu mostu lub Gateway

iMessage odzyskuje wiadomości pominięte podczas niedostępności Gateway, a jednocześnie tłumi nieaktualną „bombę zaległości”, którą Apple może wysłać po odzyskaniu połączenia Push. Domyślne zachowanie jest zawsze włączone i opiera się na deduplikacji wiadomości przychodzących.

• Deduplikacja powtórzeń. Każda przekazana wiadomość przychodząca jest rejestrowana według identyfikatora GUID Apple w trwałym stanie pluginu (imessage.inbound-dedupe): zostaje zarezerwowana podczas pobierania i zatwierdzona po obsłużeniu (rezerwacja jest zwalniana po przejściowym błędzie, aby umożliwić ponowną próbę). Wszystko, co już obsłużono, jest odrzucane zamiast przekazywane dwukrotnie. Umożliwia to agresywne odtwarzanie podczas odzyskiwania bez prowadzenia ewidencji poszczególnych wiadomości.
• Odzyskiwanie po przestoju. Podczas uruchamiania monitor zapamiętuje ostatni przekazany identyfikator rowid chat.db (trwały kursor dla każdego konta) i przekazuje go do imsg watch.subscribe jako since_rowid, dzięki czemu imsg odtwarza wiersze otrzymane podczas niedostępności Gateway, a następnie śledzi wiadomości na żywo. Odtwarzanie jest ograniczone do 500 najnowszych wierszy oraz wiadomości sprzed maksymalnie około 2 godzin, a deduplikacja odrzuca wszystko, co już obsłużono.
• Ograniczenie wieku nieaktualnych zaległości. Wiersze powyżej granicy uruchomienia są faktycznie odbierane na żywo; jeśli data wysłania jednego z nich jest starsza od czasu nadejścia o ponad około 15 minut, jest on zaległością opróżnioną przez Push i zostaje stłumiony. Odtwarzane wiersze (na granicy lub poniżej niej) korzystają natomiast z szerszego okna odzyskiwania, dzięki czemu niedawno pominięta wiadomość zostaje dostarczona, a dawna historia nie.

Odzyskiwanie działa zarówno w lokalnych, jak i zdalnych konfiguracjach cliPath, ponieważ odtwarzanie since_rowid odbywa się przez to samo połączenie RPC imsg. Różnica dotyczy okna: gdy Gateway może odczytać chat.db (lokalnie), ustala na jego podstawie graniczny identyfikator rowid uruchomienia, ogranicza zakres odtwarzania i dostarcza pominięte wiadomości sprzed maksymalnie kilku godzin. W przypadku zdalnego cliPath przez SSH nie może odczytać bazy danych, dlatego odtwarzanie nie ma limitu, a każdy wiersz korzysta z ograniczenia wieku wiadomości na żywo — nadal odzyskuje niedawno pominięte wiadomości i tłumi stare zaległości, ale używa węższego okna wiadomości na żywo. Aby uzyskać szersze okno odzyskiwania, należy uruchomić Gateway na Macu obsługującym Wiadomości.

Sygnał widoczny dla operatora

Stłumione zaległości są rejestrowane na domyślnym poziomie i nigdy nie są odrzucane bez informacji (flaga recovery wskazuje zastosowane okno):

imessage: stłumiono nieaktualne zaległe wiadomości przychodzące account=<id> sent=<iso> recovery=<bool> (&lt;N&gt; stłumionych od uruchomienia)

Migracja

channels.imessage.catchup.* jest przestarzałe — odzyskiwanie po przestoju jest automatyczne i w nowych konfiguracjach nie wymaga ustawień. Istniejące konfiguracje z catchup.enabled: true nadal są respektowane jako profil zgodności dla okna odtwarzania podczas odzyskiwania. Wyłączone bloki nadrabiania zaległości (enabled: false lub brak enabled: true) zostały wycofane; openclaw doctor --fix je usuwa.

Rozwiązywanie problemów

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

imsg chats --limit 10 --jsonimsg watch --chat-id <chat-id> --jsonsqlite3 ~/Library/Messages/chat.db \"select datetime(max(date)/1000000000 + 978307200, 'unixepoch', 'localtime'), max(ROWID) from message;"

launchctl kickstart -k system/com.apple.apsdlaunchctl kickstart -k gui/$(id -u)/com.apple.CommCenterlaunchctl kickstart -k gui/$(id -u)/com.apple.identityservicesdlaunchctl kickstart -k gui/$(id -u)/com.apple.imagentimsg launchopenclaw gateway restart

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

openclaw channels status --probe --channel imessage

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

Odnośniki do dokumentacji konfiguracji

• Dokumentacja konfiguracji — iMessage
• Konfiguracja Gateway
• Parowanie

Powiązane materiały

• Przegląd kanałów — wszystkie obsługiwane kanały
• Usunięcie BlueBubbles i ścieżka iMessage oparta na imsg — ogłoszenie i podsumowanie migracji
• Przejście z BlueBubbles — tabela mapowania konfiguracji i instrukcja migracji krok po kroku
• Parowanie — uwierzytelnianie wiadomości prywatnych i proces parowania
• Grupy — działanie czatów grupowych i ograniczanie obsługi na podstawie wzmianek
• Routing kanałów — routing sesji dla wiadomości
• Bezpieczeństwo — model dostępu i wzmacnianie zabezpieczeń