OpenClaw

OpenClaw BlueBubbles Kanal

Messaging
Mittel

Verbinden Sie OpenClaw über die BlueBubbles REST API mit iMessage. Diese Integration verwandelt Ihren Mac in ein iMessage-Gateway — installieren Sie die BlueBubbles Server-App, aktivieren Sie die Web-API, und Ihr KI-Assistent kann iMessage-Nachrichten, Tapback-Reaktionen und Medienanhänge senden und empfangen. BlueBubbles ist der empfohlene iMessage-Kanal und ersetzt den veralteten imsg CLI-Ansatz.

Kurzinfo
SchwierigkeitsgradMittel
KategorieMessaging
Unterstützte Funktionen4 / 6

BlueBubbles Unterstützte Funktionen

Textnachrichten

Unterstützt

Medien & Dateien

Unterstützt

Reaktionen

Unterstützt

Threads

Nicht unterstützt

Sprachnachrichten

Nicht unterstützt

Gruppenchat

Unterstützt

BlueBubbles Voraussetzungen

  • Ein Mac mit macOS High Sierra (10.13) oder höher (Ventura 13+ empfohlen für den vollen Funktionsumfang; Tahoe 26 wird mit Einschränkungen unterstützt)
  • BlueBubbles Server-App installiert von bluebubbles.app
  • Web-API aktiviert mit gesetztem Passwort in der BlueBubbles-Konfiguration
  • OpenClaw Gateway läuft und ist konfiguriert

BlueBubbles Schnelleinrichtung

1

BlueBubbles Server auf Ihrem Mac installieren

Laden Sie die BlueBubbles Server-App von bluebubbles.app/install herunter und installieren Sie sie. Starten Sie die App, melden Sie sich mit Ihrer Apple ID an und schließen Sie die Ersteinrichtung ab. Stellen Sie sicher, dass iMessage auf dem Mac funktioniert.

2

Web-API aktivieren

