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 i 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.
• Dla zaawansowanych akcji (reakcja / edycja / cofnięcie wysłania / odpowiedź w wątku / efekty / ankiety / operacje na grupach) System Integrity Protection musi być wyłączone — zobacz Włączanie prywatnego API imsg poniżej. Podstawowe wysyłanie/odbieranie tekstu i multimediów działa bez tego.

Not authorized to send Apple events to Messages. (-1743)

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

Włączanie prywatnego API imsg

imsg działa w dwóch trybach operacyjnych:

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

Aby uzyskać powierzchnię zaawansowanych akcji dokumentowaną na tej stronie kanału, potrzebujesz trybu prywatnego API. README imsg jednoznacznie określa wymaganie:

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

Technika wstrzykiwania pomocnika używa własnej dylib imsg, aby uzyskać dostęp 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

   Dane wyjściowe imsg status --json raportują bridge_version, rpc_methods i selectors dla poszczególnych metod, aby przed rozpoczęciem można było zobaczyć, co obsługuje bieżąca kompilacja.

2. Wyłącz System Integrity Protection oraz (na nowoczesnym macOS) Library Validation. Wstrzyknięcie niepochodzącej od Apple pomocniczej dylib do podpisanej przez Apple aplikacji Messages.app wymaga wyłączenia SIP oraz poluzowania walidacji bibliotek. Krok SIP w trybie Recovery zależy od wersji macOS:

   • macOS 10.13-10.15 (Sierra-Catalina): wyłącz Library Validation przez Terminal, uruchom ponownie w Recovery Mode, wykonaj csrutil disable, uruchom ponownie.
   • macOS 11+ (Big Sur i nowsze), Intel: Recovery Mode (albo Internet Recovery), csrutil disable, uruchom ponownie.
   • macOS 11+, Apple Silicon: sekwencja startu przyciskiem zasilania, aby wejść do Recovery; w nowszych wersjach macOS przytrzymaj klawisz Left Shift podczas kliknięcia Continue, a następnie csrutil disable. Konfiguracje maszyn wirtualnych używają osobnego procesu, więc najpierw zrób migawkę VM.

   W macOS 11 i nowszych samo csrutil disable zwykle nie wystarcza. Apple nadal wymusza walidację bibliotek wobec Messages.app jako pliku binarnego platformy, więc pomocnik podpisany adhoc jest odrzucany (Library Validation failed: ... platform binary, but mapped file is not) nawet przy wyłączonym SIP. Po wyłączeniu SIP wyłącz także walidację bibliotek i uruchom ponownie:

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

   macOS 26 (Tahoe), zweryfikowane na 26.5.1: wyłączone SIP plus powyższe polecenie DisableLibraryValidation wystarczają do wstrzyknięcia pomocnika w wersjach od 26.0 do 26.5.x. Nie są wymagane żadne boot-args. Plist jest czynnikiem decydującym i najczęściej pomijanym krokiem, gdy wstrzyknięcie na Tahoe kończy się niepowodzeniem:

   • Z plist: imsg launch wstrzykuje, a imsg status raportuje advanced_features: true.
   • Bez plist (nawet z wyłączonym SIP): imsg launch kończy się niepowodzeniem z Failed to launch: Timeout waiting for Messages.app to initialize. AMFI odrzuca pomocnik adhoc podczas ładowania, więc most nigdy nie staje się gotowy, a uruchomienie przekracza limit czasu. Ten timeout jest objawem, na który większość osób trafia na Tahoe, a poprawką jest powyższy plist, nie nic bardziej radykalnego.

   Zostało to potwierdzone kontrolowanym testem przed/po na macOS 26.5.1 (Apple Silicon): z plist dylib mapuje się do Messages.app, a most się uruchamia; po usunięciu plist i restarcie imsg launch generuje powyższy błąd timeout, a dylib nie jest zmapowana.

   Jeśli wstrzykiwanie imsg launch albo konkretne selectors zaczynają zwracać fałsz po uaktualnieniu macOS, ta blokada jest zwykle przyczyną. Sprawdź stan SIP i walidacji bibliotek, zanim uznasz, że nie powiódł się sam krok SIP. Jeśli te ustawienia są poprawne, a most nadal nie może wykonać wstrzyknięcia, zbierz imsg status --json oraz wynik imsg launch i zgłoś to do projektu imsg zamiast osłabiać dodatkowe systemowe mechanizmy bezpieczeństwa.

   Wykonaj procedurę Apple w trybie odzyskiwania dla swojego Maca, aby wyłączyć SIP przed uruchomieniem imsg launch.

