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

iMessage ist für OpenClaw kein bequemer Messenger-Schalter, sondern ein kleiner Betriebsfall auf dem Mac. Genau deshalb lohnt sich der Kanal trotzdem: Wenn du ihn sauber aufsetzt, landet dein Agent in einem Umfeld, das du ohnehin ständig offen hast. Wenn du ihn halb aufsetzt, bekommst du schnell das klassische Fehlerbild: Der Agent liest, aber sendet nicht. Oder DMs laufen, Gruppen bleiben stumm.

Der wichtigste Stand heute: Laut aktueller OpenClaw-Doku läuft iMessage nicht mehr über BlueBubbles, sondern über channels.imessage und imsg. Wenn bei dir noch channels.bluebubbles herumliegt, ist das keine nostalgische Altlast, sondern ein Migrationspunkt. Die eigentliche Architekturfrage lautet nicht mehr “welcher iMessage-Server?”, sondern: Auf welchem Mac läuft imsg, welche Rechte hat dieser Prozess und wie trennst du DMs, Gruppen und Anhänge sauber voneinander?

Wenn du zuerst die allgemeinen Messenger-Grundlagen nachziehen willst, passen der ältere Telegram- und WhatsApp-Teil, der Discord-Guide und der Signal-Guide als Nachbarn. iMessage ist in derselben Serie der Mac-Sonderfall.

Was du vorher brauchst

Für den lokalen Start brauchst du:

• einen Mac, auf dem Messages.app mit der gewünschten Apple-ID angemeldet ist
• Homebrew für die Installation von imsg
• eine laufende OpenClaw-Installation
• Full Disk Access für den Prozess, der später imsg oder OpenClaw startet
• Automation-Rechte für Messages.app, damit Sendevorgänge durchgehen
• eine Testnummer oder Apple-ID für Pairing und Allowlist

Wenn dein Gateway auf Linux oder Windows läuft, ändert das nichts an der Grundvoraussetzung: Für Messages.app brauchst du trotzdem einen Mac. In so einem Setup zeigt channels.imessage.cliPath meist nicht direkt auf imsg, sondern auf einen SSH-Wrapper, der imsg auf dem Mac ausführt.

Erst den Mac sauber machen

Installiere imsg auf genau dem Mac, auf dem Messages.app läuft:

brew install steipete/tap/imsg
imsg rpc --help
imsg --version

Damit prüfst du zuerst, ob die CLI und ihre RPC-Oberfläche überhaupt erreichbar sind. Laut der aktuellen OpenClaw-Doku gibt es zusätzlich einen erweiterten Modus über imsg launch, der weitere iMessage-Aktionen bereitstellt. Für einen normalen Einstieg solltest du das aber als zweite Stufe behandeln, nicht als Startreflex.

Bevor du OpenClaw konfigurierst, teste imsg direkt:

imsg chats --limit 3
imsg status --json
imsg send <handle> "OpenClaw imsg test"

Wenn imsg chats schon hier scheitert oder eine Datenbankberechtigung meldet, liegt dein Problem noch nicht bei OpenClaw. Dann fehlen macOS-Rechte. Wichtig ist dabei nicht irgendein Terminalfenster, sondern der echte Prozesskontext: Terminal, Editor, LaunchAgent, SSH-Session oder der Gateway-Prozess selbst. Genau dort muss Full Disk Access sitzen. Dasselbe gilt für den Sendetest: Wenn du OpenClaw später headless oder über SSH startest, solltest du imsg send einmal in genau diesem Kontext ausprobiert haben.

Die minimale Konfiguration

Für ein lokales Setup reicht als Einstieg ein kleiner channels.imessage-Block:

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

cliPath muss zu deinem tatsächlichen Installationspfad passen. Auf Apple-Silicon-Macs liegt Homebrew oft unter /opt/homebrew/bin, auf Intel-Systemen häufiger unter /usr/local/bin. Wenn imsg im PATH des Gateway-Prozesses sauber auflösbar ist, kann auch cliPath: "imsg" funktionieren. In der Praxis ist ein absoluter Pfad aber meist die nervenschonendere Variante.

