iMessage mit OpenClaw verbinden: Apple Messages auf dem Mac sauber einrichten

iMessage ist für OpenClaw kein gewöhnlicher Messenger-Schalter. Der Kanal hängt an einem Mac, auf dem Messages.app mit der gewünschten Apple-ID angemeldet ist. Dort müssen auch imsg, die macOS-Berechtigungen und der Benutzerkontext des OpenClaw Gateway oder SSH-Wrappers zusammenpassen.

BlueBubbles wird von aktuellen OpenClaw-Versionen nicht mehr unterstützt. Der gültige Kanal heißt channels.imessage. Das offizielle Plugin startet imsg rpc und kommuniziert über JSON-RPC auf stdin und stdout mit der CLI. Ein verbliebener channels.bluebubbles-Block wird nicht mehr ausgewertet.

Wenn du die allgemeinen Messenger-Grundlagen nachziehen willst, passen der Telegram- und WhatsApp-Teil, der Discord-Guide und der Signal-Guide als Nachbarn. iMessage ist der Mac-Sonderfall dieser Reihe.

Was du vorher brauchst

Für ein lokales Setup brauchst du:

• einen Mac mit einer in Messages.app angemeldeten Apple-ID
• Homebrew und eine aktuelle imsg-Installation
• eine laufende OpenClaw-Installation
• das offizielle Plugin @openclaw/imessage
• Full Disk Access für den Prozesskontext, der imsg ausführt
• Automation-Rechte für Messages.app, wenn Nachrichten gesendet werden sollen
• einen separaten iMessage-Absender für Pairing- und Antworttests

Läuft der Gateway unter Linux, Windows oder auf einem anderen Mac, bleibt ein angemeldeter Messages-Mac erforderlich. channels.imessage.cliPath verweist dann auf einen absoluten, Gateway-lokalen Pfad zu einem transparenten SSH-Wrapper.

1. Offizielles iMessage-Plugin installieren

Installiere das Plugin auf dem Gateway-Host:

openclaw plugins install @openclaw/imessage

Starte den Gateway danach mit dem Verfahren neu, das du für deine OpenClaw-Installation verwendest. Bei einer als Dienst eingerichteten Installation ist das typischerweise:

openclaw gateway restart

Das Plugin und das externe imsg-Programm sind zwei getrennte Komponenten: Das Plugin läuft im Gateway, während imsg auf dem Mac mit der angemeldeten Messages.app ausgeführt werden muss.

2. imsg installieren und direkt prüfen

Installiere oder aktualisiere imsg auf dem Messages-Mac:

brew install steipete/tap/imsg
brew update
brew upgrade imsg
imsg --version
imsg rpc --help
imsg send --help

Prüfe den Lesezugriff auf Messages:

imsg chats --limit 3

Der Befehl sollte vorhandene Chats ausgeben. Scheitert er am Zugriff auf ~/Library/Messages/chat.db, erteile Full Disk Access genau dem Prozesskontext, in dem imsg später läuft.

Teste danach einen echten Versand. Verwende eine Apple-ID-Adresse, die du für den Test kontrollierst:

imsg send --to "[email protected]" --text "OpenClaw imsg test"

Für einen bekannten Chat kannst du dessen numerische ID verwenden:

imsg send --chat-id 123 --text "OpenClaw imsg test"

Wenn Lesen funktioniert, Senden aber mit einem AppleEvents-Fehler wie -1743 scheitert, fehlt normalerweise die Automation-Berechtigung für Messages.app.

Der Prozesskontext ist entscheidend. Ein erfolgreicher Test im interaktiven Terminal belegt nicht, dass derselbe Aufruf über einen LaunchAgent oder eine SSH-Sitzung funktioniert. Wiederhole den Versand deshalb in dem Benutzer- und Prozesskontext, den der Gateway später verwendet.

3. Lokalen Kanal konfigurieren

Ein minimales lokales Setup sieht so aus:

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "/opt/homebrew/bin/imsg",
      dbPath: "/Users/user/Library/Messages/chat.db",
      dmPolicy: "pairing",
      allowFrom: ["[email protected]"],
    },
  },
}

Passe cliPath und dbPath an den Benutzer des Messages-Macs an. Homebrew liegt auf Apple-Silicon-Macs häufig unter /opt/homebrew, auf Intel-Macs oft unter /usr/local. Ermittle den tatsächlichen Pfad bei Bedarf mit:

command -v imsg

Ein absoluter Pfad ist leichter zu diagnostizieren als ein vom PATH des Gateway-Prozesses abhängiger Aufruf.