3. Wstrzyknij pomocnika. Przy wyłączonym SIP i zalogowanej aplikacji Messages.app:

   imsg launch

   imsg launch odmawia wstrzyknięcia, gdy SIP jest nadal włączony, więc służy to także jako potwierdzenie, że krok 2 zadziałał.

4. Zweryfikuj most z OpenClaw:

   openclaw channels status --probe

   Wpis iMessage powinien zgłaszać works, a imsg status --json | jq '{rpc_methods, selectors}' powinno pokazać możliwości udostępniane przez Twoją wersję macOS. Tworzenie ankiet wymaga selectors.pollPayloadMessage; głosowanie wymaga zarówno selectors.pollVoteMessage, jak i metody RPC poll.vote. Plugin OpenClaw ogłasza tylko akcje obsługiwane przez zbuforowaną sondę, natomiast pusta pamięć podręczna pozostaje optymistyczna i sonduje przy pierwszym wysłaniu.

Jeśli openclaw channels status --probe zgłasza kanał jako works, ale konkretne akcje podczas wysyłania zgłaszają błąd „iMessage <action> wymaga mostu prywatnego API imsg”, uruchom ponownie imsg launch — pomocnik może wypaść (restart Messages.app, aktualizacja OS itp.), a zbuforowany status available: true będzie nadal ogłaszał akcje do czasu odświeżenia przez kolejną sondę.

Gdy nie możesz wyłączyć SIP

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

• imsg wraca do trybu podstawowego — tylko tekst + media + odbieranie.
• Plugin OpenClaw nadal ogłasza wysyłanie tekstu/mediów i monitorowanie przychodzące; ukrywa tylko react, edit, unsend, reply, sendWithEffect oraz operacje grupowe z powierzchni 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 Dedykowany użytkownik bota macOS (osobna tożsamość iMessage) poniżej.

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 rozmów ACP

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

Szybki przepływ operatora:

• Uruchom /acp spawn codex --bind here wewnątrz DM albo dozwolonego czatu grupowego.
• Przyszłe wiadomości w tej samej rozmowie 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 albo user@example.com
• chat_id:<id> (zalecane dla stabilnych powiązań grup)
• 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: "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 "$@"

Media, dzielenie na części i cele dostarczania

imsg chats --limit 20

Akcje prywatnego API

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