dmPolicy: "pairing" ist der vernünftige Startwert. Unbekannte Absender lösen dann nicht sofort Agentenarbeit aus, sondern müssen erst freigegeben werden. In allowFrom stehen die Handles, die du direkt zulassen willst, also typischerweise Telefonnummern im E.164-Format oder Apple-ID-Adressen.

Danach startest du den Gateway neu oder lokal direkt mit:

openclaw gateway

Anschließend prüfst du:

openclaw channels status --probe
openclaw pairing list imessage

Wenn der Kanal hier nicht auftaucht, steckt der Fehler meist an einer von drei Stellen: enabled fehlt, cliPath zeigt ins Leere oder der Prozess kann die Messages-Datenbank nicht lesen.

Pairing zuerst, nicht Optimismus

Schicke dem iMessage-Konto eine Testnachricht. Im Standardfall sollte OpenClaw daraus einen Pairing-Code erzeugen. Freigeben kannst du ihn dann so:

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

Wenn so ein Code später nicht mehr funktioniert, ist eine frische Testnachricht meist schneller als langes Rätseln. Pairing ist bei iMessage kein Nebenschritt, sondern eine frühe Betriebsprobe. Codes laufen nach einer Stunde ab, und OpenClaw hält pro Kanal nur wenige offene Anfragen gleichzeitig vor.

Wenn OpenClaw lesen kann, aber nicht antwortet, ist das fast immer ein besseres Signal als ein diffuses Problemgefühl: Dann solltest du zuerst auf macOS-Automation und AppleEvents schauen. Gerade bei SSH-Setups kann die Berechtigung am falschen Prozess hängen. Dann sehen imsg chats und Status-Probes unauffällig aus, während imsg send zuverlässig mit einem AppleEvents-Fehler scheitert.

Remote-Mac: simpel oder gar nicht

Wenn OpenClaw nicht auf dem Messages-Mac läuft, sollte der Wrapper so langweilig wie möglich sein:

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

Die OpenClaw-Konfiguration zeigt dann auf diesen Wrapper:

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

Das Entscheidende ist nicht Eleganz, sondern eine saubere Stdio-Pipe. OpenClaw schiebt hier kleine JSON-RPC-Nachrichten über stdin und stdout. Alles, was puffert, filtert oder blockiert, kann dir einen scheinbaren iMessage-Ausfall produzieren, obwohl in Wahrheit nur der Wrapper schlampig ist.

Mach deshalb nicht nur einen Lesetest, sondern auch einen echten Sendetest über genau denselben Wrapper:

~/.openclaw/scripts/imsg-ssh send --chat-id 123 --text "OpenClaw imsg test"

Wenn dieser Test nicht funktioniert, solltest du den Kanal noch nicht freischalten. Bei iMessage reicht Lesbarkeit nicht. Die halbe Strecke ist hier wertlos.

Wenn du Anhänge remote nutzen willst, kommen noch zwei praktische Punkte dazu: remoteHost wird für SCP-Fetches gebraucht, und der Host-Key des Ziel-Macs muss bereits in ~/.ssh/known_hosts liegen. Sonst wirkt der Kanal bei Textnachrichten gesund, während Medien später an der Transportstrecke hängen bleiben.

Gruppen sind ihr eigener Ärger

Viele iMessage-Setups wirken zunächst stabil, bis eine Gruppe ins Spiel kommt. Der Grund: DMs und Gruppen laufen in OpenClaw getrennt. DMs hängen an direkten Senderregeln, Gruppen zusätzlich an Gruppenpolicy und Registrierung.

Für iMessage-Gruppen sind zwei Schalter entscheidend:

1. groupAllowFrom legt fest, welche Absender oder Ziele grundsätzlich zulässig sind.
2. groups legt fest, welche Gruppen unter groupPolicy: "allowlist" wirklich registriert sind.

