iMessage

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

Bei der üblichen lokalen Einrichtung kann die OpenClaw-Einrichtung eine vom Benutzer bestätigte Installation oder Aktualisierung von imsg über Homebrew 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 im selben 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", // wird für den Abruf von Anhängen per SCP verwendet  includeAttachments: true,  // Optional: zusätzliche zulässige Stammverzeichnisse für Anhänge (werden mit dem  // Standardpfad /Users/*/Library/Messages/Attachments zusammengeführt).  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.
• Für den Prozesskontext, in dem OpenClaw/imsg ausgeführt wird, ist vollständiger Festplattenzugriff erforderlich (Zugriff auf die Messages-Datenbank).
• Zum Senden von Nachrichten über Messages.app ist eine Automatisierungsberechtigung erforderlich.
• Für erweiterte Aktionen (Reagieren / Bearbeiten / Zurückziehen / Antwort in einem Thread / Effekte / Umfragen / Gruppenoperationen) muss der Systemintegritätsschutz deaktiviert sein – siehe Private API von imsg aktivieren. Das grundlegende Senden und Empfangen von Texten und Medien funktioniert auch ohne diese Änderung.

Nicht zum Senden von Apple-Ereignissen an Messages autorisiert. (-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 wird der Modus „Private API“ empfohlen, da er dem Kanal die nativen iMessage-Aktionen bereitstellt, die Benutzer erwarten. Der Basismodus bleibt für risikoarme Installationen, die anfängliche Überprüfung oder Hosts nützlich, auf denen SIP nicht deaktiviert werden kann.

• Basismodus (Standard, keine SIP-Änderungen erforderlich): ausgehende Texte und Medien über send, Überwachung/Verlauf eingehender Nachrichten, Chatliste. Dies ist der standardmäßig verfügbare Funktionsumfang nach einem neuen brew install steipete/tap/imsg und der Erteilung der oben aufgeführten standardmäßigen macOS-Berechtigungen.
• Modus „Private API“: imsg injiziert eine Hilfs-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 und leaveGroup sowie Tippanzeigen und Lesebestätigungen freigeschaltet.

Der auf dieser Seite empfohlene Aktionsumfang erfordert den Modus „Private API“. Die imsg-README nennt die Voraussetzung ausdrücklich:

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

Die Technik zur Injektion des Hilfsmoduls verwendet die eigene dylib von imsg, um auf die privaten APIs von Messages zuzugreifen. Im iMessage-Pfad von OpenClaw gibt es keinen Drittanbieterserver und keine BlueBubbles-Laufzeit.

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 die selectors jeder Methode, sodass Sie vor dem Start sehen können, was der aktuelle Build unterstützt.

2. Deaktivieren Sie den Systemintegritätsschutz und (unter modernen macOS-Versionen) die Bibliotheksvalidierung. Das Injizieren 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 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 über den 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 ein ad hoc signierter Helper selbst bei deaktiviertem SIP abgelehnt wird (Library Validation failed: ... platform binary, but mapped file is not). Deaktivieren Sie nach dem Deaktivieren von SIP zusätzlich die Bibliotheksvalidierung und starten Sie das System 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 reicht aus, um den Helper unter 26.0 bis einschließlich 26.5.x zu injizieren. Es sind keine Boot-Argumente erforderlich. Die plist-Datei ist der entscheidende Faktor und der am häufigsten fehlende Schritt, wenn die Injektion unter Tahoe fehlschlägt:

   • Mit der plist-Datei: imsg launch injiziert den Helper und imsg status meldet advanced_features: true.
   • Ohne die plist-Datei (selbst bei deaktiviertem SIP): imsg launch schlägt mit Failed to launch: Timeout waiting for Messages.app to initialize fehl. AMFI lehnt den ad hoc signierten Helper 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-Datei und keine drastischere Maßnahme.

   Wenn die Injektion mit imsg launch oder bestimmte selectors nach einem macOS-Upgrade den Wert „false“ zurückgeben, 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 nicht injiziert werden kann, erfassen Sie imsg status --json zusammen mit der Ausgabe von imsg launch und melden Sie dies dem Projekt imsg, anstatt weitere systemweite Sicherheitskontrollen abzuschwächen.

3. Injizieren Sie den Helper. Bei deaktiviertem SIP und angemeldeter Messages.app:

   imsg launch

   imsg launch verweigert die Injektion, solange SIP aktiviert ist, und dient damit zugleich als Bestätigung, dass Schritt 2 wirksam 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; für Abstimmungen sind sowohl selectors.pollVoteMessage als auch die RPC-Methode poll.vote erforderlich. Das OpenClaw-Plugin bietet nur Aktionen an, die von der zwischengespeicherten Prüfung unterstützt werden, während bei einem leeren Cache zunächst optimistisch vorgegangen und beim ersten Dispatch geprüft wird.

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

Wenn SIP aktiviert bleibt

Wenn 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; es blendet react, edit, unsend, reply, sendWithEffect und Gruppenoperationen aus der Aktionsoberfläche aus (entsprechend der Fähigkeitsprüfung pro Methode).
• Sie können einen separaten Mac ohne Apple Silicon (oder einen dedizierten Bot-Mac) mit deaktiviertem SIP für die iMessage-Workload betreiben, 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 die britische Rechtschreibung." },

        "8421": {

          requireMention: true,

          systemPrompt: "Dies ist der Chat für die Rufbereitschaft. Beschränken Sie Antworten auf höchstens 3 Sätze.",

        },        "9907": {

          // explizite Unterdrückung: Der Platzhalter „Use British spelling.“ gilt hier nicht

          systemPrompt: "",        },

      },    },  },}

