Skip to Content
👋 Willkommen bei HowToUseOpenClaw Schnellstart
KanäleBlue Bubbles

BlueBubbles (macOS REST)

Status: Mitgeliefertes Plugin, das per HTTP mit dem BlueBubbles-macOS-Server spricht. Empfohlen für iMessage-Integration dank besserer API und einfacherer Einrichtung im Vergleich zum Legacy-imsg-Kanal.

Überblick

  • Läuft unter macOS über die BlueBubbles-Hilfsanwendung (bluebubbles.app ).
  • Empfohlen/getestet: macOS Sequoia (15). macOS Tahoe (26) funktioniert; Bearbeiten ist unter Tahoe derzeit defekt, und Gruppen-Icon-Updates können Erfolg melden, aber nicht synchronisieren.
  • OpenClaw kommuniziert über die REST-API (GET /api/v1/ping, POST /message/text, POST /chat/:id/*).
  • Eingehende Nachrichten kommen per Webhooks; ausgehende Antworten, Tipp-Indikatoren, Lesebestätigungen und Tapbacks sind REST-Aufrufe.
  • Anhänge und Sticker werden als eingehende Medien übernommen (und dem Agenten nach Möglichkeit bereitgestellt).
  • Pairing/Allowlist funktioniert wie bei anderen Kanälen (/start/pairing usw.) mit channels.bluebubbles.allowFrom + Pairing-Codes.
  • Reaktionen werden wie bei Slack/Telegram als Systemereignisse bereitgestellt, damit Agenten sie vor der Antwort „erwähnen“ können.
  • Erweiterte Funktionen: Bearbeiten, Widerrufen, Antwort-Threading, Nachrichteneffekte, Gruppenverwaltung.

Schnellstart

  1. Installieren Sie den BlueBubbles-Server auf Ihrem Mac (Anleitung unter bluebubbles.app/install ).
  2. Aktivieren Sie in der BlueBubbles-Konfiguration die Web-API und setzen Sie ein Passwort.
  3. Führen Sie openclaw onboard aus und wählen Sie BlueBubbles, oder konfigurieren Sie manuell:
{
     channels: {
       bluebubbles: {
         enabled: true,
         serverUrl: "http://192.168.1.100:1234",
         password: "example-password",
         webhookPath: "/bluebubbles-webhook"
       }
     }
}
  1. Richten Sie die BlueBubbles-Webhooks auf Ihr Gateway (z. B. https://your-gateway-host:3000/bluebubbles-webhook?password=<password>).
  2. Starten Sie das Gateway; es registriert den Webhook-Handler und startet das Pairing.

Einrichtung

BlueBubbles ist im interaktiven Setup-Assistenten verfügbar:

openclaw onboard

Der Assistent fragt ab:

  • Server-URL (erforderlich): BlueBubbles-Serveradresse (z. B. http://192.168.1.100:1234)
  • Passwort (erforderlich): API-Passwort aus den BlueBubbles-Server-Einstellungen
  • Webhook-Pfad (optional): Standard /bluebubbles-webhook
  • DM-Richtlinie: pairing, allowlist, open oder disabled
  • Erlaubnisliste: Telefonnummern, E-Mails oder Chat-Ziele

BlueBubbles können Sie 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 freigegeben sind (Codes laufen nach 1 Stunde ab).
  • Freigabe ü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 legt fest, wer in Gruppen auslösen darf, wenn allowlist gesetzt ist.

Erwähnungspflicht (Gruppen)

BlueBubbles unterstützt Erwähnungspflicht für Gruppenchats, analog zu iMessage/WhatsApp:

  • Nutzt agents.list[].groupChat.mentionPatterns (oder messages.groupChat.mentionPatterns) zur Erkennung von Erwähnungen.
  • Ist requireMention für eine Gruppe aktiv, antwortet der Agent nur bei Erwähnung.
  • Steuerbefehle von autorisierten Absendern umgehen die Erwähnungspflicht.

Konfiguration pro Gruppe:

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

Befehls-Steuerung

  • Steuerbefehle (z. B. /config, /model) erfordern Autorisierung.
  • Es werden allowFrom und groupAllowFrom zur Befehls-Autorisierung verwendet.
  • Autorisierten Absendern stehen Steuerbefehle auch ohne Erwähnung in Gruppen zur Verfügung.

Tippen + Lesebestätigungen

  • Tipp-Indikatoren: Werden automatisch vor und während der Antwortgenerierung gesendet.
  • Lesebestätigungen: Steuerung über channels.bluebubbles.sendReadReceipts (Standard: true).
  • Tipp-Indikatoren: OpenClaw sendet Tipp-Start-Ereignisse; BlueBubbles beendet Tippen automatisch beim Senden oder bei Timeout (manueller Stopp per DELETE ist unzuverlässig).
{
  channels: {
    bluebubbles: {
      sendReadReceipts: false  // Lesebestätigungen deaktivieren
    }
  }
}

Erweiterte Aktionen

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

{
  channels: {
    bluebubbles: {
      actions: {
        reactions: true,       // Tapbacks (Standard: true)
        edit: true,            // gesendete Nachrichten bearbeiten (macOS 13+, unter macOS 26 Tahoe defekt)
        unsend: true,          // Nachrichten widerrufen (macOS 13+)
        reply: true,           // Antwort-Threading per Nachrichten-GUID
        sendWithEffect: true,  // Nachrichteneffekte (slam, loud usw.)
        renameGroup: true,     // Gruppenchats umbenennen
        setGroupIcon: true,    // Gruppenchat-Icon/Foto setzen (unter macOS 26 Tahoe instabil)
        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 widerrufen (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) — unter macOS 26 Tahoe instabil (API kann Erfolg melden, das Icon wird aber nicht synchronisiert).

  • 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)

    • Sprachnachrichten: Mit MP3- oder **CAF-**Audio asVoice: true setzen, um als iMessage-Sprachnachricht zu senden. BlueBubbles konvertiert MP3 → CAF beim Senden von Sprachnachrichten.

Nachrichten-IDs (kurz vs. vollständig)

OpenClaw kann kurze Nachrichten-IDs (z. B. 1, 2) zur Token-Ersparnis bereitstellen.

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

Für dauerhafte Automatisierungen und Speicherung vollständige IDs verwenden:

  • Templates: {{MessageSidFull}}, {{ReplyToIdFull}}
  • Kontext: MessageSidFull / ReplyToIdFull in eingehenden Payloads

Siehe Configuration für Template-Variablen.

Block-Streaming

Steuern, 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 Medien-Cache gespeichert.
  • Medien-Limit über channels.bluebubbles.mediaMaxMb (Standard: 8 MB).
  • Ausgehender Text wird in channels.bluebubbles.textChunkLimit-Blöcke aufgeteilt (Standard: 4000 Zeichen).

Konfigurationsreferenz

Vollständige Konfiguration: Configuration. Provider-Optionen:

  • channels.bluebubbles.enabled: Kanal 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-Erlaubnisliste (Handles, E-Mails, E.164-Nummern, chat_id:*, chat_guid:*).
  • channels.bluebubbles.groupPolicy: open | allowlist | disabled (Standard: allowlist).
  • channels.bluebubbles.groupAllowFrom: Gruppen-Absender-Erlaubnisliste.
  • channels.bluebubbles.groups: Konfiguration pro Gruppe (requireMention usw.).
  • 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 bei Leerzeilen (Absatzgrenzen) vor der Längenaufteilung.
  • channels.bluebubbles.mediaMaxMb: Eingehendes Medien-Limit in MB (Standard: 8).
  • channels.bluebubbles.historyLimit: Maximale Gruppennachrichten für Kontext (0 deaktiviert).
  • channels.bluebubbles.dmHistoryLimit: DM-Verlaufslimit.
  • channels.bluebubbles.actions: Einzelne Aktionen aktivieren/deaktivieren.
  • channels.bluebubbles.accounts: Multi-Account-Konfiguration.

Zugehörige globale Optionen:

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

Adressierung / Zustellziele

Für stabiles Routing chat_guid bevorzugen:

  • chat_guid:iMessage;-;+15555550123 (bevorzugt für Gruppen)
  • chat_id:123
  • chat_identifier:...
  • Direkte Handles: +15555550123, user@example.com
    • Existiert für einen direkten Handle noch kein DM-Chat, erstellt OpenClaw einen per POST /api/v1/chat/new. Dafür muss die BlueBubbles Private API aktiviert sein.

Sicherheit

  • Webhook-Anfragen werden authentifiziert, indem guid/password aus Query-Parametern oder Headern mit channels.bluebubbles.password verglichen werden. Anfragen von localhost werden ebenfalls akzeptiert.
  • API-Passwort und Webhook-Endpunkt geheim halten (wie Zugangsdaten behandeln).
  • Localhost-Vertrauen bedeutet, dass ein Reverse-Proxy auf demselben Host das Passwort unbeabsichtigt umgehen kann. Beim Proxying des Gateways Auth am Proxy erzwingen und gateway.trustedProxies konfigurieren. Siehe Gateway-Sicherheit.
  • HTTPS und Firewall-Regeln auf dem BlueBubbles-Server aktivieren, wenn er außerhalb des LANs erreichbar sein soll.

Fehlerbehebung

  • Wenn Tipp-/Lese-Ereignisse ausbleiben: BlueBubbles-Webhook-Logs prüfen und sicherstellen, dass der Gateway-Pfad mit channels.bluebubbles.webhookPath übereinstimmt.
  • Pairing-Codes laufen nach einer Stunde ab; verwenden Sie openclaw pairing list bluebubbles und openclaw pairing approve bluebubbles <code>.
  • Reaktionen benötigen die BlueBubbles Private API (POST /api/v1/message/react); prüfen Sie, dass die Serverversion sie bereitstellt.
  • Bearbeiten/Widerrufen erfordert macOS 13+ und eine kompatible BlueBubbles-Serverversion. Unter macOS 26 (Tahoe) ist Bearbeiten derzeit wegen Änderungen der Private API defekt.
  • Gruppen-Icon-Updates können unter macOS 26 (Tahoe) instabil sein: Die API kann Erfolg melden, das neue Icon wird aber nicht synchronisiert.
  • OpenClaw blendet bekannte defekte Aktionen anhand der macOS-Version des BlueBubbles-Servers aus. Erscheint Bearbeiten unter macOS 26 (Tahoe) weiterhin, manuell mit channels.bluebubbles.actions.edit=false deaktivieren.
  • Für Status-/Health-Infos: openclaw status --all oder openclaw status --deep.

Allgemeine Kanal-Abläufe: Channels und Plugins-Anleitung.

Zuletzt aktualisiert am:
Discord