Wechsel von BlueBubbles

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Wann diese Migration sinnvoll ist

• Sie betreiben imsg bereits auf demselben Mac (oder auf einem per SSH erreichbaren Mac), auf dem Messages.app angemeldet ist.
• Sie möchten eine Komponente weniger betreiben: keinen separaten BlueBubbles-Server, keinen zu authentifizierenden REST-Endpunkt, keine Webhook-Verkabelung. Eine einzelne CLI-Binärdatei statt Server + Client-App + Hilfsprogramm.
• Sie verwenden eine unterstützte macOS- / imsg-Version, bei der die private API-Prüfung available: true meldet.

​

Was imsg macht

• Lesezugriffe erfolgen aus ~/Library/Messages/chat.db über ein schreibgeschütztes SQLite-Handle.
• Live eingehende Nachrichten kommen aus imsg watch / watch.subscribe, das Dateisystemereignissen von chat.db folgt, mit Polling als Fallback.
• Sendungen verwenden die Automatisierung von Messages.app für normale Text- und Dateisendungen.
• Erweiterte Aktionen verwenden imsg launch, um den imsg-Helper in Messages.app zu injizieren. Dadurch werden Lesebestätigungen, Tippindikatoren, umfangreiche Sendungen, Bearbeiten, Zurückrufen, Thread-Antworten, Tapbacks und Gruppenverwaltung freigeschaltet.
• Linux-Builds können eine kopierte chat.db untersuchen, aber nicht senden, die Live-Mac-Datenbank überwachen oder Messages.app ansteuern. Führen Sie für OpenClaw iMessage imsg auf dem angemeldeten Mac aus oder über einen SSH-Wrapper zu diesem Mac.

​

Bevor Sie beginnen

1. Installieren Sie imsg auf dem Mac, auf dem Messages.app läuft:
   brew install steipete/tap/imsg
   imsg --version
   imsg chats --limit 3
   
   Wenn imsg chats mit unable to open database file, leerer Ausgabe oder authorization denied fehlschlägt, erteilen Sie dem Terminal, Editor, Node-Prozess, Gateway-Dienst oder SSH-Elternprozess, der imsg startet, vollständigen Festplattenzugriff und öffnen Sie diesen Elternprozess anschließend erneut.
2. Prüfen Sie die Lese-, Watch-, Sende- und RPC-Oberflächen, bevor Sie die OpenClaw-Konfiguration ändern:
   imsg chats --limit 10 --json | jq -s
   imsg history --chat-id 42 --limit 10 --attachments --json | jq -s
   imsg watch --chat-id 42 --reactions --json
   imsg send --chat-id 42 --text "OpenClaw imsg test"
   imsg rpc --help
   
   Ersetzen Sie 42 durch eine echte Chat-ID aus imsg chats. Das Senden erfordert die Automatisierungsberechtigung für Messages.app. Wenn OpenClaw über SSH ausgeführt wird, führen Sie diese Befehle über denselben SSH-Wrapper oder Benutzerkontext aus, den OpenClaw verwenden wird.
3. Aktivieren Sie die private API-Bridge, wenn Sie erweiterte Aktionen benötigen:
   imsg launch
   imsg status --json
   
   imsg launch erfordert, dass SIP deaktiviert ist. Einfaches Senden, Verlauf und Watch funktionieren ohne imsg launch; erweiterte Aktionen nicht.
4. Prüfen Sie die Bridge über OpenClaw:
   openclaw channels status --probe
   
   Sie möchten imessage.privateApi.available: true. Wenn false gemeldet wird, beheben Sie das zuerst, siehe Capability-Erkennung.
5. Sichern Sie Ihre Konfiguration:
   cp ~/.openclaw/openclaw.json5 ~/.openclaw/openclaw.json5.bak
   

​

Konfigurationsübersetzung

​

Stolperfalle Gruppenregistrierung

1. Absender-/Chat-Ziel-Allowlist (channels.imessage.groupAllowFrom) — wird von isAllowedIMessageSender geprüft. Gleicht eingehende Nachrichten anhand von Absender-Handle, chat_guid, chat_identifier oder chat_id ab. Gleiche Form wie BlueBubbles.
2. Gruppenregistrierung (channels.imessage.groups) — wird von resolveChannelGroupPolicy aus inbound-processing.ts:199 geprüft. Mit groupPolicy: "allowlist" erfordert diese Prüfung entweder:
   • einen groups: { "*": { ... } }-Wildcard-Eintrag (setzt allowAll = true), oder
   • einen expliziten Eintrag pro chat_id unter groups.

• Ein einmaliges warn pro Account beim Start, wenn groupPolicy: "allowlist" gesetzt ist, aber channels.imessage.groups leer ist (kein "*"-Wildcard, keine Einträge pro chat_id) — wird ausgelöst, bevor Nachrichten eintreffen.
• Ein einmaliges warn pro chat_id, wenn eine bestimmte Gruppe zur Laufzeit erstmals verworfen wird, mit Nennung der chat_id und des exakten Schlüssels, der zu groups hinzugefügt werden muss, um sie zuzulassen.

{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123", "chat_guid:any;-;..."],
      groups: {
        "*": { requireMention: true },
      },
    },
  },
}

​

Schritt für Schritt

