OpenClaw mit BlueBubbles für iMessage verbinden

Integriertes Plugin

Aktuelle OpenClaw-Releases enthalten BlueBubbles bereits als festen Bestandteil, daher ist bei normalen Paket-Builds kein separater openclaw plugins install-Schritt erforderlich.

Übersicht der BlueBubbles-Funktionen

Diese Komponente läuft auf macOS über die BlueBubbles-Hilfs-App (bluebubbles.app). Empfohlen und getestet ist macOS Sequoia (15); macOS Tahoe (26) funktioniert ebenfalls, wobei die Bearbeitungsfunktion auf Tahoe derzeit fehlerhaft ist und Aktualisierungen von Gruppen-Icons zwar als erfolgreich gemeldet werden, aber unter Umständen nicht synchronisieren. OpenClaw kommuniziert über die REST API (GET /api/v1/ping, POST /message/text, POST /chat/:id/*) mit dem Server. Eingehende Nachrichten werden über webhook-Aufrufe empfangen, während ausgehende Antworten, Tipp-Indikatoren, Lesebestätigungen und Tapbacks als REST-Aufrufe ausgeführt werden. Anhänge und Sticker werden als eingehende Medien verarbeitet und dem Agenten nach Möglichkeit zur Verfügung gestellt. Das Pairing und die Allowlist funktionieren wie bei anderen Kanälen (/channels/pairing etc.) über channels.bluebubbles.allowFrom und Pairing-Codes. Reaktionen werden wie bei Slack oder Telegram als Systemereignisse angezeigt, damit Agenten diese vor einer Antwort “erwähnen” können. Zu den erweiterten Funktionen gehören Bearbeiten, Zurückziehen, Antwort-Threading, Nachrichteneffekte und Gruppenverwaltung.

Quick Start für BlueBubbles

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

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

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

Leite die BlueBubbles webhook-Anfragen an dein Gateway weiter (Beispiel: https://your-gateway-host:3000/bluebubbles-webhook?password=<password>).
Starte das Gateway; es registriert den webhook-Handler und beginnt mit dem Pairing.

Sicherheitshinweis:

Setze immer ein webhook-Passwort.
Die webhook-Authentifizierung ist zwingend erforderlich. OpenClaw weist 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 der Loopback- oder Proxy-Topologie.
Die Passwort-Authentifizierung wird geprüft, bevor die vollständigen webhook-Bodys gelesen oder geparst werden.

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

Einige macOS-VMs oder Always-on-Setups können dazu führen, dass die Messages.app in den “Leerlauf” geht (eingehende Ereignisse stoppen, bis die App geöffnet oder in den Vordergrund geholt wird). Eine einfache Lösung besteht darin, Messages alle 5 Minuten mittels AppleScript und LaunchAgent zu “stupsen”.

1) Speichere das AppleScript

Speichere dies unter:

~/Scripts/poke-messages.scpt

Beispiel-Skript (nicht-interaktiv; stiehlt nicht den 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) Installiere einen LaunchAgent

Speichere dies unter:

~/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-Automatisierungs-Abfragen auslösen (osascript → Messages). Bestätige diese in derselben Benutzersitzung, in der der LaunchAgent ausgeführt wird.

Lade den Agenten:

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

AI Setup Assistant

Onboarding

OpenClaw bietet ein interaktives Onboarding, mit dem du BlueBubbles schnell und einfach konfigurieren kannst:

openclaw onboard

Der Assistent fragt dich nach den folgenden Informationen:

Server URL (erforderlich): Die Adresse deines BlueBubbles-Servers (z. B. http://192.168.1.100:1234).
Password (erforderlich): Das API-Passwort aus deinen BlueBubbles-Servereinstellungen.
Webhook path (optional): Standardmäßig auf /bluebubbles-webhook gesetzt.
DM policy: Wähle zwischen pairing, allowlist, open oder disabled.
Allow list: Definiere Telefonnummern, E-Mails oder Chat-Ziele.

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

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

Zugriffskontrolle (Direktnachrichten + Gruppen)

Die Verwaltung von Berechtigungen für Direktnachrichten und Gruppen erfolgt über spezifische Richtlinien, um den Zugriff auf dein System zu steuern.

Direktnachrichten:

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

Gruppen:

channels.bluebubbles.groupPolicy = open | allowlist | disabled (Standard ist allowlist).
channels.bluebubbles.groupAllowFrom steuert, wer in Gruppen agieren darf, wenn allowlist aktiviert ist.

Anreicherung von Kontaktnamen (macOS, optional)

BlueBubbles-Gruppen-webhooks enthalten oft nur die rohen Teilnehmeradressen. Wenn du möchtest, dass der GroupMembers-Kontext lokale Kontaktnamen anzeigt, kannst du die Anreicherung auf macOS aktivieren:

channels.bluebubbles.enrichGroupParticipantsFromContacts = true aktiviert die Suche. Der Standardwert ist false.
Suchvorgänge werden erst ausgeführt, nachdem der Gruppenzugriff, die Befehlsautorisierung und das Erwähnungs-Gating die Nachricht zugelassen haben.
Nur unbenannte Telefon-Teilnehmer werden angereichert.
Rohe Telefonnummern bleiben als Fallback erhalten, wenn kein lokaler Treffer gefunden wird.

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

Erwähnungs-Gating (Gruppen)

BlueBubbles unterstützt ein Erwähnungs-Gating für Gruppenchats, das dem Verhalten von iMessage oder WhatsApp entspricht:

Nutzt agents.list[].groupChat.mentionPatterns (oder messages.groupChat.mentionPatterns), um Erwähnungen zu erkennen.
Wenn requireMention für eine Gruppe aktiviert ist, antwortet der Agent nur, wenn er erwähnt wird.
Steuerbefehle von autorisierten Absendern umgehen das Erwähnungs-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 eine Autorisierung.
Verwendet allowFrom und groupAllowFrom, um die Befehlsautorisierung zu bestimmen.
Autorisierte Absender können Steuerbefehle auch ohne Erwähnung in Gruppen ausführen.

ACP Konversationsbindungen

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

Schneller Operator-Ablauf:

Führe /acp spawn codex --bind here innerhalb der Direktnachricht oder des erlaubten Gruppenchats aus.
Zukünftige Nachrichten in dieser BlueBubbles-Konversation werden an die erstellte ACP-Sitzung weitergeleitet.
/new und /reset setzen dieselbe gebundene ACP-Sitzung zurück.
/acp close schließt die ACP-Sitzung und entfernt die Bindung.

Konfigurierte persistente Bindungen werden ebenfalls über bindings[]-Einträge auf oberster Ebene mit type: "acp" und match.channel: "bluebubbles" unterstützt.

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

Normalisierter DM-Handle wie +15555550123 oder user@example.com
chat_id:<id>
chat_guid:<guid>
chat_identifier:<identifier>

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

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" },
    },
  ],
}

Weitere Informationen findest du unter ACP Agents.

Tippen + Lesebestätigungen

Die Kommunikation wird durch Statusanzeigen ergänzt, um den Benutzerfluss natürlicher zu gestalten.

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

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

Erweiterte Aktionen

OpenClaw unterstützt erweiterte Nachrichtenaktionen für BlueBubbles, sobald du diese in deiner Konfiguration aktiviert hast. Hier ist ein Beispiel, wie du die verschiedenen Funktionen freischaltest:

{
  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
      },
    },
  },
}

Die folgenden Aktionen stehen dir zur Verfügung:

react: Füge Tapback-Reaktionen hinzu oder entferne sie (messageId, emoji, remove).
edit: Bearbeite eine bereits gesendete Nachricht (messageId, text).
unsend: Mache das Senden einer Nachricht rückgängig (messageId).
reply: Antworte direkt auf eine bestimmte Nachricht (messageId, text, to).
sendWithEffect: Sende eine Nachricht mit einem iMessage-Effekt (text, to, effectId).
renameGroup: Ändere den Namen eines Gruppenchats (chatGuid, displayName).
setGroupIcon: Lege ein Icon oder Foto für einen Gruppenchat fest (chatGuid, media) — auf macOS 26 Tahoe kann dies unzuverlässig sein (die API meldet Erfolg, aber das Icon wird nicht synchronisiert).
addParticipant: Füge jemanden zu einer Gruppe hinzu (chatGuid, address).
removeParticipant: Entferne jemanden aus einer Gruppe (chatGuid, address).
leaveGroup: Verlasse einen Gruppenchat (chatGuid).
upload-file: Sende Medien oder Dateien (to, buffer, filename, asVoice).
- Sprachnotizen: Setze asVoice: true bei einer MP3- oder CAF-Audiodatei, um sie als iMessage-Sprachnachricht zu versenden. BlueBubbles konvertiert MP3 automatisch in das CAF-Format, wenn du Sprachnotizen verschickst.
- Der Legacy-Alias sendAttachment funktioniert weiterhin, aber upload-file ist der offizielle Name der Aktion.

Nachrichten-IDs (kurz vs. voll)

OpenClaw verwendet manchmal kurze Nachrichten-IDs (z. B. 1, 2), um Tokens zu sparen.

MessageSid / ReplyToId können kurze IDs sein.
MessageSidFull / ReplyToIdFull enthalten die vollständigen IDs des Anbieters.
Kurze IDs existieren nur im Arbeitsspeicher; sie können nach einem Neustart oder durch das Leeren des Caches ungültig werden.
Die Aktionen akzeptieren sowohl kurze als auch volle messageId-Werte, aber kurze IDs führen zu einem Fehler, falls sie nicht mehr verfügbar sind.

Verwende für dauerhafte Automatisierungen und die Speicherung immer die vollständigen IDs:

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

Weitere Informationen zu Vorlagenvariablen findest du unter Konfiguration.

Block-Streaming

Du kannst steuern, ob Antworten als einzelne Nachricht oder in Blöcken gestreamt werden sollen, um die Übertragung zu optimieren:

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

Medien und Limits

Eingehende Anhänge werden automatisch heruntergeladen und im Medien-Cache gespeichert. OpenClaw verwaltet diese Daten effizient, um die Performance deines Gateways zu optimieren.

Eingehende Anhänge werden heruntergeladen und im Medien-Cache gespeichert.
Das Medienlimit wird über channels.bluebubbles.mediaMaxMb für ein- und ausgehende Medien gesteuert (Standard: 8 MB).
Ausgehender Text wird gemäß channels.bluebubbles.textChunkLimit in Stücke unterteilt (Standard: 4000 Zeichen).

Konfigurationsreferenz

Die vollständige Konfiguration findest du in der Konfiguration. Hier sind die spezifischen Optionen für den BlueBubbles-Provider:

channels.bluebubbles.enabled: Aktiviert oder deaktiviert den Kanal.
channels.bluebubbles.serverUrl: Die Basis-URL der BlueBubbles REST API.
channels.bluebubbles.password: Das API-Passwort.
channels.bluebubbles.webhookPath: Der Pfad für den webhook-Endpunkt (Standard: /bluebubbles-webhook).
channels.bluebubbles.dmPolicy: Legt die Richtlinie für Direktnachrichten fest: pairing | allowlist | open | disabled (Standard: pairing).
channels.bluebubbles.allowFrom: Die Whitelist für Direktnachrichten (Handles, E-Mails, E.164-Nummern, chat_id:*, chat_guid:*).
channels.bluebubbles.groupPolicy: Richtlinie für Gruppen: open | allowlist | disabled (Standard: allowlist).
channels.bluebubbles.groupAllowFrom: Whitelist für Absender in Gruppen.
channels.bluebubbles.enrichGroupParticipantsFromContacts: Auf macOS kannst du optional unbenannte Gruppenteilnehmer nach der Filterung aus den lokalen Kontakten anreichern. Standard: false.
channels.bluebubbles.groups: Gruppenspezifische Konfiguration (z. B. requireMention).
channels.bluebubbles.sendReadReceipts: Sendet Lesebestätigungen (Standard: true).
channels.bluebubbles.blockStreaming: Aktiviert das Block-Streaming (Standard: false; erforderlich für Streaming-Antworten).
channels.bluebubbles.textChunkLimit: Größe der ausgehenden Textblöcke in Zeichen (Standard: 4000).
channels.bluebubbles.sendTimeoutMs: Timeout pro Anfrage in ms für ausgehende Textnachrichten via /api/v1/message/text (Standard: 30000). Erhöhe diesen Wert bei macOS 26-Setups, bei denen Private API iMessage-Sendevorgänge im iMessage-Framework länger als 60 Sekunden dauern können; nutze beispielsweise 45000 oder 60000. Probes, Chat-Lookups, Reaktionen, Bearbeitungen und Gesundheitsprüfungen nutzen weiterhin den kürzeren Standard von 10s. Eine konto-spezifische Überschreibung ist über channels.bluebubbles.accounts.<accountId>.sendTimeoutMs möglich.
channels.bluebubbles.chunkMode: length (Standard) teilt nur bei Überschreitung des textChunkLimit; newline teilt bei Leerzeilen (Absatzgrenzen) vor der Längenbegrenzung.
channels.bluebubbles.mediaMaxMb: Limit für ein-/ausgehende Medien in MB (Standard: 8).
channels.bluebubbles.mediaLocalRoots: Explizite Whitelist absoluter lokaler Verzeichnisse für ausgehende lokale Medienpfade. Lokale Pfade sind standardmäßig gesperrt, sofern dies nicht konfiguriert ist. Konto-spezifische Überschreibung via channels.bluebubbles.accounts.<accountId>.mediaLocalRoots.
channels.bluebubbles.historyLimit: Maximale Anzahl an Gruppennachrichten für den Kontext (0 deaktiviert dies).
channels.bluebubbles.dmHistoryLimit: Limit für den Verlauf von Direktnachrichten.
channels.bluebubbles.actions: Aktiviert oder deaktiviert spezifische Aktionen.
channels.bluebubbles.accounts: Konfiguration für mehrere Konten.

Zugehörige globale Optionen:

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

AI Setup Assistant

Adressierung und Zustellungsziele

Verwende am besten die chat_guid für ein stabiles Routing deiner Nachrichten. Diese stellt sicher, dass deine Anfragen immer das richtige Ziel erreichen.

chat_guid:iMessage;-;+15555550123 (bevorzugt für Gruppen)
chat_id:123
chat_identifier:...
Direkte Handles: +15555550123, user@example.com
- Falls für ein direktes Handle noch kein DM-Chat existiert, erstellt OpenClaw automatisch einen über POST /api/v1/chat/new. Hierfür muss die BlueBubbles Private API aktiviert sein.

Sicherheit

Die Absicherung deiner webhook-Anfragen ist entscheidend, um unbefugten Zugriff auf deine Kommunikation zu verhindern. Behandle diese Zugangsdaten immer mit der gleichen Sorgfalt wie deine Passwörter.

Webhook-Anfragen werden authentifiziert, indem die guid oder das password in den Query-Parametern oder Headern mit channels.bluebubbles.password abgeglichen werden.
Halte das API-Passwort und den webhook-Endpunkt unbedingt geheim.
Es gibt keinen Localhost-Bypass für die webhook-Authentifizierung von BlueBubbles. Wenn du den webhook-Datenverkehr über einen Gateway weiterleitest, muss das BlueBubbles-Passwort durchgehend in der Anfrage enthalten sein. gateway.trustedProxies ersetzt hier nicht channels.bluebubbles.password. Weitere Informationen findest du unter Gateway security.
Aktiviere HTTPS und richte Firewall-Regeln auf dem BlueBubbles-Server ein, falls du diesen außerhalb deines LANs erreichbar machst.

Fehlerbehebung bei OpenClaw

Wenn du Probleme mit der Verbindung oder der Synchronisation hast, helfen dir diese Schritte, um die Ursache schnell zu finden. Überprüfe bei Unregelmäßigkeiten zuerst die webhook-Logs und den Status deiner Verbindung.

Wenn Tipp- oder Lesebestätigungen nicht mehr funktionieren, prüfe die webhook-Logs von BlueBubbles und vergewissere dich, dass der Gateway-Pfad mit channels.bluebubbles.webhookPath übereinstimmt.
Pairing-Codes sind nur eine Stunde lang gültig; verwende openclaw pairing list bluebubbles und openclaw pairing approve bluebubbles <code>, um das Pairing abzuschließen.
Reaktionen erfordern die private API von BlueBubbles (POST /api/v1/message/react); stelle sicher, dass deine Server-Version diese unterstützt.
Bearbeiten und Zurückziehen von Nachrichten erfordern macOS 13+ sowie eine kompatible BlueBubbles-Server-Version. Unter macOS 26 (Tahoe) ist die Bearbeitungsfunktion aufgrund von Änderungen an der private API aktuell fehlerhaft.
Aktualisierungen von Gruppen-Icons können unter macOS 26 (Tahoe) unzuverlässig sein: Die API meldet zwar Erfolg, das neue Icon wird jedoch nicht synchronisiert.
OpenClaw blendet bekannte, fehlerhafte Aktionen basierend auf der macOS-Version des BlueBubbles-Servers automatisch aus. Falls die Bearbeiten-Funktion unter macOS 26 (Tahoe) weiterhin angezeigt wird, deaktiviere sie manuell mit channels.bluebubbles.actions.edit=false.
Für Status- oder Gesundheitsinformationen nutze openclaw status —all oder openclaw status —deep.

Für allgemeine Informationen zum Workflow der Kanäle, siehe Channels und den Plugins Leitfaden.

Noch festgefahren?

Wenn diese Seite nicht hilft, frage OpenClaw Expert nach Schritt-fuer-Schritt-Loesungen.

OpenClaw mit BlueBubbles für iMessage verbinden

Integriertes Plugin

Übersicht der BlueBubbles-Funktionen

Quick Start für BlueBubbles

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

1) Speichere das AppleScript

2) Installiere einen LaunchAgent

Onboarding

Zugriffskontrolle (Direktnachrichten + Gruppen)

Anreicherung von Kontaktnamen (macOS, optional)

Erwähnungs-Gating (Gruppen)

Befehls-Gating

ACP Konversationsbindungen

Tippen + Lesebestätigungen

Erweiterte Aktionen

Nachrichten-IDs (kurz vs. voll)

Block-Streaming

Medien und Limits

Konfigurationsreferenz

Adressierung und Zustellungsziele

Sicherheit

Fehlerbehebung bei OpenClaw

Verwandte Themen

Noch festgefahren?