BlueBubbles

Status: dołączony starszy Plugin, który komunikuje się z serwerem BlueBubbles dla macOS przez HTTP. Istniejące konfiguracje BlueBubbles nadal działają, ale nowe wdrożenia OpenClaw iMessage powinny preferować natywny Plugin iMessage, gdy jego wymagania pasują do Twojego hosta.

# Omówienie

• Działa na macOS przez aplikację pomocniczą BlueBubbles (bluebubbles.app).
• Starsza opcja awaryjna dla instalacji, które już polegają na identyfikatorach kanałów BlueBubbles, stanie webhooków, celach grupowych, dostarczaniu cron lub routingu obszarów roboczych.
• Zalecane/przetestowane: macOS Sequoia (15). macOS Tahoe (26) działa; edycja jest obecnie zepsuta na Tahoe, a aktualizacje ikon grup mogą zgłaszać powodzenie, ale się nie synchronizować.
• OpenClaw komunikuje się z nim przez jego REST API (GET /api/v1/ping, POST /message/text, POST /chat/:id/*).
• Wiadomości przychodzące docierają przez webhooki; odpowiedzi wychodzące, wskaźniki pisania, potwierdzenia odczytu i tapbacki są wywołaniami REST.
• Załączniki i naklejki są przetwarzane jako media przychodzące (i gdy to możliwe, udostępniane agentowi).
• Odpowiedzi Auto-TTS, które syntetyzują dźwięk MP3 lub CAF, są dostarczane jako dymki notatek głosowych iMessage zamiast zwykłych załączników plików.
• Parowanie/lista dozwolonych działa tak samo jak w innych kanałach (/channels/pairing itd.) z channels.bluebubbles.allowFrom + kodami parowania.
• Reakcje są udostępniane jako zdarzenia systemowe, tak jak w Slack/Telegram, aby agenci mogli o nich „wspomnieć” przed odpowiedzią.
• Funkcje zaawansowane: edycja, cofanie wysłania, wątki odpowiedzi, efekty wiadomości, zarządzanie grupami.

# Szybki start

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

# Utrzymywanie Messages.app przy życiu (konfiguracje VM / headless)

Niektóre konfiguracje macOS VM / zawsze włączone mogą doprowadzić do przejścia Messages.app w stan „bezczynności” (zdarzenia przychodzące zatrzymują się, dopóki aplikacja nie zostanie otwarta/przeniesiona na pierwszy plan). Prostym obejściem jest wybudzanie Messages co 5 minut za pomocą 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

# Wprowadzanie

BlueBubbles jest dostępny w interaktywnym wprowadzaniu:

openclaw onboard

Kreator pyta o:

Możesz też dodać BlueBubbles przez CLI:

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

# Kontrola dostępu (DM-y + grupy)

# Wzbogacanie nazw kontaktów (macOS, opcjonalnie)

Webhooki grup BlueBubbles często zawierają tylko surowe adresy uczestników. Jeśli chcesz, aby kontekst GroupMembers pokazywał zamiast tego lokalne nazwy kontaktów, możesz włączyć lokalne wzbogacanie z Kontaktów na macOS:

• channels.bluebubbles.enrichGroupParticipantsFromContacts = true włącza wyszukiwanie. Domyślnie: false.
• Wyszukiwania są uruchamiane dopiero po tym, jak dostęp do grupy, autoryzacja poleceń i bramkowanie wzmianek przepuszczą wiadomość.
• Wzbogacani są tylko nienazwani uczestnicy telefoniczni.
• Surowe numery telefonów pozostają opcją awaryjną, gdy nie znaleziono lokalnego dopasowania.

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

# Bramkowanie wzmianek (grupy)

BlueBubbles obsługuje bramkowanie wzmianek dla czatów grupowych, zgodnie z zachowaniem iMessage/WhatsApp:

• Używa agents.list[].groupChat.mentionPatterns (lub messages.groupChat.mentionPatterns) do wykrywania wzmianek.
• Gdy requireMention jest włączone dla grupy, agent odpowiada tylko po wzmiance.
• Polecenia kontrolne od autoryzowanych nadawców omijają bramkowanie wzmianek.

Konfiguracja dla grupy:

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

# Prompt systemowy dla grupy

Każdy wpis pod channels.bluebubbles.groups.* akceptuje opcjonalny ciąg systemPrompt. Wartość jest wstrzykiwana do promptu systemowego agenta przy każdej turze obsługującej wiadomość w tej grupie, dzięki czemu możesz ustawić personę lub reguły zachowania dla grupy bez edytowania promptów agenta:

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

Klucz odpowiada temu, co BlueBubbles zgłasza jako chatGuid / chatIdentifier / numeryczne chatId dla grupy, a wpis wieloznaczny "*" zapewnia ustawienie domyślne dla każdej grupy bez dokładnego dopasowania (ten sam wzorzec używany przez requireMention i zasady narzędzi dla grup). Dokładne dopasowania zawsze wygrywają z symbolem wieloznacznym. DM-y ignorują to pole; zamiast tego użyj dostosowania promptu na poziomie agenta lub konta.

# Przykład praktyczny: odpowiedzi w wątkach i reakcje tapback (Private API)

Przy włączonym BlueBubbles Private API wiadomości przychodzące docierają z krótkimi identyfikatorami wiadomości (na przykład [[reply_to:5]]), a agent może wywołać action=reply, aby wejść w wątek konkretnej wiadomości, albo action=react, aby dodać tapback. systemPrompt dla grupy to niezawodny sposób na utrzymanie wyboru właściwego narzędzia przez agenta:

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

Reakcje tapback i odpowiedzi w wątkach wymagają BlueBubbles Private API; zobacz Zaawansowane akcje i Identyfikatory wiadomości, aby poznać mechanikę leżącą u podstaw.

# Powiązania konwersacji ACP

Czaty BlueBubbles można przekształcić w trwałe obszary robocze ACP bez zmiany warstwy transportu.

Szybki przepływ operatora:

• Uruchom /acp spawn codex --bind here w DM-ie lub dozwolonym czacie grupowym.
• Przyszłe wiadomości w tej samej konwersacji BlueBubbles są kierowane do utworzonej sesji ACP.
• /new i /reset resetują tę samą powiązaną sesję ACP w miejscu.
• /acp close zamyka sesję ACP i usuwa powiązanie.

Obsługiwane są też skonfigurowane trwałe powiązania przez wpisy najwyższego poziomu bindings[] z type: "acp" i match.channel: "bluebubbles".

match.peer.id może używać dowolnej obsługiwanej formy celu BlueBubbles:

• znormalizowany uchwyt DM, taki jak +15555550123 lub [email protected]
• chat_id:<id>
• chat_guid:<guid>
• chat_identifier:<identifier>

Dla stabilnych powiązań grupowych preferuj chat_id:* lub chat_identifier:*.

Przykład:

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

Zobacz Agenci ACP, aby poznać wspólne zachowanie powiązań ACP.

# Wskaźniki pisania + potwierdzenia odczytu

• Wskaźniki pisania: Wysyłane automatycznie przed generowaniem odpowiedzi i w jego trakcie.
• Potwierdzenia odczytu: Kontrolowane przez channels.bluebubbles.sendReadReceipts (domyślnie: true).
• Wskaźniki pisania: OpenClaw wysyła zdarzenia rozpoczęcia pisania; BlueBubbles automatycznie czyści stan pisania przy wysłaniu lub po przekroczeniu limitu czasu (ręczne zatrzymanie przez DELETE jest zawodne).

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

# Zaawansowane akcje

BlueBubbles obsługuje zaawansowane akcje wiadomości, gdy są włączone w konfiguracji:

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

# Identyfikatory wiadomości (krótkie i pełne)

OpenClaw może pokazywać krótkie identyfikatory wiadomości (np. 1, 2), aby oszczędzać tokeny.

• MessageSid / ReplyToId mogą być krótkimi identyfikatorami.
• MessageSidFull / ReplyToIdFull zawierają pełne identyfikatory dostawcy.
• Krótkie identyfikatory są przechowywane w pamięci; mogą wygasnąć po restarcie lub usunięciu z pamięci podręcznej.
• Akcje akceptują krótki lub pełny messageId, ale krótkie identyfikatory zwrócą błąd, jeśli nie będą już dostępne.

Używaj pełnych identyfikatorów dla trwałych automatyzacji i przechowywania:

• Szablony: {{MessageSidFull}}, {{ReplyToIdFull}}
• Kontekst: MessageSidFull / ReplyToIdFull w przychodzących ładunkach

Zobacz Konfiguracja, aby poznać zmienne szablonów.

# Scalanie podzielonych wysyłek DM (polecenie + URL w jednej kompozycji)

Gdy użytkownik wpisze w iMessage polecenie razem z adresem URL - np. Dump https://example.com/article - Apple dzieli wysyłkę na dwa osobne dostarczenia webhooka:

1. Wiadomość tekstowa ("Dump").
2. Dymek podglądu URL ("https://...") z obrazami podglądu OG jako załącznikami.

Dwa webhooki docierają do OpenClaw w odstępie około 0,8-2,0 s w większości konfiguracji. Bez scalania agent otrzymuje samo polecenie w turze 1, odpowiada (często „wyślij mi URL”) i widzi URL dopiero w turze 2 - kiedy kontekst polecenia jest już utracony.

channels.bluebubbles.coalesceSameSenderDms włącza dla DM scalanie kolejnych webhooków od tego samego nadawcy w jedną turę agenta. Czaty grupowe nadal są kluczowane według wiadomości, dzięki czemu struktura tur wielu użytkowników pozostaje zachowana.

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

# Scenariusze i to, co widzi agent

# Rozwiązywanie problemów ze scalaniem podzielonych wysyłek

Jeśli flaga jest włączona, a podzielone wysyłki nadal docierają jako dwie tury, sprawdź każdą warstwę:

grep coalesceSameSenderDms ~/.openclaw/openclaw.json

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

# Przesyłanie blokowe

Kontroluj, czy odpowiedzi są wysyłane jako jedna wiadomość, czy strumieniowane w blokach:

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

# Multimedia + limity

• Załączniki przychodzące są pobierane i przechowywane w pamięci podręcznej multimediów.
• Limit multimediów przez channels.bluebubbles.mediaMaxMb dla multimediów przychodzących i wychodzących (domyślnie: 8 MB).
• Tekst wychodzący jest dzielony na fragmenty zgodnie z channels.bluebubbles.textChunkLimit (domyślnie: 4000 znaków).

# Odwołanie do konfiguracji

Pełna konfiguracja: Konfiguracja

Powiązane opcje globalne:

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

# Adresowanie / cele dostarczania

Preferuj chat_guid dla stabilnego routingu:

• chat_guid:iMessage;-;+15555550123 (preferowane dla grup)
• chat_id:123
• chat_identifier:...
• Bezpośrednie uchwyty: +15555550123, [email protected]
  • Jeśli bezpośredni uchwyt nie ma istniejącego czatu DM, OpenClaw utworzy go przez POST /api/v1/chat/new. Wymaga to włączenia BlueBubbles Private API.

# Routing iMessage a SMS

Gdy ten sam uchwyt ma na Macu zarówno czat iMessage, jak i SMS (na przykład numer telefonu zarejestrowany w iMessage, który otrzymywał także awaryjne wiadomości z zielonym dymkiem), OpenClaw preferuje czat iMessage i nigdy po cichu nie obniża trasy do SMS. Aby wymusić czat SMS, użyj jawnego prefiksu celu sms: (na przykład sms:+15555550123). Uchwyty bez pasującego czatu iMessage nadal wysyłają przez dowolny czat zgłoszony przez BlueBubbles.

# Bezpieczeństwo

• Żądania Webhook są uwierzytelniane przez porównanie parametrów zapytania lub nagłówków guid/password z channels.bluebubbles.password.
• Zachowaj hasło API i punkt końcowy Webhook w tajemnicy (traktuj je jak dane uwierzytelniające).
• Nie ma obejścia localhost dla uwierzytelniania Webhook BlueBubbles. Jeśli pośredniczysz w ruchu Webhook, zachowaj hasło BlueBubbles w żądaniu end-to-end. gateway.trustedProxies nie zastępuje tutaj channels.bluebubbles.password. Zobacz Bezpieczeństwo Gateway.
• Włącz HTTPS i reguły zapory na serwerze BlueBubbles, jeśli wystawiasz go poza swoją sieć LAN.

# Rozwiązywanie problemów

• Jeśli zdarzenia pisania/odczytu przestaną działać, sprawdź logi Webhook BlueBubbles i zweryfikuj, czy ścieżka Gateway odpowiada channels.bluebubbles.webhookPath.
• Kody parowania wygasają po godzinie; użyj openclaw pairing list bluebubbles i openclaw pairing approve bluebubbles <code>.
• Reakcje wymagają prywatnego API BlueBubbles (POST /api/v1/message/react); upewnij się, że wersja serwera je udostępnia.
• Edycja/cofnięcie wysłania wymaga macOS 13+ i zgodnej wersji serwera BlueBubbles. W macOS 26 (Tahoe) edycja obecnie nie działa z powodu zmian w private API.
• Aktualizacje ikon grup mogą być zawodne w macOS 26 (Tahoe): API może zwrócić sukces, ale nowa ikona się nie zsynchronizuje.
• OpenClaw automatycznie ukrywa znane niedziałające akcje na podstawie wersji macOS serwera BlueBubbles. Jeśli edycja nadal pojawia się w macOS 26 (Tahoe), wyłącz ją ręcznie za pomocą channels.bluebubbles.actions.edit=false.
• coalesceSameSenderDms jest włączone, ale rozdzielone wysyłki (np. Dump + URL) nadal docierają jako dwie tury: zobacz listę kontrolną rozwiązywania problemów ze scalaniem rozdzielonych wysyłek - typowe przyczyny to zbyt krótkie okno debounce, znaczniki czasu logu sesji błędnie odczytane jako czas dotarcia Webhook albo wysłanie cytatu odpowiedzi (które używa replyToBody, a nie drugiego Webhooka).
• Informacje o statusie/kondycji: openclaw status --all lub openclaw status --deep.

Ogólne informacje o przepływie pracy kanałów znajdziesz w przewodniku Kanały oraz Plugins.

# Powiązane

• Routing kanałów - routing sesji dla wiadomości
• Przegląd kanałów - wszystkie obsługiwane kanały
• Grupy - zachowanie czatu grupowego i kontrola wzmianek
• Parowanie - uwierzytelnianie DM i przepływ parowania
• Bezpieczeństwo - model dostępu i utwardzanie