dmPolicy: "pairing" ist ein sicherer Ausgangspunkt. Einträge in allowFrom dürfen ohne Pairing schreiben. Du kannst dort Apple-ID-Adressen oder Rufnummern im E.164-Format eintragen.

Starte den Gateway nach der Konfigurationsänderung neu und prüfe nur iMessage:

openclaw gateway restart
openclaw channels status --probe --channel imessage

Der Probe-Befehl benötigt einen erreichbaren Gateway und einen aktivierten iMessage-Account. Wenn der Kanal fehlt oder der Probe scheitert, kontrolliere Plugin-Installation, enabled, cliPath, dbPath und Full Disk Access.

4. Pairing vollständig testen

Sende dem iMessage-Konto eine Nachricht von einem Absender, der nicht in allowFrom steht. Bei dmPolicy: "pairing" sollte eine Pairing-Anfrage entstehen.

Liste die offenen Anfragen auf:

openclaw pairing list imessage

Gib anschließend den angezeigten Code frei:

openclaw pairing approve imessage <CODE>

Pairing-Codes laufen nach einer Stunde ab. Die auslösende Nachricht des unbekannten Absenders wird vor der Freigabe nicht als normaler Agententurn verarbeitet.

Sende nach der Freigabe eine neue Nachricht und prüfe den vollständigen Weg: OpenClaw empfängt sie, löst einen Agententurn aus und stellt die Antwort in derselben iMessage-Konversation zu.

Kann OpenClaw Nachrichten lesen, aber nicht antworten, wiederhole den direkten imsg send-Test im Gateway-Kontext. Ein erfolgreicher Channel-Probe ersetzt diesen Versandtest nicht.

5. Entfernten Messages-Mac per SSH anbinden

Läuft der Gateway nicht auf dem Messages-Mac, kann cliPath auf einen transparenten SSH-Wrapper zeigen. Lege ihn auf dem Gateway-Host beispielsweise unter /Users/gateway/.openclaw/scripts/imsg-ssh ab:

#!/usr/bin/env bash
exec ssh -T [email protected] imsg "$@"

Der Wrapper muss während imsg rpc eine unveränderte Stdio-Verbindung bereitstellen. Er darf JSON-RPC-Zeilen nicht puffern, filtern oder eigene Diagnosemeldungen auf stdout schreiben. Zusätzliche Logs gehören auf stderr.

Eine Remote-Konfiguration mit Anhängen kann so aussehen:

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "/Users/gateway/.openclaw/scripts/imsg-ssh",
      remoteHost: "[email protected]",
      dbPath: "/Users/bot/Library/Messages/chat.db",
      includeAttachments: true,
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
    },
  },
}

cliPath ist ein absoluter Pfad auf dem Gateway-Host. dbPath bezeichnet dagegen die Datenbank auf dem Messages-Mac. remoteHost darf nur einen Hostnamen oder user@host enthalten.

attachmentRoots begrenzt die lokal akzeptierten Attachment-Pfade. remoteAttachmentRoots begrenzt die Pfade, die vom Remote-Mac geholt werden dürfen. OpenClaw prüft den SSH-Hostschlüssel; der Messages-Mac muss daher bereits im known_hosts des Gateway-Benutzers eingetragen sein.

Teste Lesen und Senden über genau denselben Wrapper:

/Users/gateway/.openclaw/scripts/imsg-ssh chats --limit 3
/Users/gateway/.openclaw/scripts/imsg-ssh send --chat-id 123 --text "OpenClaw imsg test"

Funktioniert das Lesen, während Senden über SSH mit AppleEvents -1743 scheitert, fehlen dem serverseitigen SSH-Prozess wahrscheinlich die nötigen Automation-Rechte. Ein Gateway oder eine imsg-Bridge in der angemeldeten lokalen Benutzersitzung des Macs lässt sich dann meist leichter betreiben.

6. Gruppen mit beiden Zugriffsgates absichern

DMs und Gruppen werden getrennt geprüft. Unter groupPolicy: "allowlist" muss eine Gruppennachricht das Sender-Gate passieren. Dafür verwendet OpenClaw groupAllowFrom. Ist es nicht gesetzt, fällt der Kanal auf allowFrom zurück. Ein ausdrücklich leeres groupAllowFrom: [] lässt keine Gruppensender zu.

Die optionale groups-Map bildet ein zweites Gate. Fehlt sie oder ist sie leer, entscheidet das Sender-Gate. Sobald die Map Einträge enthält, muss die numerische chat_id der Gruppe ausdrücklich vorhanden oder durch "*" abgedeckt sein.