1. Fügen Sie neben dem vorhandenen BlueBubbles-Block einen iMessage-Block hinzu. Behalten Sie den alten Block nur als Kopiervorlage, bis der neue Pfad verifiziert ist:
   {
     channels: {
       bluebubbles: {
         enabled: true,
         // ... existing config ...
       },
       imessage: {
         enabled: false, // turn on after the dry run below
         cliPath: "/opt/homebrew/bin/imsg",
         dmPolicy: "pairing",
         allowFrom: ["+15555550123"], // copy from bluebubbles.allowFrom
         groupPolicy: "allowlist",
         groupAllowFrom: [], // copy from bluebubbles.groupAllowFrom
         groups: { "*": { requireMention: true } }, // copy from bluebubbles.groups — silently drops groups if missing, see "Group registry footgun" above
         actions: {
           reactions: true,
           edit: true,
           unsend: true,
           reply: true,
           sendWithEffect: true,
           sendAttachment: true,
         },
       },
     },
   }
   
2. Probelauf — starten Sie den Gateway und bestätigen Sie, dass iMessage als fehlerfrei gemeldet wird:
   openclaw gateway
   openclaw channels status
   openclaw channels status --probe   # expect imessage.privateApi.available: true
   
   Da imessage.enabled weiterhin false ist, wird noch kein eingehender iMessage-Datenverkehr geroutet — aber --probe testet die Bridge, sodass Sie Berechtigungs- oder Installationsprobleme vor der Umstellung erkennen.
3. Stellen Sie um. Entfernen Sie die BlueBubbles-Konfiguration und aktivieren Sie iMessage in einer einzigen Konfigurationsänderung:
   {
     channels: {
       imessage: { enabled: true /* ... */ },
     },
   }
   
   Starten Sie den Gateway neu. Eingehender iMessage-Datenverkehr läuft nun über das gebündelte Plugin.
4. Verifizieren Sie DMs. Senden Sie dem Agent eine Direktnachricht und bestätigen Sie, dass die Antwort ankommt.
5. Verifizieren Sie Gruppen separat. DMs und Gruppen verwenden unterschiedliche Codepfade — ein erfolgreicher DM-Test beweist nicht, dass Gruppen geroutet werden. Senden Sie dem Agent eine Nachricht in einem gekoppelten Gruppenchat und bestätigen Sie, dass die Antwort ankommt. Wenn die Gruppe stumm bleibt (keine Agent-Antwort, kein Fehler), prüfen Sie das Gateway-Log auf imessage: dropping group message from chat_id=<id> oder die Startzeile imessage: groupPolicy="allowlist" but channels.imessage.groups is empty — beide erscheinen auf dem standardmäßigen Log-Level. Wenn eine davon angezeigt wird, fehlt Ihr groups-Block oder er ist leer — siehe oben „Group registry footgun“.
6. Verifizieren Sie die Aktionsoberfläche — bitten Sie den Agent aus einer gekoppelten DM heraus, zu reagieren, zu bearbeiten, zurückzuziehen, zu antworten, ein Foto zu senden und (in einer Gruppe) die Gruppe umzubenennen bzw. einen Teilnehmer hinzuzufügen oder zu entfernen. Jede Aktion sollte nativ in Messages.app ankommen. Wenn bei einer Aktion „iMessage <action> requires the imsg private API bridge“ ausgelöst wird, führen Sie imsg launch erneut aus und aktualisieren Sie channels status --probe.
7. Entfernen Sie den BlueBubbles-Server und die Konfiguration, sobald iMessage-DMs, Gruppen und Aktionen verifiziert sind. OpenClaw verwendet channels.bluebubbles nicht.

​

Aktionsparität auf einen Blick

​

Pairing, Sitzungen und ACP-Bindings

• Pairing-Genehmigungen werden anhand des Handles übernommen. Sie müssen bekannte Absender nicht erneut genehmigen — channels.imessage.allowFrom erkennt dieselben +15555550123- / user@example.com-Strings, die BlueBubbles verwendet hat.
• Sitzungen bleiben pro Agent + Chat abgegrenzt. DMs werden unter dem Standard session.dmScope=main in der Hauptsitzung des Agent zusammengeführt; Gruppensitzungen bleiben pro chat_id isoliert. Die Sitzungsschlüssel unterscheiden sich (agent:<id>:imessage:group:<chat_id> gegenüber dem BlueBubbles-Äquivalent) — alter Gesprächsverlauf unter BlueBubbles-Sitzungsschlüsseln wird nicht in iMessage-Sitzungen übernommen.
• ACP-Bindings mit Verweis auf match.channel: "bluebubbles" müssen auf "imessage" aktualisiert werden. Die Formen von match.peer.id (chat_id:, chat_guid:, chat_identifier:, reines Handle) sind identisch.

​

Kein Rollback-Kanal

​

Verwandte Themen

• iMessage — vollständige Referenz zum iMessage-Kanal, einschließlich imsg launch-Einrichtung und Fähigkeitserkennung.
• /channels/bluebubbles — alte URL, die zu diesem Migrationsleitfaden weiterleitet.
• Pairing — DM-Authentifizierung und Pairing-Ablauf.
• Channel-Routing — wie der Gateway einen Kanal für ausgehende Antworten auswählt.