iMessage

Status: native externe CLI-Integration. Das Gateway startet imsg rpc und kommuniziert über JSON-RPC auf stdio (kein separater Daemon/Port). Erweiterte Aktionen erfordern imsg launch und eine erfolgreiche Prüfung der privaten API.

Schnelle Einrichtung

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

Anforderungen und Berechtigungen (macOS)

• Messages muss auf dem Mac angemeldet sein, auf dem imsg läuft.
• Vollständiger Festplattenzugriff ist für den Prozesskontext erforderlich, der OpenClaw/imsg ausführt (Zugriff auf die Messages-Datenbank).
• Die Automatisierungsberechtigung ist erforderlich, um Nachrichten über Messages.app zu senden.
• Für erweiterte Aktionen (Reagieren / Bearbeiten / Zurückrufen / Thread-Antwort / Effekte / Umfragen / Gruppenoperationen) muss System Integrity Protection deaktiviert sein — siehe unten Die private imsg-API aktivieren. Einfaches Senden/Empfangen von Text und Medien funktioniert ohne diese Änderung.

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

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

Die private imsg-API aktivieren

imsg wird in zwei Betriebsmodi ausgeliefert:

• Basismodus (Standard, keine SIP-Änderungen erforderlich): ausgehender Text und Medien über send, eingehendes Watch/History, Chatliste. Das erhalten Sie direkt nach einem frischen brew install steipete/tap/imsg plus den oben genannten Standardberechtigungen von macOS.
• Modus mit privater API: imsg injiziert eine Hilfs-dylib in Messages.app, um interne IMCore-Funktionen aufzurufen. Dadurch werden react, edit, unsend, reply (Thread-Antwort), sendWithEffect, poll und poll-vote (native Messages-Umfragen), renameGroup, setGroupIcon, addParticipant, removeParticipant, leaveGroup sowie Tippindikatoren und Lesebestätigungen freigeschaltet.

Um die erweiterte Aktionsoberfläche zu erreichen, die diese Kanalseite dokumentiert, benötigen Sie den Modus mit privater API. Das imsg-README beschreibt die Anforderung ausdrücklich:

Erweiterte Funktionen wie read, typing, launch, Bridge-gestütztes Rich Send, Nachrichtenmutation und Chatverwaltung sind optional. Sie erfordern, dass SIP deaktiviert ist und eine Hilfs-dylib in Messages.app injiziert wird. imsg launch verweigert die Injektion, wenn SIP aktiviert ist.

Die Hilfs-Injektionstechnik verwendet die eigene dylib von imsg, um private Messages-APIs zu erreichen. Im OpenClaw-iMessage-Pfad gibt es keinen Drittanbieter-Server und keine BlueBubbles-Runtime.

Einrichtung

1. Installieren (oder aktualisieren) Sie imsg auf dem Mac, auf dem Messages.app läuft:

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

   Die Ausgabe von imsg status --json meldet bridge_version, rpc_methods und pro Methode selectors, sodass Sie sehen können, was der aktuelle Build unterstützt, bevor Sie beginnen.