Das Minimalmuster sieht so aus:

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

Genau hier sitzt einer der teuersten Denkfehler: DMs können problemlos laufen, während jede Gruppennachricht verworfen wird. Wenn du also erfolgreich pairst, aber in Gruppen nichts zurückkommt, solltest du nicht zuerst am Modell oder an der Prompting-Seite suchen. Prüfe zuerst groupPolicy, groupAllowFrom und groups.

Dazu kommt ein iMessage-spezifischer Praxispunkt: Mention-Gating fühlt sich hier oft weniger komfortabel an als in Team-Chats wie Slack oder Discord. Verlass dich deshalb nicht blind darauf, dass jede Anrede so sauber erkannt wird wie in einem nativen Bot-Ökosystem. Teste requireMention mit deinem tatsächlichen Agentennamen oder klaren Aktivierungswörtern in genau der Gruppe, die später produktiv laufen soll.

Anhänge sind ein eigener Layer

Text kann funktionieren, während Medien still scheitern. Das ist bei iMessage kein exotischer Edge Case, sondern ein normaler Betriebszustand, wenn du Anhänge nicht explizit aktivierst:

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

Bei Remote-Setups kommen laut OpenClaw-Doku zusätzlich remoteHost und remoteAttachmentRoots dazu. OpenClaw holt Dateien dann per SCP und prüft die Pfade gegen erlaubte Attachment-Roots. Das ist gut für die Sicherheit, aber auch einer der häufigsten Gründe, warum Text sauber läuft und Medien trotzdem verschwinden.

Für längere ausgehende Antworten sind außerdem textChunkLimit und chunkMode relevant. Standardmäßig wird nach Länge getrennt. Wenn du besser lesbare Antworten willst, ist ein Modus sinnvoller, der eher an Zeilenumbrüchen schneidet.

Private API: bewusst entscheiden

Der erweiterte iMessage-Modus klingt attraktiv, weil er weitere Aktionen wie Reaktionen, Bearbeiten oder Thread-Antworten freischalten kann. Gleichzeitig hängt er an deutlich sensibleren Systemvoraussetzungen. Laut Dokumentation brauchst du dafür imsg launch und ein Mac-Setup, das diesen Modus überhaupt zulässt.

Das ist keine Option, die du nebenbei einschaltest. Wenn du Systemschutz und Betriebssicherheit hoch halten willst, bleibt iMessage auch ohne diesen Modus nutzbar, nur eben mit kleinerer Aktionsfläche. Für viele private Agenten-Setups reicht genau das.

Wichtig ist aber der aktuelle Detailstand: Auf modernen macOS-Versionen reicht deaktiviertes SIP für imsg launch oft nicht mehr allein. Die OpenClaw-Doku verweist darauf, dass auf macOS 11+ in der Praxis zusätzlich die Library Validation gelockert werden muss, sonst scheitert die Injektion trotz ausgeschaltetem SIP häufig weiter. Der dokumentierte zusätzliche Schritt lautet:

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

Danach ist ein Neustart fällig. Erst dann lohnt sich der nächste Test mit:

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

Wenn der Kanal im Probe-Status gesund aussieht, einzelne Aktionen aber trotzdem auf die private API verweisen, solltest du nicht den ganzen Kanal in Frage stellen. Dann ist eher der erweiterte Modus das Problem, nicht der Basisbetrieb.

BlueBubbles sauber hinter dir lassen

Wenn du von BlueBubbles kommst, ist die Migration mehr als ein Umbenennen. Der Zielblock heißt jetzt channels.imessage. Klassische Transportfelder wie serverUrl oder password fallen weg. Verhaltensregeln wie dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups, includeAttachments, attachmentRoots, mediaMaxMb oder textChunkLimit lassen sich dagegen weitgehend übertragen.

Der wichtigste Migrationsfehler ist unscheinbar: der Gruppenblock. Wenn du groupPolicy: "allowlist" nutzt, ist groups nicht dekorativ, sondern tragend. Wer diesen Block vergisst, produziert genau die Art stillen Ausfall, die im Alltag am meisten Zeit frisst.

