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 und im Runtime-Schema vorhandene Konfigurationspfad 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

Prüfe die Ausgabe des Installationsbefehls und fahre nur fort, wenn OpenClaw die Installation erfolgreich angewendet hat. Falls die Ausgabe einen Neustart verlangt oder der laufende Gateway das Plugin anschließend nicht erkennt, starte den eingerichteten Gateway-Dienst neu:

openclaw gateway restart

Das Plugin und imsg sind getrennte Komponenten: Das Plugin läuft im Gateway. imsg muss dagegen auf dem Mac ausgeführt werden, auf dem Messages.app angemeldet ist.

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 anschließend den Zugriff 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 dem Prozesskontext, in dem imsg später läuft.

Teste danach einen echten Versand an eine Adresse, die du kontrollierst:

imsg send --to "user@example.com" --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 dem ausführenden Prozess normalerweise die Automation-Berechtigung für Messages.app.

Ein erfolgreicher Test im interaktiven Terminal sagt noch nichts über einen LaunchAgent oder eine SSH-Sitzung aus. Wiederhole den Versand deshalb in demselben Benutzer- und Prozesskontext, den der Gateway später verwendet.

3. Lokalen Kanal konfigurieren

Trage die iMessage-Einstellungen in openclaw.json unter dem schema-konformen Pfad channels.imessage ein. Aufbau und JSON5-Syntax der Datei erklärt der Guide zur Gateway-Konfiguration.

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: ["user@example.com"],
    },
  },
}

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. Den tatsächlichen Pfad findest du mit:

command -v imsg

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

dmPolicy: "pairing" ist ein sicherer Ausgangspunkt. Bereits in allowFrom eingetragene Apple-ID-Adressen oder Rufnummern im E.164-Format benötigen keine zusätzliche Pairing-Freigabe.

Prüfe den Kanal nach der Konfigurationsänderung:

openclaw channels status --probe --channel imessage

Der Probe benötigt einen erreichbaren Gateway und einen aktivierten iMessage-Account. Wenn der Kanal fehlt oder die Prüfung scheitert, kontrolliere Plugin-Installation, enabled, cliPath, dbPath und Full Disk Access. Falls die Änderung noch nicht übernommen wurde, starte den Gateway-Dienst neu und wiederhole den Probe.

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. OpenClaw sollte sie empfangen, einen Agententurn auslösen und die Antwort in derselben iMessage-Konversation zustellen.

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 channels.imessage.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 bot@mac-mini.example imsg "$@"

Mache die Datei ausführbar. 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.

Die Konfiguration bleibt unter channels.imessage und kann so aussehen:

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "/Users/gateway/.openclaw/scripts/imsg-ssh",
      remoteHost: "bot@mac-mini.example",
      dbPath: "/Users/bot/Library/Messages/chat.db",
    },
  },
}

cliPath ist ein absoluter Pfad auf dem Gateway-Host. dbPath bezeichnet die Datenbank auf dem Messages-Mac. remoteHost enthält den Hostnamen oder user@host.

Der SSH-Zugang muss ohne interaktive Passwortabfrage funktionieren. Hinterlege den Hostschlüssel vorher im known_hosts des Gateway-Benutzers und prüfe dessen Fingerprint über einen vertrauenswürdigen Weg.

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 oft zuverlässiger betreiben.

Remote-Anhänge benötigen zusätzliche Pfad- und Transferregeln. Konfiguriere sie erst nach der aktuellen OpenClaw-Seite zum Remote-Mac und teste Text sowie Anhänge getrennt; ein funktionierender SSH-Wrapper bestätigt noch keinen Attachment-Transfer.

6. Gruppen mit ausdrücklichen Zugriffsgates absichern

DMs und Gruppen werden getrennt geprüft. Verlasse dich bei Gruppen nicht auf implizite Standard- oder Fallbackwerte. Setze sowohl das Sender-Gate als auch die zugelassenen Gruppen ausdrücklich unter channels.imessage.

Dieses Muster lässt den angegebenen Absender in konfigurierten Gruppen zu und verlangt zusätzlich eine erkannte Anrede:

{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["user@example.com"],
      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: ["user@example.com"],
      groups: {
        "8421": { requireMention: true },
      },
    },
  },
}

iMessage liefert OpenClaw keine nativen Mention-Metadaten. requireMention benötigt deshalb passende Textmuster. Der 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 in derselben Gruppe nacheinander:

1. einen nicht erlaubten Absender,
2. einen erlaubten Absender ohne Anrede,
3. einen erlaubten Absender mit passendem Muster.

Nur der dritte Test sollte einen normalen Agententurn auslösen.

7. Anhänge und lange Antworten testen

Wenn Inhalte eingehender Anhänge an Agententurns übergeben werden sollen, aktiviere sie unter channels.imessage mit begrenzten erlaubten Pfaden:

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

Teste ein Bild oder Dokument aus dem Messages-Attachment-Verzeichnis. Prüfe außerdem den Negativfall mit einem Pfad außerhalb der erlaubten Roots; er darf nicht als Attachment in den Agententurn gelangen.

Bei einem Remote-Mac muss zusätzlich der entfernte Abrufpfad korrekt eingerichtet sein. Verwende dafür die Felder und Einschränkungen der aktuellen OpenClaw-Setup-Dokumentation und prüfe den Transfer separat.

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.

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, gelockerte Library Validation und eine erfolgreiche Helper-Injektion.

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 Recovery- und Library-Validation-Schritte nicht anhand eines alten Einzelbefehls aus. Prüfe unmittelbar vor der Änderung die aktuelle OpenClaw-Dokumentation zur Private API und Apples Hinweise für die installierte macOS-Version. Dokumentiere die geänderten Werte und den Weg zurück zur vorherigen SIP-Konfiguration.

Prüfe zunächst, 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 testest du:

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

Der Probe sollte den iMessage-Kanal als funktionsfähig und privateApi.available als true 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 Probe.

9. Von BlueBubbles migrieren

Ersetze channels.bluebubbles durch den schema-konformen Pfad 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 attachmentRoots
• mediaMaxMb und textChunkLimit
• unterstützte actions

Konkrete Gruppen werden unter groups mit der numerischen chat_id aus imsg chats eingetragen. Prüfe Zugriffsgates und Gruppen-IDs nach der Migration neu, statt die Wirkung alter Einstellungen vorauszusetzen.

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 spielt nach einem Bridge- oder Gateway-Neustart verpasste iMessage-Eingänge automatisch ein und unterdrückt doppelte Zustellungen. Der Neustarttest zeigt, ob dieser Wiederherstellungspfad 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 unter channels.imessage konfigurierte Kanal meldet einen funktionierenden Probe.
DM von unbekanntem Absender	Pairing wird ausgelöst; die auslösende Nachricht wird vor der Freigabe 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 ohne erforderliche Anrede	Kein normaler Agententurn wird ausgelöst.
Erlaubter Absender mit passendem Mention-Muster	Die Nachricht 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 Remote-Transferpfad.

Reality Check

• Grundlage: aktuelle OpenClaw-Dokumentation zu iMessage, Pairing und der BlueBubbles-Migration; kein vollständiger Produktionsaufbau eigens 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 transparenter SSH-Wrapper, falsche Gruppenfreigaben, falsche Chat-IDs und nicht erlaubte Attachment-Pfade.
• Nicht durch diesen Artikel live abgesichert: Pairing, Remote-Transfers realer Anhänge 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. Die iMessage-Konfiguration gehört in openclaw.json unter channels.imessage. Prüfe Datenbankzugriff, Versand, Pairing, Gruppen und Anhänge einzeln.

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 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.