2. Deaktivieren Sie System Integrity Protection und (auf modernem macOS) Library Validation. Das Injizieren einer nicht von Apple stammenden Hilfs-dylib in die von Apple signierte Messages.app erfordert deaktiviertes SIP und gelockerte Library Validation. Der SIP-Schritt im Wiederherstellungsmodus ist macOS-versionsspezifisch:

   • macOS 10.13-10.15 (Sierra-Catalina): Deaktivieren Sie Library Validation über Terminal, starten Sie in den Wiederherstellungsmodus, führen Sie csrutil disable aus, starten Sie neu.
   • macOS 11+ (Big Sur und neuer), Intel: Wiederherstellungsmodus (oder Internet Recovery), csrutil disable, Neustart.
   • macOS 11+, Apple Silicon: Startsequenz über die Einschalttaste, um Recovery aufzurufen; halten Sie auf neueren macOS-Versionen die linke Umschalttaste gedrückt, wenn Sie auf Fortfahren klicken, dann csrutil disable. Setups mit virtuellen Maschinen folgen einem separaten Ablauf, erstellen Sie daher zuerst einen VM-Snapshot.

   Unter macOS 11 und neuer reicht csrutil disable allein normalerweise nicht aus. Apple erzwingt Library Validation weiterhin gegen Messages.app als Platform Binary, sodass eine ad-hoc-signierte Hilfsbibliothek abgelehnt wird (Library Validation failed: ... platform binary, but mapped file is not), selbst wenn SIP deaktiviert ist. Deaktivieren Sie nach dem Deaktivieren von SIP auch Library Validation und starten Sie neu:

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

   macOS 26 (Tahoe), verifiziert auf 26.5.1: Deaktiviertes SIP plus der oben genannte DisableLibraryValidation-Befehl reicht aus, um die Hilfsbibliothek über 26.0 bis 26.5.x hinweg zu injizieren. Es sind keine boot-args erforderlich. Die plist ist der entscheidende Faktor und der häufigste fehlende Schritt, wenn die Injektion auf Tahoe fehlschlägt:

   • Mit der plist: imsg launch injiziert, und imsg status meldet advanced_features: true.
   • Ohne die plist (auch bei deaktiviertem SIP): imsg launch schlägt mit Failed to launch: Timeout waiting for Messages.app to initialize fehl. AMFI lehnt den ad-hoc-Helper beim Laden ab, daher wird die Bridge nie bereit und der Start läuft in einen Timeout. Dieser Timeout ist das Symptom, auf das die meisten unter Tahoe stoßen, und die Lösung ist die obige plist, nicht etwas Drastischeres.

   Dies wurde mit einem kontrollierten Vorher/Nachher unter macOS 26.5.1 (Apple Silicon) bestätigt: Mit der plist wird die dylib in Messages.app gemappt und die Bridge startet; entfernen Sie die plist und starten Sie neu, dann erzeugt imsg launch den oben genannten Timeout-Fehler, wobei die dylib nicht gemappt ist.

   Wenn die imsg launch-Injektion oder bestimmte selectors nach einem macOS-Upgrade false zurückgeben, ist diese Prüfung meist die Ursache. Prüfen Sie Ihren SIP- und Library-Validation-Status, bevor Sie annehmen, dass der SIP-Schritt selbst fehlgeschlagen ist. Wenn diese Einstellungen korrekt sind und die Bridge weiterhin nicht injizieren kann, erfassen Sie imsg status --json sowie die Ausgabe von imsg launch und melden Sie dies dem imsg-Projekt, statt zusätzliche systemweite Sicherheitskontrollen abzuschwächen.

   Folgen Sie Apples Recovery-Mode-Ablauf für Ihren Mac, um SIP zu deaktivieren, bevor Sie imsg launch ausführen.

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

   imsg launch

   imsg launch verweigert die Injektion, wenn SIP noch aktiviert ist, sodass dies zugleich bestätigt, dass Schritt 2 wirksam war.

4. Überprüfen Sie die Bridge aus 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 Funktionen anzeigen. Die Erstellung von Umfragen erfordert selectors.pollPayloadMessage; Abstimmungen erfordern sowohl selectors.pollVoteMessage als auch die RPC-Methode poll.vote. Das OpenClaw Plugin bewirbt nur Aktionen, die vom zwischengespeicherten Probe unterstützt werden, während ein leerer Cache optimistisch bleibt und beim ersten Dispatch prüft.

Wenn openclaw channels status --probe den Kanal als works meldet, bestimmte Aktionen aber zur Dispatch-Zeit "iMessage <action> requires the imsg private API bridge" auslösen, führen Sie imsg launch erneut aus — der Helper kann herausfallen (Neustart von Messages.app, OS-Update usw.), und der zwischengespeicherte Status available: true bewirbt weiterhin Aktionen, bis der nächste Probe ihn aktualisiert.

Wenn Sie SIP nicht deaktivieren können

Wenn deaktiviertes SIP für Ihr Bedrohungsmodell nicht akzeptabel ist:

• imsg fällt auf den Basismodus zurück — nur Text + Medien + Empfang.
• Das OpenClaw Plugin bewirbt weiterhin Text-/Medienversand und eingehende Überwachung; es blendet lediglich react, edit, unsend, reply, sendWithEffect und Gruppenoperationen aus der Aktionsoberfläche aus (gemäß der funktionsbezogenen Capability-Prüfung).
• 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 Dedizierter macOS-Bot-Benutzer (separate iMessage-Identität) unten.

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

ACP-Konversationsbindungen

Legacy-iMessage-Chats können auch an ACP-Sessions gebunden werden.

Schneller Operator-Ablauf:

• Führen Sie /acp spawn codex --bind here innerhalb der DM oder des erlaubten Gruppenchats aus.
• Zukünftige Nachrichten in derselben iMessage-Konversation werden zur erzeugten ACP-Session geroutet.
• /new und /reset setzen dieselbe gebundene ACP-Session an Ort und Stelle zurück.
• /acp close schließt die ACP-Session und entfernt die Bindung.

Konfigurierte persistente Bindungen werden über Top-Level-bindings[]-Einträge mit type: "acp" und match.channel: "imessage" unterstützt.

match.peer.id kann Folgendes verwenden:

• normalisierten DM-Handle wie +15555550123 oder user@example.com
• chat_id:<id> (empfohlen für stabile Gruppenbindungen)
• 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" },    },  ],}

Siehe ACP-Agenten für gemeinsames ACP-Bindungsverhalten.

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, Chunking und Zustellziele

imsg chats --limit 20

Private-API-Aktionen

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

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

Konfigurationsschreibvorgänge

iMessage erlaubt standardmäßig kanalinitiierte Konfigurationsschreibvorgänge (für /config set|unset, wenn commands.config: true gilt).

Deaktivieren:

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

Zusammenführen von Split-Send-DMs (Befehl + URL in einer Komposition)

Wenn ein Benutzer einen Befehl und eine URL zusammen 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-Sprechblase ("https://...") mit OG-Vorschaubildern als Anhänge.

Die beiden Zeilen kommen bei den meisten Setups mit etwa 0,8-2,0 s Abstand bei OpenClaw an. Ohne Zusammenführung erhält der Agent in Durchlauf 1 nur den Befehl, antwortet (oft „send me the URL“) und sieht die URL erst in Durchlauf 2 — zu diesem Zeitpunkt ist der Befehlskontext bereits verloren. Das ist Apples Sendepipeline und nichts, was OpenClaw oder imsg einführt.

channels.imessage.coalesceSameSenderDms aktiviert für eine DM die Pufferung aufeinanderfolgender Zeilen desselben Absenders. Wenn imsg den strukturellen URL-Vorschau-Marker balloon_bundle_id: "com.apple.messages.URLBalloonProvider" in einer der Quellzeilen bereitstellt, führt OpenClaw nur diesen echten Split-Send zusammen und behält alle anderen gepufferten Zeilen als separate Durchläufe bei. Bei älteren imsg-Builds, die keinerlei Sprechblasenmetadaten ausgeben, kann OpenClaw einen Split-Send nicht von separaten Sendevorgängen unterscheiden und fällt daher auf das Zusammenführen des Buckets zurück. Das bewahrt das Verhalten vor den Metadaten, statt Dump <url>-Split-Sends in zwei Durchläufe zurückfallen zu lassen. Gruppenchats werden weiterhin pro Nachricht ausgeliefert, damit die Mehrbenutzer-Turn-Struktur erhalten bleibt.

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

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

Szenarien und was der Agent sieht

Die Spalte „Flag aktiviert“ zeigt das Verhalten auf einem imsg-Build, der balloon_bundle_id ausgibt. Bei älteren imsg-Builds, die überhaupt keine Balloon-Metadaten ausgeben, fallen die unten als „Zwei Turns“ / „N Turns“ markierten Zeilen stattdessen auf eine Legacy-Zusammenführung zurück (ein Turn): OpenClaw kann einen Split-Send strukturell nicht von separaten Sends unterscheiden und bewahrt daher die Zusammenführung vor den Metadaten. Präzise Trennung wird aktiviert, sobald der Build Balloon-Metadaten ausgibt.

Eingehende Wiederherstellung nach einem Neustart von Bridge oder Gateway

