iMessage

Status: native externe CLI-Integration. Der Gateway startet imsg rpc und kommuniziert über stdio mittels JSON-RPC — ohne separaten Daemon oder Port. Der Modus der privaten API wird für einen vollständigen iMessage-Kanal dringend empfohlen; Antworten, Tapbacks, Effekte, Umfragen, Antworten auf Anhänge und Gruppenaktionen erfordern imsg launch sowie eine erfolgreiche Prüfung der privaten API.

Für die gängige lokale Einrichtung kann die OpenClaw-Einrichtung eine vom Benutzer bestätigte Homebrew-Installation oder -Aktualisierung von imsg auf dem bei Messages angemeldeten Mac anbieten. Die manuelle Einrichtung und Topologien mit SSH-Wrapper werden weiterhin vom Betreiber verwaltet: Installieren oder aktualisieren Sie imsg in demselben Benutzerkontext, in dem der Gateway oder Wrapper ausgeführt wird.

Schnelleinrichtung

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", // used for SCP attachment fetches  includeAttachments: true,  // Optional: extra allowed attachment roots (merged with the default  // /Users/*/Library/Messages/Attachments).  attachmentRoots: ["/Users/*/Library/Messages/Attachments"],  remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],},},}

Anforderungen und Berechtigungen (macOS)

• Messages muss auf dem Mac angemeldet sein, auf dem imsg ausgeführt wird.
• Vollständiger Festplattenzugriff ist für den Prozesskontext erforderlich, in dem OpenClaw/imsg ausgeführt wird (Zugriff auf die Messages-Datenbank).
• Die Automatisierungsberechtigung ist erforderlich, um Nachrichten über Messages.app zu senden.
• Für erweiterte Aktionen (Reaktion / Bearbeiten / Senden rückgängig machen / Antwort im Thread / Effekte / Umfragen / Gruppenoperationen) muss der Systemintegritätsschutz deaktiviert sein — siehe Private API von imsg aktivieren. Das grundlegende Senden und Empfangen von Text und Medien funktioniert ohne diese Deaktivierung.

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

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

Private API von imsg aktivieren

imsg wird mit zwei Betriebsmodi ausgeliefert. Für OpenClaw ist der Modus der privaten API die empfohlene Einrichtung, da er dem Kanal die nativen iMessage-Aktionen bereitstellt, die Benutzer erwarten. Der Basismodus bleibt für Installationen mit geringem Risiko, die erste Überprüfung oder Hosts nützlich, auf denen SIP nicht deaktiviert werden kann.

• Basismodus (Standard, keine SIP-Änderungen erforderlich): ausgehender Text und ausgehende Medien über send, Überwachung/Verlauf eingehender Nachrichten, Chatliste. Dies ist der sofort verfügbare Funktionsumfang einer neuen brew install steipete/tap/imsg-Installation mit den oben genannten standardmäßigen macOS-Berechtigungen.
• Modus der privaten API: imsg injiziert eine Hilfsbibliothek vom Typ dylib in Messages.app, um interne IMCore-Funktionen aufzurufen. Dadurch werden react, edit, unsend, reply (in Threads), sendWithEffect, poll und poll-vote (native Messages-Umfragen), renameGroup, setGroupIcon, addParticipant, removeParticipant, leaveGroup sowie Tippindikatoren und Lesebestätigungen ermöglicht.

Die auf dieser Seite empfohlene Aktionsoberfläche erfordert den Modus der privaten API. Die README-Datei von imsg beschreibt die Anforderung ausdrücklich:

Erweiterte Funktionen wie read, typing, launch, Bridge-gestütztes Senden umfangreicher Inhalte, Nachrichtenänderungen und Chatverwaltung sind optional. Sie erfordern, dass SIP deaktiviert und eine Hilfsbibliothek vom Typ dylib in Messages.app injiziert wird. imsg launch verweigert die Injektion, wenn SIP aktiviert ist.

Die Technik zur Injektion der Hilfsbibliothek verwendet die eigene dylib von imsg, um auf die privaten APIs von Messages zuzugreifen. Im OpenClaw-iMessage-Pfad gibt es weder einen Drittanbieterserver noch eine BlueBubbles-Laufzeitumgebung.

Einrichtung

1. Installieren (oder aktualisieren) Sie imsg auf dem Mac, auf dem Messages.app ausgeführt wird:

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

   Die Ausgabe von imsg status --json meldet bridge_version, rpc_methods und methodenspezifische selectors, sodass Sie vor dem Start erkennen können, welche Funktionen der aktuelle Build unterstützt.

2. Deaktivieren Sie den Systemintegritätsschutz und (auf modernen macOS-Versionen) die Bibliotheksvalidierung. Das Einschleusen einer nicht von Apple stammenden Hilfs-dylib in die von Apple signierte Messages.app erfordert, dass SIP deaktiviert und die Bibliotheksvalidierung gelockert ist. Der SIP-Schritt im Wiederherstellungsmodus hängt von der macOS-Version ab:

   • macOS 10.13-10.15 (Sierra-Catalina): Deaktivieren Sie die Bibliotheksvalidierung über das Terminal, starten Sie im Wiederherstellungsmodus neu, führen Sie csrutil disable aus und starten Sie erneut.
   • macOS 11+ (Big Sur und neuer), Intel: Starten Sie im Wiederherstellungsmodus (oder über die Internetwiederherstellung), führen Sie csrutil disable aus und starten Sie neu.
   • macOS 11+, Apple Silicon: Verwenden Sie die Startsequenz mit dem Ein-/Ausschalter, um die Wiederherstellung aufzurufen; halten Sie bei aktuellen macOS-Versionen die Taste Left Shift gedrückt, wenn Sie auf Continue klicken, und führen Sie anschließend csrutil disable aus. Für virtuelle Maschinen gilt ein separater Ablauf; erstellen Sie daher zuerst einen VM-Snapshot.

   Unter macOS 11 und neuer reicht csrutil disable allein normalerweise nicht aus. Apple erzwingt weiterhin die Bibliotheksvalidierung für Messages.app als Plattformbinärdatei, sodass eine ad hoc signierte Hilfskomponente selbst bei deaktiviertem SIP abgewiesen wird (Library Validation failed: ... platform binary, but mapped file is not). Deaktivieren Sie nach SIP auch die Bibliotheksvalidierung und starten Sie neu:

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

   macOS 26 (Tahoe), verifiziert unter 26.5.1: Deaktiviertes SIP zusammen mit dem obigen Befehl DisableLibraryValidation genügt, um die Hilfskomponente unter den Versionen 26.0 bis 26.5.x einzuschleusen. Es sind keine Boot-Argumente erforderlich. Die plist ist der entscheidende Faktor und der am häufigsten fehlende Schritt, wenn das Einschleusen unter Tahoe fehlschlägt:

   • Mit der plist: imsg launch schleust die Hilfskomponente ein und imsg status meldet advanced_features: true.
   • Ohne die plist (selbst bei deaktiviertem SIP): imsg launch schlägt mit Failed to launch: Timeout waiting for Messages.app to initialize fehl. AMFI weist die ad hoc signierte Hilfskomponente beim Laden ab, sodass die Bridge nie bereit wird und der Start wegen einer Zeitüberschreitung abbricht. Diese Zeitüberschreitung ist das Symptom, auf das die meisten Personen unter Tahoe stoßen; die Lösung ist die obige plist und keine drastischere Maßnahme.

   Falls das Einschleusen über imsg launch oder bestimmte selectors nach einem macOS-Upgrade beginnen, false zurückzugeben, ist diese Sperre üblicherweise die Ursache. Prüfen Sie den Status von SIP und der Bibliotheksvalidierung, bevor Sie davon ausgehen, dass der SIP-Schritt selbst fehlgeschlagen ist. Wenn diese Einstellungen korrekt sind und die Bridge weiterhin nichts einschleusen kann, erfassen Sie imsg status --json sowie die Ausgabe von imsg launch und melden Sie dies dem Projekt imsg, statt weitere systemweite Sicherheitskontrollen zu schwächen.

3. Schleusen Sie die Hilfskomponente ein. Bei deaktiviertem SIP und angemeldeter Messages.app:

   imsg launch

   imsg launch verweigert das Einschleusen, solange SIP aktiviert ist. Dies dient daher zugleich als Bestätigung, dass Schritt 2 erfolgreich war.

4. Überprüfen Sie die Bridge über OpenClaw:

   openclaw channels status --probe

   Der iMessage-Eintrag sollte works melden, und imsg status --json | jq '{rpc_methods, selectors}' sollte die von Ihrem macOS-Build bereitgestellten Fähigkeiten anzeigen. Das Erstellen von Umfragen erfordert selectors.pollPayloadMessage; Abstimmungen erfordern sowohl selectors.pollVoteMessage als auch die RPC-Methode poll.vote. Das OpenClaw-Plugin bietet nur Aktionen an, die von der zwischengespeicherten Prüfung unterstützt werden, während ein leerer Cache optimistisch bleibt und beim ersten Versand eine Prüfung durchführt.

Wenn openclaw channels status --probe den Kanal als works meldet, bestimmte Aktionen aber beim Versand den Fehler „iMessage <action> requires the imsg private API bridge“ auslösen, führen Sie imsg launch erneut aus. Die Hilfskomponente kann ausfallen (Neustart von Messages.app, Betriebssystemupdate usw.), und der zwischengespeicherte Status available: true bietet weiterhin Aktionen an, bis die nächste Prüfung ihn aktualisiert.

Wenn SIP aktiviert bleibt

Falls das Deaktivieren von SIP für Ihr Bedrohungsmodell nicht akzeptabel ist:

• imsg wechselt in den Basismodus zurück — nur Text, Medien und Empfang.
• Das OpenClaw-Plugin bietet weiterhin das Senden von Text und Medien sowie die Überwachung eingehender Nachrichten an; react, edit, unsend, reply, sendWithEffect und Gruppenoperationen werden aus der Aktionsoberfläche ausgeblendet (entsprechend der Fähigkeitssperre pro Methode).
• Sie können für die iMessage-Arbeitslast einen separaten Mac ohne Apple Silicon (oder einen dedizierten Bot-Mac) mit deaktiviertem SIP verwenden, während SIP auf Ihren primären Geräten aktiviert bleibt. Siehe unten Dedizierter macOS-Bot-Benutzer (separate iMessage-Identität).

Zugriffskontrolle und Routing

{  channels: {    imessage: {      groupPolicy: "allowlist",      groupAllowFrom: ["+15555550123"],      groups: {        "*": { systemPrompt: "Verwenden Sie britische Rechtschreibung." },        "8421": {          requireMention: true,          systemPrompt: "Dies ist der Chat für die Rufbereitschaft. Begrenzen Sie Antworten auf höchstens 3 Sätze.",        },        "9907": {          // explizite Unterdrückung: Der Platzhalter "Verwenden Sie britische Rechtschreibung." gilt hier nicht          systemPrompt: "",        },      },    },  },}

ACP-Konversationsbindungen

iMessage-Chats können an ACP-Sitzungen gebunden werden.

Schneller Ablauf für Betriebspersonal:

• Führen Sie /acp spawn codex --bind here innerhalb der Direktnachricht oder des zulässigen Gruppenchats aus.
• Künftige Nachrichten in derselben iMessage-Konversation werden an die erzeugte ACP-Sitzung weitergeleitet.
• /new und /reset setzen dieselbe gebundene ACP-Sitzung direkt zurück.
• /acp close schließt die ACP-Sitzung und entfernt die Bindung.

Konfigurierte persistente Bindungen verwenden Einträge der obersten Ebene bindings[] mit type: "acp" und match.channel: "imessage".

match.peer.id kann Folgendes verwenden:

• normalisiertes Handle für Direktnachrichten wie +15555550123 oder user@example.com
• chat_id:<id> (für stabile Gruppenbindungen empfohlen)
• chat_guid:<guid>
• chat_identifier:<identifier>

Beispiel:

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

Informationen zum gemeinsamen Verhalten von ACP-Bindungen finden Sie unter ACP-Agenten.

Bereitstellungsmuster

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

Medien, Aufteilung und Zustellungsziele

imsg chats --limit 20

Aktionen der privaten API

Wenn imsg launch ausgeführt wird und openclaw channels status --probe den Wert privateApi.available: true meldet, kann das Nachrichten-Tool zusätzlich zum normalen Textversand iMessage-native Aktionen verwenden.

Alle Aktionen sind standardmäßig aktiviert; verwenden Sie channels.imessage.actions, um einzelne Aktionen zu deaktivieren:

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

Konfigurationsänderungen

iMessage erlaubt standardmäßig vom Kanal initiierte Konfigurationsänderungen (für /config set|unset, wenn commands.config: true).

Deaktivieren:

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

Zusammenführen aufgeteilt gesendeter Direktnachrichten (Befehl + URL in einer Eingabe)

Apple kann einen Befehl und dessen URL-Vorschau als separate physische chat.db-Zeilen speichern. imsg ab Version 0.13.1 führt diese Zeilen zusammen, bevor Überwachung, Verlauf oder Suche die Nachricht zurückgeben. Dadurch empfängt OpenClaw eine einzige logische eingehende Nachricht, ohne eine kanalspezifische Latenz für Direktnachrichten hinzuzufügen.

Für iMessage ist keine Einstellung zum Zusammenführen erforderlich. Der außer Betrieb genommene Schlüssel channels.imessage.coalesceSameSenderDms wird von openclaw doctor --fix entfernt. Die allgemeine messages.inbound-Entprellung bleibt verfügbar, wenn Sie absichtlich schnell aufeinanderfolgende Textnachrichten eines Kanals bündeln möchten.

Wenn Sendungen aus Befehl und URL als separate Agentendurchläufe eintreffen, aktualisieren Sie imsg auf dem Messages-Mac:

brew update && brew upgrade imsg

Wiederherstellung eingehender Nachrichten nach einem Neustart der Bridge oder des Gateways

iMessage stellt Nachrichten wieder her, die während des Ausfalls des Gateways verpasst wurden, und unterdrückt gleichzeitig die veraltete „Backlog-Bombe“, die Apple nach einer Push-Wiederherstellung ausgeben kann. Das auf dauerhaftem Eingang und einer Altersgrenze basierende Standardverhalten ist immer aktiviert.

• Dauerhafter Schutz vor Wiederholungen. Bevor OpenClaw den Wiederherstellungscursor fortschreibt, protokolliert es jede Rohzeile in der gemeinsamen SQLite-Eingangswarteschlange und verwendet deren Apple-GUID als Ereignis-ID. Eine abgeschlossene Zeile hinterlässt für etwa 4 Stunden einen Tombstone, wobei die Anzahl auf 10.000 Einträge begrenzt ist. Dadurch wird eine Wiederholung mit derselben GUID auch nach einem Neustart verworfen. Eine ausstehende Zeile bleibt wiederherstellbar, bis sie vom Versand übernommen wird.
• Wiederherstellung nach Ausfallzeiten. Beim Start merkt sich der Monitor die Zeilen-ID der letzten dauerhaft angenommenen chat.db-Zeile (einen persistenten Cursor pro Konto) und übergibt sie als since_rowid an imsg watch.subscribe. Dadurch gibt imsg Zeilen erneut wieder, die noch nicht protokolliert wurden, und folgt anschließend den Live-Ereignissen. Vor einem Absturz protokollierte Zeilen werden aus SQLite fortgesetzt. Die Wiederholung ist auf die neuesten 500 Zeilen und auf Nachrichten mit einem Alter von bis zu etwa 2 Stunden begrenzt; GUID-Tombstones verwerfen alle bereits verarbeiteten Einträge.
• Altersgrenze für veraltete Rückstände. Zeilen oberhalb der Startgrenze sind tatsächlich live; liegt das Sendedatum einer solchen Zeile mehr als etwa 15 Minuten vor ihrem Eingang, handelt es sich um den durch Push ausgegebenen Rückstand, der unterdrückt wird. Wiederholte Zeilen (an oder unterhalb der Grenze) verwenden stattdessen das größere Wiederherstellungsfenster. Dadurch wird eine kürzlich verpasste Nachricht zugestellt, während alte Verlaufsdaten nicht zugestellt werden.

Die Wiederherstellung funktioniert sowohl bei lokalen als auch bei entfernten cliPath-Konfigurationen, da die since_rowid-Wiederholung über dieselbe imsg-RPC-Verbindung ausgeführt wird. Der Unterschied liegt im Zeitfenster: Wenn das Gateway chat.db lesen kann (lokal), verankert es die Startgrenze der Zeilen-ID, begrenzt den Wiederholungsumfang und stellt verpasste Nachrichten mit einem Alter von bis zu einigen Stunden zu. Über eine entfernte SSH-cliPath kann es die Datenbank nicht lesen. Daher ist die Wiederholung unbegrenzt und jede Zeile verwendet die Live-Altersgrenze. Kürzlich verpasste Nachrichten werden weiterhin wiederhergestellt und alte Rückstände weiterhin unterdrückt, jedoch mit dem kleineren Live-Zeitfenster. Führen Sie das Gateway auf dem Messages-Mac aus, um das größere Wiederherstellungsfenster zu verwenden.

Für Betreiber sichtbares Signal

Unterdrückte Rückstände werden auf der Standardprotokollierungsstufe protokolliert und niemals stillschweigend verworfen (das Flag recovery zeigt, welches Zeitfenster angewendet wurde):

imessage: veralteter eingehender Rückstand unterdrückt account=<id> sent=<iso> recovery=<bool> (&lt;N&gt; seit dem Start unterdrückt)

Migration

channels.imessage.catchup.* ist veraltet – die Wiederherstellung nach Ausfallzeiten erfolgt automatisch und benötigt bei neuen Konfigurationen keine Konfiguration. Vorhandene Konfigurationen mit catchup.enabled: true werden weiterhin als Kompatibilitätsprofil für das Wiederholungsfenster der Wiederherstellung berücksichtigt. Deaktivierte Catchup-Blöcke (enabled: false oder ohne enabled: true) wurden außer Betrieb genommen; openclaw doctor --fix entfernt sie.

Fehlerbehebung

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"

Verweise zur Konfigurationsreferenz

• Konfigurationsreferenz – iMessage
• Gateway-Konfiguration
• Kopplung

Verwandte Themen

• Kanalübersicht — alle unterstützten Kanäle
• Entfernung von BlueBubbles und der imsg-iMessage-Pfad — Ankündigung und Zusammenfassung der Migration
• Umstieg von BlueBubbles — Tabelle zur Übertragung der Konfiguration und schrittweise Umstellung
• Kopplung — Authentifizierung von Direktnachrichten und Kopplungsablauf
• Gruppen — Verhalten von Gruppenchats und Erwähnungsbeschränkung
• Kanal-Routing — Sitzungs-Routing für Nachrichten
• Sicherheit — Zugriffsmodell und Härtung