BlueBubbles (macOS REST)

Status: Mitgeliefertes Plugin, das über HTTP mit dem BlueBubbles macOS Server kommuniziert. Empfohlen für iMessage-Integration aufgrund der umfangreicheren API und einfacheren Einrichtung im Vergleich zum Legacy-imsg-Channel.

Überblick

Läuft auf macOS über die BlueBubbles Helper-App (bluebubbles.app).
Empfohlen/getestet: macOS Sequoia (15). macOS Tahoe (26) funktioniert; Edit ist aktuell auf Tahoe defekt, und Gruppen-Icon-Updates melden möglicherweise Erfolg, synchronisieren aber nicht.
OpenClaw kommuniziert über die REST API (GET /api/v1/ping, POST /message/text, POST /chat/:id/*).
Eingehende Nachrichten kommen über Webhooks; ausgehende Antworten, Tippanzeigen, Lesebestätigungen und Tapbacks sind REST-Aufrufe.
Anhänge und Sticker werden als eingehende Medien verarbeitet (und dem Agent bereitgestellt, wenn möglich).
Pairing/Allowlist funktioniert wie bei anderen Channels (/start/pairing etc.) mit channels.bluebubbles.allowFrom + Pairing-Codes.
Reaktionen werden als System-Events angezeigt, genau wie bei Slack/Telegram, sodass Agents sie vor der Antwort “erwähnen” können.
Erweiterte Features: Edit, Unsend, Reply-Threading, Nachrichteneffekte, Gruppenverwaltung.

Schnellstart

Installiere den BlueBubbles Server auf deinem Mac (folge der Anleitung auf bluebubbles.app/install).
Aktiviere in der BlueBubbles-Konfiguration die Web-API und setze ein Passwort.

Führe openclaw onboard aus und wähle BlueBubbles, oder konfiguriere manuell:

{
  channels: {
    bluebubbles: {
      enabled: true,
      serverUrl: "http://192.168.1.100:1234",
      password: "example-password",
      webhookPath: "/bluebubbles-webhook",
    },
  },
}

Richte die BlueBubbles Webhooks auf dein Gateway (Beispiel: https://your-gateway-host:3000/bluebubbles-webhook?password=<password>).
Starte das Gateway; es registriert den Webhook-Handler und startet das Pairing.

Onboarding

BlueBubbles ist im interaktiven Setup-Wizard verfügbar:

openclaw onboard

Der Wizard fragt nach:

Server URL (erforderlich): BlueBubbles Server-Adresse (z. B. http://192.168.1.100:1234)
Password (erforderlich): API-Passwort aus den BlueBubbles Server-Einstellungen
Webhook path (optional): Standard ist /bluebubbles-webhook
DM policy: pairing, allowlist, open oder disabled
Allow list: Telefonnummern, E-Mails oder Chat-Ziele

Du kannst BlueBubbles auch per CLI hinzufügen:

openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --password <password>

Zugriffskontrolle (DMs + Gruppen)

DMs:

Standard: channels.bluebubbles.dmPolicy = "pairing".
Unbekannte Absender erhalten einen Pairing-Code; Nachrichten werden ignoriert, bis sie genehmigt werden (Codes laufen nach 1 Stunde ab).
Genehmigung über:
- openclaw pairing list bluebubbles
- openclaw pairing approve bluebubbles <CODE>
Pairing ist der Standard-Token-Austausch. Details: Pairing

Gruppen:

channels.bluebubbles.groupPolicy = open | allowlist | disabled (Standard: allowlist).
channels.bluebubbles.groupAllowFrom steuert, wer in Gruppen triggern kann, wenn allowlist gesetzt ist.

Mention Gating (Gruppen)

BlueBubbles unterstützt Mention Gating für Gruppenchats, passend zum iMessage/WhatsApp-Verhalten:

Verwendet agents.list[].groupChat.mentionPatterns (oder messages.groupChat.mentionPatterns) zur Erkennung von Erwähnungen.
Wenn requireMention für eine Gruppe aktiviert ist, antwortet der Agent nur bei Erwähnung.
Control-Befehle von autorisierten Absendern umgehen das Mention Gating.

Konfiguration pro Gruppe:

{
  channels: {
    bluebubbles: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: {
        "*": { requireMention: true }, // Standard für alle Gruppen
        "iMessage;-;chat123": { requireMention: false }, // Überschreibung für spezifische Gruppe
      },
    },
  },
}

Command Gating

Control-Befehle (z. B. /config, /model) erfordern Autorisierung.
Verwendet allowFrom und groupAllowFrom zur Bestimmung der Befehlsautorisierung.
Autorisierte Absender können Control-Befehle auch ohne Erwähnung in Gruppen ausführen.

Tippanzeige + Lesebestätigungen

Tippanzeigen: Werden automatisch vor und während der Antwortgenerierung gesendet.
Lesebestätigungen: Gesteuert durch channels.bluebubbles.sendReadReceipts (Standard: true).
Tippanzeigen: OpenClaw sendet Tipp-Start-Events; BlueBubbles löscht die Tippanzeige automatisch beim Senden oder Timeout (manuelles Stoppen via DELETE ist unzuverlässig).

{
  channels: {
    bluebubbles: {
      sendReadReceipts: false, // Lesebestätigungen deaktivieren
    },
  },
}

Erweiterte Aktionen

BlueBubbles unterstützt erweiterte Nachrichtenaktionen, wenn sie in der Konfiguration aktiviert sind:

{
  channels: {
    bluebubbles: {
      actions: {
        reactions: true, // Tapbacks (Standard: true)
        edit: true, // Gesendete Nachrichten bearbeiten (macOS 13+, defekt auf macOS 26 Tahoe)
        unsend: true, // Nachrichten zurückziehen (macOS 13+)
        reply: true, // Reply-Threading per Message-GUID
        sendWithEffect: true, // Nachrichteneffekte (slam, loud, etc.)
        renameGroup: true, // Gruppenchats umbenennen
        setGroupIcon: true, // Gruppenchat-Icon/Foto setzen (instabil auf macOS 26 Tahoe)
        addParticipant: true, // Teilnehmer zu Gruppen hinzufügen
        removeParticipant: true, // Teilnehmer aus Gruppen entfernen
        leaveGroup: true, // Gruppenchats verlassen
        sendAttachment: true, // Anhänge/Medien senden
      },
    },
  },
}

Verfügbare Aktionen:

react: Tapback-Reaktionen hinzufügen/entfernen (messageId, emoji, remove)
edit: Gesendete Nachricht bearbeiten (messageId, text)
unsend: Nachricht zurückziehen (messageId)
reply: Auf eine bestimmte Nachricht antworten (messageId, text, to)
sendWithEffect: Mit iMessage-Effekt senden (text, to, effectId)
renameGroup: Gruppenchat umbenennen (chatGuid, displayName)
setGroupIcon: Icon/Foto eines Gruppenchats setzen (chatGuid, media) — instabil auf macOS 26 Tahoe (API meldet möglicherweise Erfolg, aber das Icon synchronisiert nicht).
addParticipant: Jemanden zu einer Gruppe hinzufügen (chatGuid, address)
removeParticipant: Jemanden aus einer Gruppe entfernen (chatGuid, address)
leaveGroup: Gruppenchat verlassen (chatGuid)
sendAttachment: Medien/Dateien senden (to, buffer, filename, asVoice)
- Sprachmemos: Setze asVoice: true mit MP3 oder CAF Audio, um als iMessage-Sprachnachricht zu senden. BlueBubbles konvertiert MP3 → CAF beim Senden von Sprachmemos.

Message IDs (kurz vs. vollständig)

OpenClaw kann kurze Message-IDs (z. B. 1, 2) anzeigen, um Tokens zu sparen.

MessageSid / ReplyToId können kurze IDs sein.
MessageSidFull / ReplyToIdFull enthalten die vollständigen Provider-IDs.
Kurze IDs sind im Speicher; sie können bei Neustart oder Cache-Eviction ablaufen.
Aktionen akzeptieren kurze oder vollständige messageId, aber kurze IDs führen zu Fehlern, wenn sie nicht mehr verfügbar sind.

Verwende vollständige IDs für dauerhafte Automatisierungen und Speicherung:

Templates: {{MessageSidFull}}, {{ReplyToIdFull}}
Context: MessageSidFull / ReplyToIdFull in eingehenden Payloads

Siehe Configuration für Template-Variablen.

Block Streaming

Steuere, ob Antworten als einzelne Nachricht oder in Blöcken gestreamt werden:

{
  channels: {
    bluebubbles: {
      blockStreaming: true, // Block Streaming aktivieren (Standardverhalten)
    },
  },
}

Medien + Limits

Eingehende Anhänge werden heruntergeladen und im Media-Cache gespeichert.
Medien-Limit über channels.bluebubbles.mediaMaxMb (Standard: 8 MB).
Ausgehender Text wird in Chunks aufgeteilt gemäß channels.bluebubbles.textChunkLimit (Standard: 4000 Zeichen).

Konfigurationsreferenz

Vollständige Konfiguration: Configuration

Provider-Optionen:

channels.bluebubbles.enabled: Channel aktivieren/deaktivieren.
channels.bluebubbles.serverUrl: BlueBubbles REST API Basis-URL.
channels.bluebubbles.password: API-Passwort.
channels.bluebubbles.webhookPath: Webhook-Endpunkt-Pfad (Standard: /bluebubbles-webhook).
channels.bluebubbles.dmPolicy: pairing | allowlist | open | disabled (Standard: pairing).
channels.bluebubbles.allowFrom: DM-Allowlist (Handles, E-Mails, E.164-Nummern, chat_id:*, chat_guid:*).
channels.bluebubbles.groupPolicy: open | allowlist | disabled (Standard: allowlist).
channels.bluebubbles.groupAllowFrom: Gruppen-Absender-Allowlist.
channels.bluebubbles.groups: Konfiguration pro Gruppe (requireMention, etc.).
channels.bluebubbles.sendReadReceipts: Lesebestätigungen senden (Standard: true).
channels.bluebubbles.blockStreaming: Block Streaming aktivieren (Standard: true).
channels.bluebubbles.textChunkLimit: Ausgehende Chunk-Größe in Zeichen (Standard: 4000).
channels.bluebubbles.chunkMode: length (Standard) teilt nur bei Überschreitung von textChunkLimit; newline teilt an Leerzeilen (Absatzgrenzen) vor der Längen-Aufteilung.
channels.bluebubbles.mediaMaxMb: Eingehendes Medien-Limit in MB (Standard: 8).
channels.bluebubbles.historyLimit: Maximale Gruppennachrichten für Context (0 deaktiviert).
channels.bluebubbles.dmHistoryLimit: DM-History-Limit.
channels.bluebubbles.actions: Spezifische Aktionen aktivieren/deaktivieren.
channels.bluebubbles.accounts: Multi-Account-Konfiguration.

Verwandte globale Optionen:

agents.list[].groupChat.mentionPatterns (oder messages.groupChat.mentionPatterns).
messages.responsePrefix.

Adressierung / Zustellungsziele

Bevorzuge chat_guid für stabiles Routing:

chat_guid:iMessage;-;+15555550123 (bevorzugt für Gruppen)
chat_id:123
chat_identifier:...
Direkte Handles: +15555550123, [email protected]
- Wenn ein direktes Handle keinen existierenden DM-Chat hat, erstellt OpenClaw einen über POST /api/v1/chat/new. Dies erfordert, dass die BlueBubbles Private API aktiviert ist.

Sicherheit

Webhook-Anfragen werden authentifiziert, indem guid/password Query-Parameter oder Header mit channels.bluebubbles.password verglichen werden. Anfragen von localhost werden ebenfalls akzeptiert.
Halte das API-Passwort und den Webhook-Endpunkt geheim (behandle sie wie Zugangsdaten).
Localhost-Trust bedeutet, dass ein Reverse-Proxy auf demselben Host unbeabsichtigt das Passwort umgehen kann. Wenn du das Gateway proxyst, verlange Auth am Proxy und konfiguriere gateway.trustedProxies. Siehe Gateway Security.
Aktiviere HTTPS + Firewall-Regeln auf dem BlueBubbles Server, wenn du ihn außerhalb deines LANs exponierst.

Troubleshooting

Wenn Tipp-/Lese-Events nicht mehr funktionieren, prüfe die BlueBubbles Webhook-Logs und stelle sicher, dass der Gateway-Pfad mit channels.bluebubbles.webhookPath übereinstimmt.
Pairing-Codes laufen nach einer Stunde ab; verwende openclaw pairing list bluebubbles und openclaw pairing approve bluebubbles <code>.
Reaktionen erfordern die BlueBubbles Private API (POST /api/v1/message/react); stelle sicher, dass die Server-Version sie bereitstellt.
Edit/Unsend erfordern macOS 13+ und eine kompatible BlueBubbles Server-Version. Auf macOS 26 (Tahoe) ist Edit aktuell defekt aufgrund von Private-API-Änderungen.
Gruppen-Icon-Updates können auf macOS 26 (Tahoe) instabil sein: Die API meldet möglicherweise Erfolg, aber das neue Icon synchronisiert nicht.
OpenClaw blendet bekanntermaßen defekte Aktionen basierend auf der macOS-Version des BlueBubbles Servers automatisch aus. Wenn Edit auf macOS 26 (Tahoe) trotzdem erscheint, deaktiviere es manuell mit channels.bluebubbles.actions.edit=false.
Für Status-/Health-Infos: openclaw status --all oder openclaw status --deep.

Für allgemeine Channel-Workflow-Referenz siehe Channels und den Plugins Guide.