{  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 zapisy konfiguracji inicjowane przez kanał (dla /config set|unset, gdy commands.config: true).

Wyłącz:

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

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

Gdy użytkownik wpisze razem polecenie i URL — np. Dump https://example.com/article — aplikacja Wiadomości 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.

Te dwa wiersze docierają do OpenClaw w odstępie ~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 — kiedy kontekst polecenia jest już utracony. To jest potok wysyłania Apple, a nie coś wprowadzanego przez OpenClaw lub imsg.

channels.imessage.coalesceSameSenderDms włącza dla DM buforowanie kolejnych wierszy od tego samego nadawcy. Gdy imsg ujawnia strukturalny znacznik podglądu URL balloon_bundle_id: "com.apple.messages.URLBalloonProvider" w jednym z wierszy źródłowych, OpenClaw scala tylko tę rzeczywistą dzieloną wysyłkę i zachowuje pozostałe zbuforowane wiersze jako osobne tury. W starszych kompilacjach imsg, które w ogóle nie emitują metadanych dymka, OpenClaw nie potrafi odróżnić dzielonej wysyłki od osobnych wysyłek, więc fallback polega na scaleniu koszyka. Zachowuje to zachowanie sprzed metadanych zamiast regresji dzielonych wysyłek Dump <url> do dwóch tur. Czaty grupowe nadal wysyłają per wiadomość, aby zachować strukturę tur wielu użytkowników.

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

{  messages: {    inbound: {      byChannel: {        // 7000 ms covers observed Messages.app URL-preview delays.        imessage: 7000,      },    },  },}

Scenariusze i co widzi agent

Kolumna „Flaga włączona” pokazuje zachowanie w kompilacji imsg, która emituje balloon_bundle_id. W starszych kompilacjach imsg, które w ogóle nie emitują metadanych dymku, wiersze oznaczone poniżej jako „Dwie tury” / „N tur” zamiast tego wracają do starszego scalania (jedna tura): OpenClaw nie może strukturalnie odróżnić wysyłki podzielonej od osobnych wysyłek, więc zachowuje scalanie sprzed metadanych. Precyzyjne rozdzielanie aktywuje się, gdy kompilacja zacznie emitować metadane dymku.

Odzyskiwanie przychodzących wiadomości po restarcie mostka lub Gateway

iMessage odzyskuje wiadomości pominięte, gdy Gateway był wyłączony, a jednocześnie tłumi przestarzałą „bombę zaległości”, którą Apple może opróżnić po odzyskiwaniu Push. Domyślne zachowanie jest zawsze włączone i opiera się na deduplikacji przychodzącej.

• Deduplikacja odtworzeń. Każda wysłana przychodząca wiadomość jest rejestrowana według swojego Apple GUID w trwałym stanie Plugin (imessage.inbound-dedupe), zajmowana podczas ingestii i zatwierdzana po obsłużeniu (zwalniana przy błędzie przejściowym, aby można było ponowić próbę). Wszystko, co już obsłużono, jest odrzucane zamiast wysyłane drugi raz. To pozwala odzyskiwaniu agresywnie odtwarzać bez księgowania każdej wiadomości osobno.
• Odzyskiwanie po przestoju. Przy starcie monitor zapamiętuje ostatni wysłany chat.db rowid (utrwalony kursor per konto) i przekazuje go do imsg watch.subscribe jako since_rowid, więc imsg odtwarza wiersze, które trafiły podczas niedostępności Gateway, a potem śledzi na żywo. Odtwarzanie jest ograniczone do najnowszych wierszy i do wiadomości mających maksymalnie ~2 godziny, a deduplikacja odrzuca wszystko, co już obsłużono.
• Bariera wieku przestarzałych zaległości. Wiersze powyżej granicy startowej są rzeczywiście na żywo; taki, którego data wysłania jest o ponad ~15 minut starsza niż czas przybycia, jest zaległością opróżnioną przez Push i jest tłumiony. Odtworzone wiersze (na granicy lub poniżej) używają zamiast tego szerszego okna odzyskiwania, więc niedawno pominięta wiadomość zostanie dostarczona, a dawna historia nie.

Odzyskiwanie działa zarówno w lokalnych, jak i zdalnych konfiguracjach cliPath, ponieważ odtwarzanie since_rowid działa przez to samo połączenie RPC imsg. Różnicą jest okno: gdy Gateway może odczytać chat.db (lokalnie), zakotwicza granicę rowid startu, ogranicza zakres odtwarzania i dostarcza pominięte wiadomości mające maksymalnie kilka godzin. Przez zdalne SSH cliPath nie może odczytać bazy danych, więc odtwarzanie nie ma ograniczenia, a każdy wiersz używa bariery wieku dla trybu na żywo — nadal odzyskuje niedawno pominięte wiadomości i nadal tłumi stare zaległości, tylko z węższym oknem na żywo. Uruchom Gateway na Macu z Messages, aby uzyskać szersze okno odzyskiwania.

Sygnał widoczny dla operatora

Tłumione zaległości są logowane na domyślnym poziomie, nigdy nie są po cichu odrzucane (flaga recovery pokazuje, które okno zastosowano):

imessage: suppressed stale inbound backlog account=<id> sent=<iso> recovery=<bool> (&lt;N&gt; suppressed since start)

Migracja

channels.imessage.catchup.* jest przestarzałe — odzyskiwanie po przestoju jest teraz automatyczne i nie wymaga konfiguracji w nowych instalacjach. Istniejące konfiguracje z catchup.enabled: true pozostają honorowane jako profil zgodności dla okna odtwarzania odzyskiwania. Wyłączone bloki catchup (enabled: false albo brak enabled: true) są 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"

Wskaźniki odniesienia konfiguracji

• Dokumentacja 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 przełączenie 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