iMessage stellt Nachrichten wieder her, die verpasst wurden, während das Gateway ausgefallen war, und unterdrückt gleichzeitig die veraltete „Backlog-Bombe“, die Apple nach einer Push-Wiederherstellung ausgeben kann. Das Standardverhalten ist immer aktiv und baut auf der eingehenden Deduplizierung auf.

• Replay-Deduplizierung. Jede zugestellte eingehende Nachricht wird anhand ihrer Apple-GUID im persistenten Plugin-Zustand (imessage.inbound-dedupe) erfasst, bei der Aufnahme beansprucht und nach der Verarbeitung committet (bei einem vorübergehenden Fehler freigegeben, damit sie erneut versucht werden kann). Alles, was bereits verarbeitet wurde, wird verworfen, statt zweimal zugestellt zu werden. Dadurch kann Recovery aggressiv wiederholen, ohne Buchhaltung pro Nachricht.
• Downtime-Recovery. Beim Start merkt sich der Monitor die zuletzt zugestellte chat.db-rowid (ein persistenter Cursor pro Konto) und übergibt sie als since_rowid an imsg watch.subscribe, sodass imsg die Zeilen wiederholt, die eingegangen sind, während das Gateway ausgefallen war, und danach live weiterläuft. Replay ist auf die neuesten Zeilen und auf Nachrichten bis zu ~2 Stunden Alter begrenzt, und die Deduplizierung verwirft alles, was bereits verarbeitet wurde.
• Altersgrenze für veralteten Backlog. Zeilen oberhalb der Startgrenze sind tatsächlich live; eine Zeile, deren Sendedatum mehr als ~15 Minuten älter ist als ihre Ankunft, ist der Push-Flush-Backlog und wird unterdrückt. Wiederholte Zeilen (an oder unterhalb der Grenze) verwenden stattdessen das breitere Recovery-Fenster, sodass eine kürzlich verpasste Nachricht zugestellt wird, während uralte Historie nicht zugestellt wird.

Recovery funktioniert sowohl über lokale als auch über Remote-cliPath-Setups, weil since_rowid-Replay über dieselbe imsg-RPC-Verbindung läuft. Der Unterschied ist das Fenster: Wenn das Gateway chat.db lesen kann (lokal), verankert es die rowid-Startgrenze, begrenzt die Replay-Spanne und stellt verpasste Nachrichten zu, die bis zu ein paar Stunden alt sind. Über ein Remote-SSH-cliPath kann es die Datenbank nicht lesen, daher ist das Replay unbegrenzt und jede Zeile verwendet die Live-Altersgrenze — es stellt weiterhin kürzlich verpasste Nachrichten wieder her und unterdrückt weiterhin alten Backlog, nur mit dem engeren Live-Fenster. Führen Sie das Gateway auf dem Messages-Mac aus, um das breitere Recovery-Fenster zu erhalten.

Für Operator sichtbares Signal

Unterdrückter Backlog wird auf der Standardebene geloggt und nie stillschweigend verworfen (das Flag recovery zeigt, welches Fenster angewendet wurde):

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

Migration

channels.imessage.catchup.* ist veraltet — Downtime-Recovery ist jetzt automatisch und benötigt für neue Setups keine Konfiguration. Vorhandene Konfigurationen mit catchup.enabled: true werden weiterhin als Kompatibilitätsprofil für das Recovery-Replay-Fenster berücksichtigt. Deaktivierte Catchup-Blöcke (enabled: false oder kein enabled: true) sind eingestellt; 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
• Pairing

Verwandt

• Kanalübersicht — alle unterstützten Kanäle
• Entfernung von BlueBubbles und der imsg-iMessage-Pfad — Ankündigung und Migrationszusammenfassung
• Von BlueBubbles kommend — Konfigurationsübersetzungstabelle und schrittweise Umstellung
• Pairing — DM-Authentifizierung und Pairing-Ablauf
• Gruppen — Gruppenchat-Verhalten und Erwähnungs-Gating
• Kanal-Routing — Sitzungs-Routing für Nachrichten
• Sicherheit — Zugriffsmodell und Härtung