BlueBubbles (macOS REST)

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

Überblick

  • Läuft auf macOS über die BlueBubbles-Hilfsapp (bluebubbles.app).
  • Empfohlen/getestet: macOS Sequoia (15). macOS Tahoe (26) funktioniert; Bearbeiten ist auf Tahoe derzeit defekt, und Gruppensymbol-Aktualisierungen 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 via Webhooks; ausgehende Antworten, Tippindikatoren, Lesebestätigungen und Tapbacks sind REST-Aufrufe.
  • Anhänge und Sticker werden als eingehende Medien aufgenommen (und dem Agent wenn möglich bereitgestellt).
  • Pairing/Allowlist funktioniert wie bei anderen Kanälen (/channels/pairing usw.) mit channels.bluebubbles.allowFrom + Pairing-Codes.
  • Reaktionen werden als Systemereignisse bereitgestellt, genau wie bei Slack/Telegram, sodass Agents sie vor der Antwort „erwähnen” können.
  • Erweiterte Funktionen: Bearbeiten, Zurückziehen, Antwort-Threading, Nachrichteneffekte, Gruppenverwaltung.

Schnellstart

  1. Installiere den BlueBubbles-Server auf deinem Mac (folge den Anweisungen unter bluebubbles.app/install).

  2. Aktiviere in der BlueBubbles-Konfiguration die Web-API und setze ein Passwort.

  3. 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",
    },
  },
}

  4. Richte die BlueBubbles-Webhooks auf dein Gateway (Beispiel: https://your-gateway-host:3000/bluebubbles-webhook?password=<password>).

  5. Starte das Gateway; es registriert den Webhook-Handler und beginnt mit dem Pairing.

Sicherheitshinweis:

  • Setze immer ein Webhook-Passwort.
  • Webhook-Authentifizierung ist immer erforderlich. OpenClaw lehnt BlueBubbles-Webhook-Anfragen ab, sofern sie kein Passwort/GUID enthalten, das mit channels.bluebubbles.password übereinstimmt (zum Beispiel ?password=<password> oder x-password), unabhängig von Loopback-/Proxy-Topologie.
  • Die Passwortauthentifizierung wird geprüft, bevor vollständige Webhook-Bodies gelesen/geparst werden.

Messages.app aktiv halten (VM / Headless-Setups)

Einige macOS-VM-/Dauerbetrieb-Setups können dazu führen, dass Messages.app in den „Leerlauf” geht (eingehende Events stoppen, bis die App geöffnet/in den Vordergrund gebracht wird). Eine einfache Abhilfe ist, Messages alle 5 Minuten anzustoßen mit einem AppleScript + LaunchAgent.

1) AppleScript speichern

Speichere es als:

  • ~/Scripts/poke-messages.scpt

Beispielskript (nicht-interaktiv; stiehlt keinen Fokus):

try
  tell application "Messages"
    if not running then
      launch
    end if

    -- Touch the scripting interface to keep the process responsive.
    set _chatCount to (count of chats)
  end tell
on error
  -- Ignore transient failures (first-run prompts, locked session, etc).
end try

2) LaunchAgent installieren

Speichere es als:

  • ~/Library/LaunchAgents/com.user.poke-messages.plist
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>Label</key>
    <string>com.user.poke-messages</string>

    <key>ProgramArguments</key>
    <array>
      <string>/bin/bash</string>
      <string>-lc</string>
      <string>/usr/bin/osascript &quot;$HOME/Scripts/poke-messages.scpt&quot;</string>
    </array>

    <key>RunAtLoad</key>
    <true/>

    <key>StartInterval</key>
    <integer>300</integer>

    <key>StandardOutPath</key>
    <string>/tmp/poke-messages.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/poke-messages.err</string>
  </dict>
</plist>

Hinweise:

  • Dies wird alle 300 Sekunden und beim Login ausgeführt.
  • Der erste Durchlauf kann macOS-Automation-Aufforderungen auslösen (osascript -> Messages). Genehmige sie in derselben Benutzersitzung, die den LaunchAgent ausführt.

Laden:

launchctl unload ~/Library/LaunchAgents/com.user.poke-messages.plist 2>/dev/null || true
launchctl load ~/Library/LaunchAgents/com.user.poke-messages.plist

Onboarding

BlueBubbles ist im interaktiven Einrichtungsassistenten verfügbar:

openclaw onboard

Der Assistent fragt nach:

  • 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 ist /bluebubbles-webhook
  • DM-Richtlinie: pairing, allowlist, open oder disabled
  • Allowlist: Telefonnummern, E-Mail-Adressen oder Chat-Ziele

Du kannst BlueBubbles auch über die CLI hinzufügen:

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

Zugriffssteuerung (DMs + Gruppen)

DMs:

  • Standard: channels.bluebubbles.dmPolicy = "pairing".
  • Unbekannte Absender erhalten einen Pairing-Code; Nachrichten werden ignoriert, bis sie genehmigt sind (Codes verfallen nach 1 Stunde).
  • 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 auslösen 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 Mention-Erkennung.
  • Wenn requireMention für eine Gruppe aktiviert ist, antwortet der Agent nur bei Erwähnung.
  • Steuerbefehle von autorisierten Absendern umgehen das Mention-Gating.