ACP-Konversationsbindungen

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

Schneller Ablauf für Betreiber:

• Führen Sie /acp spawn codex --bind here in der Direktnachricht oder im zulässigen Gruppenchat 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 bindings[]-Einträge auf oberster Ebene mit type: "acp" und match.channel: "imessage".

match.peer.id kann Folgendes verwenden:

• normalisiertes DM-Handle 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 aufgeteilter Direktnachrichten (Befehl und URL in einer Eingabe)

Wenn ein Benutzer einen Befehl und eine URL gemeinsam eingibt – z. B. Dump https://example.com/article –, teilt Apples Nachrichten-App den Versand in zwei separate chat.db-Zeilen auf:

1. Eine Textnachricht ("Dump").
2. Eine URL-Vorschau-Blase ("https://...") mit Bildern der OG-Vorschau als Anhänge.

Die beiden Zeilen treffen bei den meisten Konfigurationen mit einem Abstand von ~0.8-2.0 s bei OpenClaw ein. Ohne Zusammenführung erhält der Agent in Turn 1 nur den Befehl (und antwortet häufig „Senden Sie mir die URL“), bevor die URL in Turn 2 eintrifft. Dies ist Teil der Versandpipeline von Apple und wird weder von OpenClaw noch von imsg verursacht.

channels.imessage.coalesceSameSenderDms aktiviert für eine Direktnachricht die Pufferung aufeinanderfolgender Zeilen desselben Absenders. Wenn imsg in einer der Quellzeilen die strukturelle URL-Vorschaumarkierung balloon_bundle_id: "com.apple.messages.URLBalloonProvider" bereitstellt, führt OpenClaw nur diesen tatsächlich aufgeteilten Versand zusammen und behält alle anderen gepufferten Zeilen als separate Turns bei. Bei älteren imsg-Builds, die keinerlei Balloon-Metadaten ausgeben, kann OpenClaw einen aufgeteilten Versand nicht von separaten Sendungen unterscheiden und führt daher ersatzweise den Bucket zusammen. Dadurch bleibt das Verhalten vor Einführung der Metadaten erhalten, statt aufgeteilte Sendungen vom Typ Dump <url> in zwei Turns aufzuteilen. Gruppenchats werden weiterhin nach einzelnen Nachrichten verarbeitet, sodass die Turn-Struktur bei mehreren Benutzern erhalten bleibt.

