BlueBubbles

Status: gebündeltes Legacy-Plugin, das über HTTP mit dem BlueBubbles-macOS-Server kommuniziert. Bestehende BlueBubbles-Setups funktionieren weiterhin, neue OpenClaw-iMessage-Bereitstellungen sollten jedoch das native iMessage-Plugin bevorzugen, wenn dessen Anforderungen zu Ihrem Host passen.

# Überblick

• Läuft unter macOS über die BlueBubbles-Helper-App (bluebubbles.app).
• Legacy-Fallback für Installationen, die bereits auf BlueBubbles-Kanal-IDs, Webhook-Status, Gruppenziele, Cron-Zustellung oder Workspace-Routing angewiesen sind.
• Empfohlen/getestet: macOS Sequoia (15). macOS Tahoe (26) funktioniert; Bearbeiten ist unter Tahoe derzeit defekt, und Aktualisierungen von Gruppensymbolen melden eventuell Erfolg, synchronisieren aber nicht.
• OpenClaw kommuniziert damit über die REST-API (GET /api/v1/ping, POST /message/text, POST /chat/:id/*).
• Eingehende Nachrichten treffen über Webhooks ein; ausgehende Antworten, Tippindikatoren, Lesebestätigungen und Tapbacks sind REST-Aufrufe.
• Anhänge und Sticker werden als eingehende Medien aufgenommen und, wenn möglich, dem Agenten bereitgestellt.
• Auto-TTS-Antworten, die MP3- oder CAF-Audio synthetisieren, werden als iMessage-Sprachmemo-Blasen statt als einfache Dateianhänge zugestellt.
• Pairing/Allowlist funktioniert wie bei anderen Kanälen (/channels/pairing usw.) mit channels.bluebubbles.allowFrom + Pairing-Codes.
• Reaktionen werden genau wie bei Slack/Telegram als Systemereignisse bereitgestellt, sodass Agenten sie vor dem Antworten „erwähnen“ können.
• Erweiterte Funktionen: Bearbeiten, Senden rückgängig machen, Antwort-Threads, Nachrichteneffekte, Gruppenverwaltung.

# Schnellstart

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

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

Einige macOS-VM- oder Always-on-Setups können dazu führen, dass Messages.app „idle“ wird (eingehende Ereignisse stoppen, bis die App geöffnet/in den Vordergrund gebracht wird). Ein einfacher Workaround besteht darin, Messages alle 5 Minuten anzustoßen, mit einem AppleScript + LaunchAgent.

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

<?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>

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 Onboarding verfügbar:

openclaw onboard

Der Assistent fragt nach:

Sie können BlueBubbles auch per CLI hinzufügen:

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

# Zugriffskontrolle (DMs + Gruppen)

# Kontaktnamen-Anreicherung (macOS, optional)

BlueBubbles-Gruppen-Webhooks enthalten häufig nur rohe Teilnehmeradressen. Wenn Sie möchten, dass der GroupMembers-Kontext stattdessen lokale Kontaktnamen anzeigt, können Sie unter macOS lokale Kontakte-Anreicherung aktivieren:

• channels.bluebubbles.enrichGroupParticipantsFromContacts = true aktiviert die Suche. Standard: false.
• Suchvorgänge laufen erst, nachdem Gruppenzugriff, Befehlsautorisierung und Mention-Gating die Nachricht zugelassen haben.
• Nur unbenannte Telefonnummern-Teilnehmer werden angereichert.
• Rohe Telefonnummern bleiben der Fallback, wenn keine lokale Übereinstimmung gefunden wird.

{
  channels: {
    bluebubbles: {
      enrichGroupParticipantsFromContacts: true,
    },
  },
}

# Mention-Gating (Gruppen)

BlueBubbles unterstützt Mention-Gating für Gruppenchats und entspricht damit dem Verhalten von iMessage/WhatsApp:

• Verwendet agents.list[].groupChat.mentionPatterns (oder messages.groupChat.mentionPatterns), um Mentions zu erkennen.
• Wenn requireMention für eine Gruppe aktiviert ist, antwortet der Agent nur, wenn er erwähnt wird.
• Steuerbefehle von autorisierten Absendern umgehen Mention-Gating.

Konfiguration pro Gruppe:

{
  channels: {
    bluebubbles: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: {
        "*": { requireMention: true }, // default for all groups
        "iMessage;-;chat123": { requireMention: false }, // override for specific group
      },
    },
  },
}

# Befehls-Gating

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

# System-Prompt pro Gruppe

Jeder Eintrag unter channels.bluebubbles.groups.* akzeptiert einen optionalen systemPrompt-String. Der Wert wird bei jedem Turn, der eine Nachricht in dieser Gruppe verarbeitet, in den System-Prompt des Agenten eingefügt, sodass Sie gruppenspezifische Persona- oder Verhaltensregeln festlegen können, ohne Agenten-Prompts zu bearbeiten:

{
  channels: {
    bluebubbles: {
      groups: {
        "iMessage;-;chat123": {
          systemPrompt: "Keep responses under 3 sentences. Mirror the group's casual tone.",
        },
      },
    },
  },
}

Der Schlüssel entspricht dem, was BlueBubbles für die Gruppe als chatGuid / chatIdentifier / numerische chatId meldet, und ein "*"-Wildcard-Eintrag stellt einen Standard für jede Gruppe ohne genaue Übereinstimmung bereit (dasselbe Muster wie bei requireMention und Tool-Richtlinien pro Gruppe). Genaue Übereinstimmungen haben immer Vorrang vor der Wildcard. DMs ignorieren dieses Feld; verwenden Sie stattdessen Prompt-Anpassung auf Agenten- oder Kontoebene.

# Ausgearbeitetes Beispiel: Thread-Antworten und Tapback-Reaktionen (Private API)

Wenn die BlueBubbles Private API aktiviert ist, treffen eingehende Nachrichten mit kurzen Nachrichten-IDs ein (zum Beispiel [[reply_to:5]]), und der Agent kann action=reply aufrufen, um in eine bestimmte Nachricht einzufädeln, oder action=react, um einen Tapback zu setzen. Ein systemPrompt pro Gruppe ist eine zuverlässige Möglichkeit, den Agenten dazu zu bringen, das richtige Tool auszuwählen:

{
  channels: {
    bluebubbles: {
      groups: {
        "iMessage;+;chat-family": {
          systemPrompt: "When replying in this group, always call action=reply with the [[reply_to:N]] messageId from context so your response threads under the triggering message. Never send a new unlinked message. For short acknowledgements ('ok', 'got it', 'on it'), use action=react with an appropriate tapback emoji (❤️, 👍, 😂, ‼️, ❓) instead of sending a text reply.",
        },
      },
    },
  },
}

Tapback-Reaktionen und Thread-Antworten erfordern beide die BlueBubbles Private API; siehe Erweiterte Aktionen und Nachrichten-IDs für die zugrunde liegenden Mechanismen.

# ACP-Konversationsbindungen

BlueBubbles-Chats können in dauerhafte ACP-Workspaces umgewandelt werden, ohne die Transportschicht zu ändern.

Schneller Operator-Ablauf:

• Führen Sie /acp spawn codex --bind here innerhalb der DM oder des erlaubten Gruppenchats aus.
• Zukünftige Nachrichten in derselben BlueBubbles-Konversation werden an die gestartete ACP-Sitzung geroutet.
• /new und /reset setzen dieselbe gebundene ACP-Sitzung direkt zurück.
• /acp close schließt die ACP-Sitzung und entfernt die Bindung.

Konfigurierte persistente Bindungen werden auch über Top-Level-bindings[]-Einträge mit type: "acp" und match.channel: "bluebubbles" unterstützt.

match.peer.id kann jede unterstützte BlueBubbles-Zielform verwenden:

• normalisiertes DM-Handle wie +15555550123 oder [email protected]
• chat_id:<id>
• chat_guid:<guid>
• chat_identifier:<identifier>

Für stabile Gruppenbindungen bevorzugen Sie chat_id:* oder chat_identifier:*.

Beispiel:

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: { agent: "codex", backend: "acpx", mode: "persistent" },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "bluebubbles",
        accountId: "default",
        peer: { kind: "dm", id: "+15555550123" },
      },
      acp: { label: "codex-imessage" },
    },
  ],
}

Siehe ACP-Agenten für gemeinsames ACP-Bindungsverhalten.

# Tippanzeige + Lesebestätigungen

• Tippanzeigen: Werden vor und während der Antwortgenerierung automatisch gesendet.
• Lesebestätigungen: Gesteuert über channels.bluebubbles.sendReadReceipts (Standard: true).
• Tippanzeigen: OpenClaw sendet Ereignisse für den Tippbeginn; BlueBubbles löscht die Tippanzeige automatisch beim Senden oder nach einem Timeout (manuelles Stoppen per DELETE ist unzuverlässig).

{
  channels: {
    bluebubbles: {
      sendReadReceipts: false, // disable read receipts
    },
  },
}

# Erweiterte Aktionen

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

{
  channels: {
    bluebubbles: {
      actions: {
        reactions: true, // tapbacks (default: true)
        edit: true, // edit sent messages (macOS 13+, broken on macOS 26 Tahoe)
        unsend: true, // unsend messages (macOS 13+)
        reply: true, // reply threading by message GUID
        sendWithEffect: true, // message effects (slam, loud, etc.)
        renameGroup: true, // rename group chats
        setGroupIcon: true, // set group chat icon/photo (flaky on macOS 26 Tahoe)
        addParticipant: true, // add participants to groups
        removeParticipant: true, // remove participants from groups
        leaveGroup: true, // leave group chats
        sendAttachment: true, // send attachments/media
      },
    },
  },
}

# Nachrichten-IDs (kurz vs. vollständig)

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

• MessageSid / ReplyToId können kurze IDs sein.
• MessageSidFull / ReplyToIdFull enthalten die vollständigen Provider-IDs.
• Kurze IDs liegen im Speicher; sie können nach einem Neustart oder Cache-Verdrängung ablaufen.
• Aktionen akzeptieren kurze oder vollständige messageId, aber kurze IDs geben einen Fehler aus, wenn sie nicht mehr verfügbar sind.

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

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

Siehe Konfiguration für Vorlagenvariablen.

# Zusammenführen aufgeteilter DM-Sendungen (Befehl + URL in einer Komposition)

Wenn ein Benutzer in iMessage einen Befehl und eine URL zusammen eingibt - z. B. Dump https://example.com/article -, teilt Apple den Versand in zwei separate Webhook-Zustellungen auf:

1. Eine Textnachricht ("Dump").
2. Eine URL-Vorschaublase ("https://...") mit OG-Vorschaubildern als Anhängen.

Die beiden Webhooks treffen bei den meisten Setups im Abstand von ca. 0,8-2,0 s bei OpenClaw ein. Ohne Zusammenführung erhält der Agent in Runde 1 nur den Befehl, antwortet (oft „send me the URL“) und sieht die URL erst in Runde 2 - dann ist der Befehlskontext bereits verloren.

channels.bluebubbles.coalesceSameSenderDms aktiviert für eine DM das Zusammenführen aufeinanderfolgender Webhooks desselben Absenders zu einer einzelnen Agentenrunde. Gruppenchats bleiben nach Nachricht geschlüsselt, sodass die Rundenstruktur mit mehreren Benutzern erhalten bleibt.

{
  channels: {
    bluebubbles: {
      coalesceSameSenderDms: true, // opt in (default: false)
    },
  },
}

{
  messages: {
    inbound: {
      byChannel: {
        // 2500 ms works for most setups; raise to 4000 ms if your Mac is slow
        // or under memory pressure (observed gap can stretch past 2 s then).
        bluebubbles: 2500,
      },
    },
  },
}

# Szenarien und was der Agent sieht

# Fehlerbehebung für Zusammenführung aufgeteilter Sendungen

Wenn das Flag aktiviert ist und aufgeteilte Sendungen weiterhin als zwei Runden ankommen, prüfen Sie jede Ebene:

grep coalesceSameSenderDms ~/.openclaw/openclaw.json

grep -E "Dispatching event to webhook" main.log | tail -20

# Block-Streaming

Steuern Sie, ob Antworten als einzelne Nachricht gesendet oder in Blöcken gestreamt werden:

{
  channels: {
    bluebubbles: {
      blockStreaming: true, // enable block streaming (off by default)
    },
  },
}

# Medien + Limits

• Eingehende Anhänge werden heruntergeladen und im Mediencache gespeichert.
• Medienlimit über channels.bluebubbles.mediaMaxMb für eingehende und ausgehende Medien (Standard: 8 MB).
• Ausgehender Text wird auf channels.bluebubbles.textChunkLimit aufgeteilt (Standard: 4000 Zeichen).

# Konfigurationsreferenz

Vollständige Konfiguration: Konfiguration

Zugehörige globale Optionen:

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

# Adressierung / Zustellziele

Bevorzugen Sie chat_guid für stabiles Routing:

• chat_guid:iMessage;-;+15555550123 (für Gruppen bevorzugt)
• chat_id:123
• chat_identifier:...
• Direkte Handles: +15555550123, [email protected]
  • Wenn ein direkter Handle keinen bestehenden DM-Chat hat, erstellt OpenClaw über POST /api/v1/chat/new einen. Dafür muss die BlueBubbles Private API aktiviert sein.

# iMessage- vs. SMS-Routing

Wenn derselbe Handle auf dem Mac sowohl einen iMessage- als auch einen SMS-Chat hat (zum Beispiel eine Telefonnummer, die für iMessage registriert ist, aber auch Fallbacks mit grüner Sprechblase empfangen hat), bevorzugt OpenClaw den iMessage-Chat und stuft niemals stillschweigend auf SMS zurück. Um den SMS-Chat zu erzwingen, verwenden Sie ein explizites sms:-Zielpräfix (zum Beispiel sms:+15555550123). Handles ohne passenden iMessage-Chat senden weiterhin über den Chat, den BlueBubbles meldet.

# Sicherheit

• Webhook-Anfragen werden authentifiziert, indem guid/password-Query-Parameter oder -Header mit channels.bluebubbles.password verglichen werden.
• Halten Sie das API-Passwort und den Webhook-Endpunkt geheim (behandeln Sie sie wie Zugangsdaten).
• Für die BlueBubbles-Webhook-Authentifizierung gibt es keine localhost-Umgehung. Wenn Sie Webhook-Datenverkehr proxien, behalten Sie das BlueBubbles-Passwort End-to-End in der Anfrage. gateway.trustedProxies ersetzt hier nicht channels.bluebubbles.password. Siehe Gateway-Sicherheit.
• Aktivieren Sie HTTPS + Firewall-Regeln auf dem BlueBubbles-Server, wenn Sie ihn außerhalb Ihres LAN bereitstellen.

# Fehlerbehebung

• Wenn Tipp-/Leseereignisse nicht mehr funktionieren, prüfen Sie die BlueBubbles-Webhook-Protokolle und verifizieren Sie, dass der Gateway-Pfad channels.bluebubbles.webhookPath entspricht.
• Pairing-Codes laufen nach einer Stunde ab; verwenden Sie openclaw pairing list bluebubbles und openclaw pairing approve bluebubbles <code>.
• Reaktionen erfordern die BlueBubbles Private API (POST /api/v1/message/react); stellen Sie sicher, dass die Serverversion sie bereitstellt.
• Bearbeiten/Zurückrufen erfordert macOS 13+ und eine kompatible BlueBubbles-Serverversion. Unter macOS 26 (Tahoe) ist Bearbeiten derzeit aufgrund von Änderungen an der Private API defekt.
• Aktualisierungen von Gruppensymbolen können unter macOS 26 (Tahoe) unzuverlässig sein: Die API kann Erfolg zurückgeben, aber das neue Symbol wird nicht synchronisiert.
• OpenClaw blendet bekannte defekte Aktionen basierend auf der macOS-Version des BlueBubbles-Servers automatisch aus. Wenn Bearbeiten unter macOS 26 (Tahoe) weiterhin erscheint, deaktivieren Sie es manuell mit channels.bluebubbles.actions.edit=false.
• coalesceSameSenderDms ist aktiviert, aber Split-Sends (z. B. Dump + URL) kommen weiterhin als zwei Turns an: siehe die Fehlerbehebungs-Checkliste zur Split-Send-Zusammenführung - häufige Ursachen sind ein zu enges Debounce-Fenster, Session-Log-Zeitstempel, die fälschlich als Webhook-Ankunft gelesen werden, oder ein Senden mit Antwortzitat (das replyToBody verwendet, nicht einen zweiten Webhook).
• Für Status-/Health-Informationen: openclaw status --all oder openclaw status --deep.

Eine allgemeine Referenz zum Kanal-Workflow finden Sie unter Kanäle und im Leitfaden Plugins.

# Zugehörig

• Kanal-Routing - Session-Routing für Nachrichten
• Kanäle: Übersicht - alle unterstützten Kanäle
• Gruppen - Gruppenchatverhalten und Mention-Gating
• Pairing - DM-Authentifizierung und Pairing-Ablauf
• Sicherheit - Zugriffsmodell und Härtung