Dieses Muster lässt erlaubte Absender in allen Gruppen zu, verlangt aber eine erkannte Anrede:

{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["[email protected]"],
      groups: {
        "*": { requireMention: true },
      },
    },
  },
}

Wenn nur eine bestimmte Gruppe zugelassen werden soll, ermittle ihre numerische ID mit imsg chats und verwende sie als Schlüssel:

{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["[email protected]"],
      groups: {
        "8421": { requireMention: true },
      },
    },
  },
}

iMessage liefert OpenClaw keine nativen Mention-Metadaten. requireMention benötigt deshalb passende Textmuster. Der durch die installierte Runtime bestätigte globale Pfad lautet messages.groupChat.mentionPatterns:

{
  messages: {
    groupChat: {
      mentionPatterns: ["\\bnexus\\b", "@nexus"],
    },
  },
}

Verwende präzise Muster für den tatsächlichen Agentennamen. Teste danach in derselben Gruppe eine Nachricht ohne Anrede und eine mit passendem Muster. Nur die zweite sollte einen normalen Agententurn auslösen.

7. Anhänge und lange Antworten testen

Eingehende Anhänge sind standardmäßig nicht aktiviert. Schalte sie nur mit begrenzten erlaubten Pfaden frei:

{
  channels: {
    imessage: {
      includeAttachments: true,
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      mediaMaxMb: 16,
    },
  },
}

Bei einem Remote-Mac kommen remoteHost und remoteAttachmentRoots hinzu. Eine Datei wird nur verarbeitet, wenn ihr Pfad gegen die konfigurierten Roots validiert werden kann.

Teste mindestens ein Bild oder Dokument. Prüfe außerdem den Negativfall mit einem Pfad außerhalb der erlaubten Roots. Er darf nicht als Attachment in den Agententurn gelangen.

Lange ausgehende Texte steuerst du über textChunkLimit. Der Trennmodus liegt unter channels.imessage.streaming.chunkMode:

{
  channels: {
    imessage: {
      textChunkLimit: 4000,
      streaming: {
        chunkMode: "newline",
      },
    },
  },
}

Zulässige Modi sind length und newline; length ist der Standard.

8. Private API nur nach bewusster Sicherheitsentscheidung

Der Basisbetrieb benötigt kein deaktiviertes SIP. Textversand, Empfang, Verlauf und Medien funktionieren mit den üblichen macOS-Berechtigungen.

Erweiterte Aktionen wie Tapbacks, Bearbeiten, Zurückrufen, Thread-Replies, Effekte, native Umfragen und Gruppenverwaltung benötigen den Private-API-Modus über imsg launch. Dafür verlangt die aktuelle OpenClaw-Dokumentation deaktiviertes SIP und auf modernen macOS-Versionen zusätzliche Änderungen an der Library Validation.

Das schwächt systemweite macOS-Schutzmechanismen. Auf Apple-Silicon-Macs verhindert deaktiviertes SIP außerdem die Installation und Ausführung von iOS-Apps auf dem Mac. Verwende diesen Modus vorzugsweise auf einem dedizierten Messages-Mac und nur mit einem dokumentierten Rückbauplan.

Führe die Recovery- und Library-Validation-Schritte nicht anhand eines einzelnen kopierten Terminalbefehls aus. Prüfe unmittelbar vor der Änderung die aktuelle OpenClaw-iMessage-Dokumentation und Apples Hinweise für die tatsächlich installierte macOS-Version. Halte fest, welche Werte geändert wurden und wie du sie beim erneuten Aktivieren von SIP zurücksetzt.

Prüfe außerdem vor dem Start, ob deine installierte imsg-Version die benötigten Befehle kennt:

imsg --version
imsg launch --help
imsg status --help

Nach vollständig eingerichtetem Private-API-Modus kannst du testen:

imsg launch
imsg status --json
openclaw channels status --probe --channel imessage --json

Der iMessage-Probe sollte funktionieren und die private API als verfügbar melden. Fällt eine erweiterte Aktion nach einem Neustart von Messages.app oder einem macOS-Update aus, prüfe erneut imsg status --json, starte die Bridge bei Bedarf mit imsg launch und wiederhole den Channel-Probe.

9. Von BlueBubbles migrieren

Ersetze channels.bluebubbles durch channels.imessage. Transportfelder wie serverUrl, password und Webhook-Konfiguration entfallen, weil der unterstützte iMessage-Pfad keinen BlueBubbles-Server verwendet.

Übertragen werden können unter anderem:

• dmPolicy und allowFrom
• groupPolicy und groupAllowFrom
• groups
• includeAttachments und die Attachment-Roots
• mediaMaxMb und textChunkLimit
• unterstützte actions