Pro-Gruppen-Konfiguration:

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

Befehlsautorisierung

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

Tippanzeige + Lesebestätigungen

  • Tippindikatoren: Werden automatisch vor und während der Antwortgenerierung gesendet.
  • Lesebestätigungen: Gesteuert durch channels.bluebubbles.sendReadReceipts (Standard: true).
  • Tippindikatoren: 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, // Antwort-Threading nach Nachrichten-GUID
        sendWithEffect: true, // Nachrichteneffekte (Slam, Laut usw.)
        renameGroup: true, // Gruppenchats umbenennen
        setGroupIcon: true, // Gruppenchat-Symbol/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 bestimmte Nachricht antworten (messageId, text, to)
  • sendWithEffect: Mit iMessage-Effekt senden (text, to, effectId)
  • renameGroup: Gruppenchat umbenennen (chatGuid, displayName)
  • setGroupIcon: Gruppenchat-Symbol/Foto setzen (chatGuid, media) — instabil auf macOS 26 Tahoe (API meldet möglicherweise Erfolg, aber das Symbol synchronisiert nicht).
  • addParticipant: Jemanden zur Gruppe hinzufügen (chatGuid, address)
  • removeParticipant: Jemanden aus der Gruppe entfernen (chatGuid, address)
  • leaveGroup: Gruppenchat verlassen (chatGuid)
  • sendAttachment: Medien/Dateien senden (to, buffer, filename, asVoice)
    • Sprachnachrichten: Setze asVoice: true mit MP3- oder CAF-Audio, um als iMessage-Sprachnachricht zu senden. BlueBubbles konvertiert MP3 zu CAF beim Senden von Sprachnachrichten.

Nachrichten-IDs (kurz vs. vollständig)

OpenClaw kann kurze Nachrichten-IDs (z. B. 1, 2) bereitstellen, um Token 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 ergeben einen Fehler, wenn sie nicht mehr verfügbar sind.

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

  • Templates: {{MessageSidFull}}, {{ReplyToIdFull}}
  • Kontext: 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 (standardmäßig aus)
    },
  },
}

Medien + Limits

  • Eingehende Anhänge werden heruntergeladen und im Medien-Cache gespeichert.
  • Medien-Obergrenze via channels.bluebubbles.mediaMaxMb für ein- und ausgehende Medien (Standard: 8 MB).
  • Ausgehender Text wird auf channels.bluebubbles.textChunkLimit 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-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: Pro-Gruppen-Konfiguration (requireMention usw.).
  • channels.bluebubbles.sendReadReceipts: Lesebestätigungen senden (Standard: true).
  • channels.bluebubbles.blockStreaming: Block-Streaming aktivieren (Standard: false; erforderlich für Streaming-Antworten).
  • channels.bluebubbles.textChunkLimit: Ausgehende Blockgröße in Zeichen (Standard: 4000).
  • channels.bluebubbles.chunkMode: length (Standard) teilt nur auf, wenn textChunkLimit überschritten wird; newline teilt an Leerzeilen (Absatzgrenzen) vor dem Längen-Chunking.
  • channels.bluebubbles.mediaMaxMb: Medien-Obergrenze ein-/ausgehend in MB (Standard: 8).
  • channels.bluebubbles.mediaLocalRoots: Explizite Allowlist absoluter lokaler Verzeichnisse, die für ausgehende lokale Medienpfade erlaubt sind. Lokale Pfadsendungen werden standardmäßig verweigert, sofern dies nicht konfiguriert ist. Pro-Konto-Überschreibung: channels.bluebubbles.accounts.<accountId>.mediaLocalRoots.
  • channels.bluebubbles.historyLimit: Max. Gruppennachrichten für Kontext (0 deaktiviert).
  • channels.bluebubbles.dmHistoryLimit: DM-Verlaufslimit.
  • channels.bluebubbles.actions: Bestimmte 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

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 bestehenden DM-Chat hat, erstellt OpenClaw einen via 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-Vertrauen bedeutet, dass ein Same-Host-Reverse-Proxy das Passwort unbeabsichtigt umgehen kann. Wenn du das Gateway proxiest, erzwinge 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.

Fehlerbehebung

  • 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 verfallen nach einer Stunde; 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 Serverversion sie bereitstellt.
  • Bearbeiten/Zurückziehen erfordert macOS 13+ und eine kompatible BlueBubbles-Serverversion. Auf macOS 26 (Tahoe) ist Bearbeiten derzeit aufgrund von Private-API-Änderungen defekt.
  • Gruppensymbol-Aktualisierungen können auf macOS 26 (Tahoe) instabil sein: Die API meldet möglicherweise Erfolg, aber das neue Symbol synchronisiert nicht.
  • OpenClaw blendet bekannt defekte Aktionen basierend auf der macOS-Version des BlueBubbles-Servers automatisch aus. Wenn Bearbeiten auf macOS 26 (Tahoe) weiterhin erscheint, deaktiviere es manuell mit channels.bluebubbles.actions.edit=false.
  • Für Status-/Gesundheitsinformationen: openclaw status --all oder openclaw status --deep.

Allgemeine Kanal-Workflow-Referenz findest du unter Channels und im Plugins-Leitfaden.

arrow_back
Zurück
Channels
Weiter
Discord
arrow_forward