{  channels: {    imessage: {      coalesceSameSenderDms: true, // aktivieren (Standard: false)    },  },}

{  messages: {    inbound: {      byChannel: {        // 7000 ms decken beobachtete Verzögerungen bei URL-Vorschauen von Messages.app ab.        imessage: 7000,      },    },  },}

Szenarien und was der Agent sieht

Die Spalte „Flag aktiviert“ zeigt das Verhalten bei einem imsg-Build, der balloon_bundle_id ausgibt. Bei älteren imsg-Builds, die keinerlei Balloon-Metadaten ausgeben, werden die unten mit „Zwei Turns“/„N Turns“ gekennzeichneten Zeilen stattdessen ersatzweise wie bisher zusammengeführt (ein Turn): OpenClaw kann einen aufgeteilten Versand strukturell nicht von separaten Sendungen unterscheiden und behält daher die Zusammenführung aus der Zeit vor den Metadaten bei. Die präzise Trennung wird aktiviert, sobald der Build Balloon-Metadaten ausgibt.

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 Standardverhalten ist immer aktiviert und basiert auf der Deduplizierung eingehender Nachrichten.

• Wiedergabe-Deduplizierung. Jede weitergeleitete eingehende Nachricht wird anhand ihrer Apple-GUID im persistenten Plugin-Zustand (imessage.inbound-dedupe) erfasst, bei der Aufnahme beansprucht und nach der Verarbeitung bestätigt (bei einem vorübergehenden Fehler wieder freigegeben, damit ein erneuter Versuch möglich ist). Bereits verarbeitete Nachrichten werden verworfen, statt zweimal weitergeleitet zu werden. Dadurch kann die Wiederherstellung Nachrichten umfassend wiedergeben, ohne jede Nachricht einzeln nachzuverfolgen.
• Wiederherstellung nach Ausfallzeit. Beim Start merkt sich der Monitor die zuletzt weitergeleitete chat.db-rowid (einen persistenten Cursor pro Konto) und übergibt sie als since_rowid an imsg watch.subscribe. Dadurch gibt imsg die Zeilen wieder, die während des Gateway-Ausfalls eingegangen sind, und verfolgt anschließend neue Nachrichten live. Die Wiedergabe ist auf die neuesten 500 Zeilen und auf Nachrichten begrenzt, die höchstens ~2 Stunden alt sind; die Deduplizierung verwirft alle bereits verarbeiteten Nachrichten.
• Altersgrenze für veralteten Rückstau. Zeilen oberhalb der Startgrenze sind tatsächlich live; wenn das Sendedatum einer solchen Zeile mehr als ~15 Minuten vor ihrem Eingang liegt, handelt es sich um den durch Push ausgegebenen Rückstau, der unterdrückt wird. Wiedergegebene Zeilen (an oder unterhalb der Grenze) verwenden stattdessen das größere Wiederherstellungszeitfenster. Dadurch wird eine kürzlich verpasste Nachricht zugestellt, während weit zurückliegende Nachrichten nicht zugestellt werden.

Die Wiederherstellung funktioniert sowohl bei lokalen als auch bei entfernten cliPath-Konfigurationen, da die Wiedergabe über since_rowid über dieselbe imsg-RPC-Verbindung erfolgt. Der Unterschied liegt im Zeitfenster: Wenn das Gateway chat.db lesen kann (lokal), verankert es die rowid-Startgrenze, begrenzt den Wiedergabezeitraum und stellt verpasste Nachrichten zu, die bis zu einigen Stunden alt sind. Bei einem entfernten SSH-cliPath kann es die Datenbank nicht lesen. Daher ist die Wiedergabe nicht begrenzt und jede Zeile verwendet die Altersgrenze für Live-Nachrichten — kürzlich verpasste Nachrichten werden weiterhin wiederhergestellt und alte Rückstände weiterhin unterdrückt, jedoch mit dem engeren Live-Zeitfenster. Führen Sie das Gateway auf dem Messages-Mac aus, um das größere Wiederherstellungszeitfenster zu verwenden.

Für Betreiber sichtbares Signal

Unterdrückter Rückstau wird auf der Standardstufe protokolliert und niemals stillschweigend verworfen (das Flag recovery zeigt, welches Zeitfenster angewendet wurde):

imessage: veralteter eingehender Rückstau 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 erfordert bei neuen Konfigurationen keine Konfiguration. Bestehende Konfigurationen mit catchup.enabled: true werden weiterhin als Kompatibilitätsprofil für das Wiedergabezeitfenster der Wiederherstellung berücksichtigt. Deaktivierte Catchup-Blöcke (enabled: false oder ohne enabled: true) werden nicht mehr verwendet; 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 Konfigurationsübertragung und schrittweise Umstellung
• Kopplung — DM-Authentifizierung und Kopplungsablauf
• Gruppen — Verhalten von Gruppenchats und Beschränkung auf Erwähnungen
• Kanal-Routing — Sitzungs-Routing für Nachrichten
• Sicherheit — Zugriffsmodell und Absicherung