Konkrete Gruppen müssen unter groups mit der numerischen chat_id aus imsg chats eingetragen werden. Nur ein vorhandener Wildcard-Eintrag "*" lässt sich ohne neue Gruppen-ID übernehmen.

Pairing-Freigaben werden nicht von BlueBubbles auf iMessage übertragen. Bereits gepaarte Absender müssen erneut pairen oder in allowFrom eingetragen werden.

Teste vor dem Entfernen des alten BlueBubbles-Systems eine direkte Nachricht und eine erlaubte Gruppe. Sind Anhänge aktiviert, sende auch eine Datei. Prüfe zusätzlich jede benötigte Private-API-Aktion sowie einen Gateway-Neustart mit einer während der Unterbrechung eingegangenen Nachricht.

OpenClaw stellt nach einem Bridge- oder Gateway-Neustart verpasste iMessage-Eingänge automatisch wieder her und dedupliziert sie. Der Neustarttest zeigt, ob dieser Pfad in deinem Aufbau funktioniert.

Testmatrix

Test	Erwartung
imsg chats --limit 3	Die Messages-Datenbank ist im späteren Prozesskontext lesbar.
imsg send --to ... --text ...	Der Versand funktioniert im späteren Prozesskontext.
openclaw channels status --probe --channel imessage	Der konfigurierte iMessage-Kanal meldet einen funktionierenden Probe.
DM von unbekanntem Absender	Pairing wird ausgelöst; die Nachricht vor der Freigabe wird nicht verarbeitet.
DM nach Pairing	Die Antwort landet in derselben iMessage-Konversation.
Gruppe mit nicht erlaubtem Absender	Kein normaler Agententurn wird ausgelöst.
Erlaubter Absender in zugelassener Gruppe	Die Nachricht passiert Sender- und gegebenenfalls Gruppen-Gate.
requireMention mit passendem Muster	Nur die Nachricht mit erkannter Anrede löst einen normalen Agententurn aus.
Anhang bei deaktiviertem includeAttachments	Der Medieninhalt erreicht den Agententurn nicht.
Anhang bei aktiviertem includeAttachments	Nur Dateien aus erlaubten Pfaden werden verarbeitet.
imsg launch plus JSON-Probe	Die private API wird nach der Sicherheitskonfiguration als verfügbar gemeldet.

Ein grüner DM-Test belegt nicht, dass Gruppen funktionieren. Ein erfolgreicher Probe ersetzt nicht den Test der macOS-Automation für ausgehende Nachrichten. Funktionierender Textversand bestätigt weder den Attachment- noch den SCP-Pfad.

Reality Check

• Grundlage: aktuelle OpenClaw-Dokumentation zu iMessage, Pairing und der BlueBubbles-Migration; kein frischer vollständiger Produktionsaufbau für diesen Artikel.
• Passt gut für: private OpenClaw-Installationen auf einem Mac, dedizierte Messages-Macs und Gateways mit transparenter SSH-Verbindung.
• Typische Bruchstellen: fehlender Full Disk Access, fehlende Automation-Rechte, veraltetes imsg, ein nicht transparent arbeitender SSH-Wrapper, leere Gruppen-Allowlisten, falsche Chat-IDs und nicht freigegebene Attachment-Pfade.
• Nicht durch diesen Artikel live abgesichert: Pairing, Remote-SCP mit realen Anhängen und Private-API-Aktionen auf einem produktiven Mac.
• Betriebsrisiko: höher als bei üblichen Bot-Messengern, besonders wenn für erweiterte Aktionen macOS-Schutzmechanismen deaktiviert werden.

Wichtigste Punkte

Installiere das offizielle Plugin auf dem Gateway-Host und imsg im Benutzerkontext des Messages-Macs. Prüfe Datenbankzugriff, Versand, Pairing, Gruppen und Anhänge einzeln. Ein erfolgreicher Test ersetzt dabei keinen der anderen Schritte.

Für einen entfernten Mac benötigt channels.imessage.cliPath einen absoluten Pfad zu einem transparenten SSH-Wrapper auf dem Gateway-Host. Das Mention-Gate verwendet den bestätigten globalen Pfad messages.groupChat.mentionPatterns.

Der Basisbetrieb kommt ohne deaktiviertes SIP aus. Die Private API erweitert die verfügbaren Aktionen, schwächt aber macOS-Schutzmechanismen und benötigt einen dokumentierten Rückbauplan. Für teamartige Räume bietet der Matrix-Guide einen passenden Gegencheck.