Aktivieren Sie in den BlueBubbles Server-Einstellungen die Web/REST-API und legen Sie ein sicheres Passwort fest. Notieren Sie die Server-URL (z.B. http://localhost:1234) — Sie benötigen diese für die OpenClaw-Konfiguration.

3

BlueBubbles-Kanalkonfiguration hinzufügen

Führen Sie 'openclaw onboard' aus und wählen Sie BlueBubbles, oder fügen Sie die Kanalkonfiguration manuell zu ~/.openclaw/openclaw.json mit Ihrer serverUrl und Ihrem password hinzu. Konfigurieren Sie bei Bedarf den webhookPath.

4

Webhook konfigurieren und testen

Richten Sie die BlueBubbles-Webhooks auf Ihr Gateway: https://your-gateway-host:3000/bluebubbles-webhook?password=<password>. Starten Sie das Gateway und senden Sie eine Test-iMessage, um die Verbindung zu überprüfen. Bei Verwendung der Pairing-Richtlinie genehmigen Sie den Absender über 'openclaw pairing approve bluebubbles <code>'.

BlueBubbles Konfigurationsbeispiel

config.json
{
  "channels": {
    "bluebubbles": {
      "enabled": true,
      "serverUrl": "http://localhost:1234",
      "password": "YOUR_BLUEBUBBLES_PASSWORD",
      "webhookPath": "/bluebubbles-webhook",
      "dmPolicy": "pairing"
    }
  }
}

BlueBubbles Detaillierte Dokumentation

Architekturübersicht

OpenClaw verbindet sich über die BlueBubbles Server-App auf einem Mac mit iMessage. BlueBubbles stellt eine REST-API bereit, die das Gateway zum Senden von Nachrichten, Reaktionen und zur Chat-Verwaltung nutzt. Eingehende Nachrichten werden per Webhook zugestellt — BlueBubbles pusht neue Nachrichtenereignisse an den Webhook-Endpunkt des Gateways. Der Architekturfluss: iMessage kommt auf dem Mac an → BlueBubbles Server → Webhook-Push an Gateway → OpenClaw verarbeitet mit KI → REST-API-Rückruf an BlueBubbles → iMessage zugestellt. Dieser Ansatz erfordert einen permanent online Mac (physisch oder VM), da iMessage ein Apple-exklusiver Dienst ist. Der Mac dient als Brücke zwischen Apples Messaging-Ökosystem und Ihrem OpenClaw-Assistenten.
Ein dedizierter Mac Mini oder eine macOS-VM ist ideal, um BlueBubbles als permanentes iMessage-Gateway zu betreiben.
BlueBubbles unterstützt die Private API für erweiterte Funktionen wie Tapback-Reaktionen, Nachrichtenbearbeitung und Widerruf — stellen Sie sicher, dass sie in den BlueBubbles-Einstellungen aktiviert ist.

BlueBubbles Server-Einrichtung

Die Einrichtung von BlueBubbles erfordert die Installation der Server-App auf Ihrem Mac: 1. Laden Sie BlueBubbles von bluebubbles.app/install herunter und starten Sie die App. 2. Melden Sie sich mit Ihrer Apple ID an und überprüfen Sie, dass iMessage auf dem Mac funktioniert. 3. Aktivieren Sie die Web/REST-API in den BlueBubbles-Einstellungen. 4. Legen Sie ein sicheres API-Passwort fest — dieses authentifiziert alle API-Anfragen und Webhook-Zustellungen. 5. Notieren Sie die in der App angezeigte Server-URL (Standard: http://localhost:1234). 6. Optional: Aktivieren Sie die Private API für erweiterte Funktionen (Reaktionen, Bearbeitung, Widerruf). Der Server muss weiterlaufen, damit die iMessage-Brücke funktioniert. Konfigurieren Sie BlueBubbles für den Autostart für Zuverlässigkeit.
webhook URL
# Webhook-URL-Format für Ihr Gateway
https://your-gateway-host:3000/bluebubbles-webhook?password=YOUR_PASSWORD
Bewahren Sie Ihr BlueBubbles API-Passwort sicher auf. Wenn der Server im Netzwerk erreichbar ist, aktivieren Sie HTTPS auf BlueBubbles und verwenden Sie Firewall-Regeln zur Zugriffsbeschränkung. Reverse-Proxys auf dem gleichen Host umgehen die Passwort-Authentifizierung — fügen Sie Proxy-Level-Authentifizierung hinzu und konfigurieren Sie gateway.trustedProxies.

DM-Richtlinien

DM (Direktnachrichten)-Richtlinien steuern, wer über iMessage mit Ihrem KI-Assistenten interagieren kann. OpenClaw unterstützt vier Richtlinien: • pairing (Standard) — Unbekannte Absender erhalten einen zeitbegrenzten Pairing-Code (läuft nach 1 Stunde ab). Genehmigen oder ablehnen über 'openclaw pairing approve bluebubbles <CODE>'. Nach Genehmigung können sie frei chatten. • allowlist — Nur in allowFrom aufgelistete Telefonnummern und E-Mail-Adressen können Nachrichten senden. Alle anderen werden still ignoriert. E.164-Format für Telefonnummern unterstützt. • open — Jeder, der eine Nachricht sendet, erhält eine Antwort. Vorsichtig verwenden. • disabled — DM-Verarbeitung ist vollständig deaktiviert.
openclaw.json
{
  "channels": {
    "bluebubbles": {
      "dmPolicy": "allowlist",
      "allowFrom": ["+15551234567", "user@example.com"]
    }
  }
}
Das allowFrom-Feld akzeptiert sowohl Telefonnummern (E.164-Format, z.B. +15551234567) als auch E-Mail-Adressen für iMessage-Routing.

Gruppenchat-Verwaltung

OpenClaw unterstützt iMessage-Gruppenchats über BlueBubbles mit flexibler Zugriffskontrolle: • groupPolicy steuert, wer den Bot in Gruppenchats auslösen kann: - open — Jedes Gruppenmitglied kann interagieren - allowlist — Nur Adressen aus groupAllowFrom können auslösen - disabled (Standard) — Gruppennachrichten werden ignoriert • Erwähnungserkennung — Wenn requireMention true ist (Standard für Gruppen), antwortet der Bot nur bei Erwähnung. Erwähnungsmuster werden in agents.list[].groupChat.mentionPatterns konfiguriert. • Pro-Gruppe-Konfiguration — Verwenden Sie das groups-Objekt, um verschiedene requireMention-Regeln für bestimmte Gruppenchats festzulegen.
openclaw.json
{
  "channels": {
    "bluebubbles": {
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["+15551234567"],
      "groups": {
        "iMessage;+;chat123456": {
          "requireMention": false
        }
      }
    }
  }
}

iMessage-Aktionen und -Effekte

BlueBubbles bietet über die Private API umfangreiche native iMessage-Aktionen. Jede Aktion kann einzeln umgeschaltet werden: • reactions — Tapback-Reaktionen senden und empfangen (Herz, Daumen hoch, Daumen runter, Lachen, Hervorhebung, Fragezeichen) • edit — Gesendete Nachrichten bearbeiten (erfordert macOS 13+; derzeit fehlerhaft auf macOS Tahoe) • unsend — Gesendete Nachrichten widerrufen (macOS 13+) • reply — Nachrichten-Threading per GUID • sendWithEffect — Nachrichten mit Blaseneffekten senden (Slam, Laut, Sanft, Unsichtbare Tinte, etc.) • sendAttachment — Mediendateien und Sprachmemos senden (MP3/CAF-Format für Sprache; BlueBubbles konvertiert MP3→CAF automatisch) Gruppenverwaltungs-Aktionen: • renameGroup — Gruppenchats umbenennen • setGroupIcon — Gruppenchat-Foto festlegen (instabil auf macOS Tahoe) • addParticipant / removeParticipant / leaveGroup — Gruppenmitglieder verwalten
openclaw.json
{
  "channels": {
    "bluebubbles": {
      "actions": {
        "reactions": true,
        "edit": true,
        "unsend": true,
        "reply": true,
        "sendWithEffect": true,
        "sendAttachment": true
      }
    }
  }
}
Auf macOS Tahoe (26) ist die edit-Aktion aufgrund von Private-API-Änderungen derzeit fehlerhaft, und setGroupIcon ist unzuverlässig (API meldet Erfolg, aber Icon synchronisiert nicht). Wenn Sie Tahoe verwenden, deaktivieren Sie diese Aktionen manuell.

Nachrichtenzustellung und Aufteilung

OpenClaw bietet konfigurierbare Aufteilungszustellung für lange KI-Antworten: • textChunkLimit — Maximale Zeichen pro Nachrichtenblock (Standard: 4000). iMessage hat kein striktes Limit, aber zu lange Nachrichten werden möglicherweise nicht auf allen Geräten korrekt angezeigt. • chunkMode — Steuert die Textaufteilungsmethode: - length (Standard) — Harte Aufteilung bei textChunkLimit Zeichen - newline — Aufteilung an Absatzgrenzen für natürlicheres Lesen • blockStreaming — Bei true werden Antworten während der Generierung blockweise gesendet, ohne auf die vollständige Antwort zu warten. Lesebestätigungen werden standardmäßig gesendet, um einen natürlichen Gesprächsfluss zu erhalten. Tippindikatoren werden automatisch vor und während der KI-Antwortgenerierung gesendet.
openclaw.json
{
  "channels": {
    "bluebubbles": {
      "textChunkLimit": 4000,
      "chunkMode": "newline",
      "blockStreaming": false,
      "sendReadReceipts": true
    }
  }
}

Medien und Anhänge

BlueBubbles unterstützt das Senden und Empfangen von Medien über iMessage: • Eingehende Anhänge werden vom Gateway automatisch heruntergeladen und zwischengespeichert. Die maximale eingehende Dateigröße wird durch mediaMaxMb gesteuert (Standard: 8 MB). • Sprachmemos können über die sendAttachment-Aktion mit asVoice: true gesendet werden. BlueBubbles konvertiert MP3 automatisch in CAF für native iMessage-Sprachmemo-Wiedergabe. • Ausgehende Medien werden über die sendAttachment-Aktion mit buffer-, filename- und optionalen mime-Typ-Parametern gesendet.
Verwenden Sie für Sprachmemos das MP3- oder CAF-Format. BlueBubbles konvertiert MP3 automatisch in CAF für native iMessage-Wiedergabe.
Passen Sie mediaMaxMb an, wenn Sie größere Anhänge verarbeiten müssen — der Standardwert von 8 MB deckt die meisten Fotos und kurzen Videos ab.

Nachrichten-ID-Verwaltung

BlueBubbles verwendet zwei Arten von Nachrichtenidentifikatoren: • Kurze IDs — Temporäre In-Memory-Token (wie 1, 2, 3). Schnell, aber kurzlebig. Verfallen bei Gateway-Neustart oder Cache-Bereinigung. • Vollständige IDs — Persistente Provider-Identifikatoren (MessageSidFull, ReplyToIdFull). Überleben Neustarts und sind stabil für Langzeitreferenzen. Beide Formate werden in Aktionsparametern (messageId, replyTo etc.) akzeptiert. Für dauerhafte Automatisierungen, die Nachrichten über Neustarts hinweg referenzieren müssen, verwenden Sie immer vollständige IDs.
Verwenden Sie vollständige Nachrichten-IDs für jede Automatisierung, die Gateway-Neustarts überstehen muss. Kurze IDs sind für interaktive Nutzung praktisch, werden aber nach einem Neustart ungültig.

Adressierung und Routing

BlueBubbles unterstützt mehrere Adressformate für die Nachrichtenzustellung. Bevorzugte Routing-Reihenfolge nach Stabilität: 1. chat_guid — Stabilstes Format: chat_guid:iMessage;-;+15555550123 2. chat_id — Numerische Chat-Kennung: chat_id:123 3. chat_identifier — Chat-Kennungszeichenkette 4. Direkte Adressen — Telefonnummer (+15555550123) oder E-Mail (user@example.com) Beim Senden an eine direkte Adresse ohne bestehenden Chat erstellt BlueBubbles automatisch eine neue DM über POST /api/v1/chat/new (erfordert Private API).
Verwenden Sie in Automatisierungen das chat_guid-Format für das zuverlässigste Nachrichten-Routing.

Sicherheit und Webhook-Authentifizierung

BlueBubbles authentifiziert Webhook-Zustellungen mit dem konfigurierten Passwort. Das Gateway überprüft, ob der Passwort-Parameter (über Query-String oder Header) mit der channels.bluebubbles.password-Konfiguration übereinstimmt. Sicherheitsüberlegungen: • Localhost-Anfragen werden automatisch vertraut und umgehen die Passwortüberprüfung. • Reverse-Proxys auf dem gleichen Host umgehen ebenfalls die Passwortprüfung — wenn Sie einen Reverse-Proxy auf derselben Maschine verwenden, fügen Sie Proxy-Level-Authentifizierung hinzu und konfigurieren Sie gateway.trustedProxies. • Aktivieren Sie HTTPS auf dem BlueBubbles Server für verschlüsselte Kommunikation. • Verwenden Sie Firewall-Regeln, um externen Zugriff auf den BlueBubbles API-Port zu beschränken. Für Produktionsbereitstellungen verwenden Sie immer HTTPS und stellen Sie sicher, dass der Webhook-Endpunkt nicht ohne Authentifizierung öffentlich zugänglich ist.
Reverse-Proxys auf dem gleichen Host umgehen die BlueBubbles-Passwort-Authentifizierung. Konfigurieren Sie bei Verwendung eines Reverse-Proxys immer Proxy-Level-Authentifizierung und setzen Sie gateway.trustedProxies.

Messages.app Aufrechterhaltung (Headless/VM)

Wenn Sie BlueBubbles auf einem Headless-Mac oder einer VM ausführen, kann Messages.app in den Ruhezustand gehen und die Nachrichtenverarbeitung einstellen. Die Lösung ist ein LaunchAgent, der alle 5 Minuten ein AppleScript ausführt, um die Messages-Scripting-Schnittstelle anzusprechen. Dieses Keepalive-Skript ignoriert sicher vorübergehende Fehler und stiehlt keinen Fokus von anderen Anwendungen. Es ist wesentlich für den zuverlässigen unbeaufsichtigten Betrieb der iMessage-Brücke. Richten Sie einen macOS LaunchAgent-plist ein, um das AppleScript regelmäßig auszuführen und die Reaktionsfähigkeit von Messages.app aufrechtzuerhalten.
Dies ist nur für Headless/VM-Umgebungen erforderlich. Wenn Ihr Mac eine aktive Desktop-Sitzung mit sichtbarer Messages.app hat, ist das Keepalive nicht notwendig.
Verwenden Sie launchctl zur Verwaltung des LaunchAgent — laden Sie ihn beim Booten für vollständig unbeaufsichtigten Betrieb.

BlueBubbles Konfigurationsreferenz

enabled
Type: booleanDefault: false

BlueBubbles-Kanal aktivieren oder deaktivieren

serverUrl
Type: stringDefault: ""

BlueBubbles REST API Basis-URL (z.B. http://localhost:1234)

password
Type: stringDefault: ""

BlueBubbles API-Passwort zur Authentifizierung

webhookPath
Type: stringDefault: "/bluebubbles-webhook"

Webhook-Endpunktpfad für den Empfang eingehender Nachrichten

dmPolicy
Type: stringDefault: "pairing"

Steuert, wer dem Bot DMs senden kann. Optionen: pairing, allowlist, open, disabled

allowFrom
Type: string[]Default: []

Zum Nachrichtensenden berechtigte Telefonnummern und E-Mails (E.164-Format für Telefone)

groupPolicy
Type: stringDefault: "allowlist"

Gruppenchat-Richtlinie. Optionen: open, allowlist, disabled

groupAllowFrom
Type: string[]Default: []

Autorisierte Absenderadressen zum Auslösen des Bots in Gruppenchats

sendReadReceipts
Type: booleanDefault: true

Lesebestätigung bei Nachrichtenverarbeitung senden

blockStreaming
Type: booleanDefault: false

Blockbasiertes Antwort-Streaming aktivieren statt auf vollständige Antwort zu warten

textChunkLimit
Type: numberDefault: 4000

Maximale Zeichen pro ausgehendem Textnachrichtenblock

chunkMode
Type: stringDefault: "length"

Textaufteilungsmodus. Optionen: length (größenbasiert), newline (absatzbasiert)

mediaMaxMb
Type: numberDefault: 8

Maximale Dateigröße eingehender Anhänge in Megabyte

historyLimit
Type: numberDefault: -

Maximale Gruppennachrichten als KI-Kontext (0 deaktiviert)

dmHistoryLimit
Type: numberDefault: -

DM-Gesprächsverlaufslimit für KI-Kontext

actions.reactions
Type: booleanDefault: true

Tapback-Reaktionen aktivieren (erfordert Private API)

actions.edit
Type: booleanDefault: true

Nachrichtenbearbeitung aktivieren (erfordert macOS 13+; fehlerhaft auf Tahoe)

actions.unsend
Type: booleanDefault: true

Nachrichtenwiderruf aktivieren (erfordert macOS 13+)

actions.reply
Type: booleanDefault: true

Nachrichten-Threading per GUID aktivieren

actions.sendWithEffect
Type: booleanDefault: true

iMessage Blaseneffekte aktivieren (Slam, Laut, Sanft, etc.)

actions.sendAttachment
Type: booleanDefault: true

Medien- und Sprachmemo-Zustellung aktivieren

BlueBubbles Häufig gestellte Fragen

BlueBubbles Fehlerbehebung

Webhook empfängt keine Nachrichten

Die Webhook-URL in BlueBubbles stimmt nicht mit dem Gateway-Endpunkt überein, oder der Passwort-Parameter ist falsch.

Überprüfen Sie, dass die Webhook-URL auf https://your-gateway-host:3000/bluebubbles-webhook?password=YOUR_PASSWORD gesetzt ist. Prüfen Sie, ob channels.bluebubbles.webhookPath mit dem Pfad in der URL übereinstimmt. Überprüfen Sie die Gateway-Logs auf eingehende Webhook-Versuche.
Gateway verbunden, aber Aktionen schlagen fehl (Reaktionen, Bearbeitung, Widerruf)

Die BlueBubbles Private API ist nicht aktiviert, oder die Server-Version unterstützt die erforderlichen API-Endpunkte nicht.

Aktivieren Sie die Private API in den BlueBubbles Server-Einstellungen. Aktualisieren Sie BlueBubbles auf die neueste Version. Wenn bestimmte Aktionen auf macOS Tahoe fehlschlagen, deaktivieren Sie sie einzeln: channels.bluebubbles.actions.edit=false.
Messages.app reagiert nicht mehr auf Headless-Mac

Messages.app geht auf Headless/VM-Setups in den Ruhezustand und stoppt die Verarbeitung der Scripting-Schnittstelle.

Richten Sie den AppleScript-Keepalive-LaunchAgent ein, um alle 5 Minuten die Messages-Scripting-Schnittstelle anzusprechen. Stellen Sie sicher, dass der LaunchAgent über launchctl geladen wird und beim Booten ausgeführt wird.
Bot-Nachrichten sind keine iMessages (grüne Blasen)

Die Telefonnummer oder E-Mail des Empfängers ist nicht bei iMessage registriert, oder die Apple ID auf dem Mac hat iMessage deaktiviert.

Überprüfen Sie in den Messages.app-Einstellungen auf dem Mac, dass iMessage aktiviert ist. Prüfen Sie, ob der Empfänger ein Apple-Gerät mit aktiviertem iMessage verwendet. Grüne Blasen zeigen SMS-Fallback an, den BlueBubbles je nach Konfiguration möglicherweise nicht unterstützt.
Bearbeitungsaktion schlägt auf macOS Tahoe fehl

Bekanntes Problem — macOS Tahoe (26) hat den Private-API-Endpunkt für Nachrichtenbearbeitung beschädigt.

Deaktivieren Sie die Bearbeitungsaktion: Setzen Sie channels.bluebubbles.actions.edit auf false. Dies ist eine bekannte BlueBubbles-Einschränkung auf Tahoe. Beobachten Sie BlueBubbles-Releases für eine Lösung.
Vollständige Dokumentation anzeigenZurück zu allen Kanälen

Verwandte Kanäle

WhatsApp

Medium

OpenClaw Verbindung per QR-Code ueber das Baileys-Protokoll

Einrichtungsanleitung

Telegram

Easy

OpenClaw Bot API-Integration ueber das grammY-Framework

Einrichtungsanleitung

Discord

Easy

OpenClaw Bot Token-Integration mit discord.js

Einrichtungsanleitung