Teste nach der Migration deshalb getrennt:

• eine direkte Nachricht
• eine erlaubte Gruppe
• einen Anhang, falls includeAttachments aktiv ist
• genau die erweiterten iMessage-Aktionen, die du später wirklich brauchst
• einen Gateway-Neustart, damit Inbound-Recovery und Dedupe-Verhalten sichtbar werden

Erst wenn diese Liste grün ist, lohnt es sich, den alten BlueBubbles-Pfad endgültig abzuschalten.

Die kleine Testmatrix, die dir später Ärger spart

Vor produktiver Nutzung reicht keine einzelne Probe. Sinnvoll ist eine kurze Matrix:

Test	Erwartung
imsg chats --limit 3	Die Messages-Datenbank ist lesbar.
imsg send ...	Senden über den echten Prozesskontext funktioniert.
openclaw channels status --probe	Der iMessage-Kanal ist grundsätzlich erreichbar.
DM von unbekanntem Absender	Pairing wird ausgelöst oder Zugriff sauber blockiert.
DM nach Pairing	Die Antwort landet wieder in iMessage.
Gruppe ohne Freigabe	Keine Agentenantwort.
Gruppe mit Allowlist und groups-Eintrag	Antwort nur nach gewünschter Aktivierungsregel.
Attachment bei deaktiviertem includeAttachments	Kein Medieninhalt im Agententurn.
Attachment bei aktiviertem includeAttachments	Datei wird nur aus erlaubten Pfaden verarbeitet.
imsg launch + imsg status --json	Erweiterte Aktionen sind wirklich verfügbar und nicht nur angenommen.

Wenn einer dieser Tests scheitert, hilft eine einfache Denkregel: DMs, Gruppen, Anhänge und erweiterte Aktionen sind getrennte Schichten. Ein grüner DM-Test sagt nichts über Gruppen. Ein grüner Probe-Test sagt nichts über AppleEvents beim Senden. Und funktionierender Text sagt noch nichts über Medien.

Reality Check

• Grundlage: kein frisches Live-Setup, sondern die aktuelle OpenClaw-Doku zu iMessage, Gruppen, Routing, Channel-Konfiguration und BlueBubbles-Migration.
• Passt gut für: private Agenten auf dem eigenen Mac, dedizierte Bot-Macs und Gateways, die per SSH auf einen Messages-Mac zugreifen.
• Typische Bruchstellen: fehlender Full Disk Access, fehlende Automation-Rechte für Messages.app, zu komplexe SSH-Wrapper, leere Gruppenregistrierung bei Allowlist-Setups, fehlender echter Sendetest im Zielkontext und Altlasten aus BlueBubbles.
• Nicht abgesichert durch Live-Test: frisches Pairing, SCP-Transfer von Anhängen über einen Remote-Mac und fortgeschrittene private-API-Aktionen in einem realen Produktionssetup.
• Betriebsrisiko: höher als bei vielen anderen Messengern, weil iMessage an einem persönlichen macOS-System und dessen Rechtemodell hängt.

Fazit

iMessage ist für OpenClaw dann stark, wenn du den Kanal nicht als App-Integration, sondern als Mac-gebundene Betriebsstrecke behandelst. Die Oberfläche ist bequem. Die eigentliche Arbeit steckt darunter: Rechte, Prozesskontext, Pairing, Gruppen-Gates und saubere Tests pro Schicht.

Wenn du genau das sauber abnimmst, bekommst du einen brauchbaren Alltagskanal. Wenn du nur enabled: true setzt und auf Glück hoffst, landest du schnell bei einem Agenten, der liest, aber nicht sendet, in DMs funktioniert, aber Gruppen ignoriert, oder Medien kommentarlos verliert. Für teamartige Räume lohnt danach der Gegencheck mit dem Matrix-Guide, weil dort Raumlogik und sichere Replies stärker im Vordergrund stehen.