BlueBubbles (macOS REST)

Status: dolaczony plugin komunikujacy sie z serwerem BlueBubbles macOS przez HTTP. Zalecany do integracji iMessage dzieki bogatszemu API i latwiejszej konfiguracji w porownaniu z przestarzalym kanalem imsg.

Przeglad

  • Dziala na macOS przez aplikacje pomocnicza BlueBubbles (bluebubbles.app).
  • Zalecane/przetestowane: macOS Sequoia (15). macOS Tahoe (26) dziala; edycja jest obecnie zepsuta na Tahoe, a aktualizacje ikon grup moga raportowac sukces, ale sie nie synchronizowac.
  • OpenClaw komunikuje sie z nim przez REST API (GET /api/v1/ping, POST /message/text, POST /chat/:id/*).
  • Wiadomosci przychodzace docieraja przez webhooki; odpowiedzi wychodzace, wskazniki pisania, potwierdzenia odczytu i tapbacki to wywolania REST.
  • Zalaczniki i naklejki sa pobierane jako media przychodzace (i udostepniane agentowi gdy to mozliwe).
  • Parowanie/lista dozwolonych dziala tak samo jak inne kanaly (/channels/pairing itp.) z channels.bluebubbles.allowFrom + kodami parowania.
  • Reakcje sa wyswietlane jako zdarzenia systemowe tak jak Slack/Telegram, wiec agenci moga je “wspomniec” przed odpowiedzia.
  • Zaawansowane funkcje: edycja, cofniecie wyslania, watkowanie odpowiedzi, efekty wiadomosci, zarzadzanie grupami.

Szybki start

  1. Zainstaluj serwer BlueBubbles na swoim Macu (postepuj zgodnie z instrukcjami na bluebubbles.app/install).

  2. W konfiguracji BlueBubbles wlacz web API i ustaw haslo.

  3. Uruchom openclaw onboard i wybierz BlueBubbles, lub skonfiguruj recznie:

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

  4. Skieruj webhooki BlueBubbles na gateway (przyklad: https://your-gateway-host:3000/bluebubbles-webhook?password=<password>).

  5. Uruchom gateway; zarejestruje handler webhooka i rozpocznie parowanie.

Uwaga bezpieczenstwa:

  • Zawsze ustaw haslo webhooka.
  • Uwierzytelnianie webhooka jest zawsze wymagane. OpenClaw odrzuca zadania webhooka BlueBubbles, chyba ze zawieraja haslo/guid pasujace do channels.bluebubbles.password (np. ?password=<password> lub x-password), niezaleznie od topologii loopback/proxy.
  • Uwierzytelnianie haslem jest sprawdzane przed odczytaniem/parsowaniem pelnych cial webhooka.

Utrzymywanie Messages.app przy zyciu (VM / konfiguracje bezgraficzne)

Niektore konfiguracje macOS VM / always-on moga skonczyc sie z Messages.app przechodzacym w stan “idle” (zdarzenia przychodzace zatrzymuja sie do momentu otwarcia/wysuniecia aplikacji na pierwszy plan). Prostym obejsciem jest pobudzanie Messages co 5 minut za pomoca AppleScript + LaunchAgent.

1) Zapisz AppleScript

Zapisz jako:

  • ~/Scripts/poke-messages.scpt

Przykladowy skrypt (nieinteraktywny; nie kradnie fokusu):

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) Zainstaluj LaunchAgent

Zapisz jako:

  • ~/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>

Uwagi:

  • Uruchamia sie co 300 sekund i przy logowaniu.
  • Pierwsze uruchomienie moze wyzwolic monity Automatyzacji macOS (osascript -> Messages). Zatwierdz je w tej samej sesji uzytkownika, ktora uruchamia LaunchAgent.

Zaladuj:

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

Onboarding

BlueBubbles jest dostepny w interaktywnym kreatorze konfiguracji:

openclaw onboard

Kreator pyta o:

  • URL serwera (wymagany): adres serwera BlueBubbles (np. http://192.168.1.100:1234)
  • Haslo (wymagane): haslo API z ustawien serwera BlueBubbles
  • Sciezka webhooka (opcjonalna): domyslnie /bluebubbles-webhook
  • Polityka DM: parowanie, lista dozwolonych, otwarta lub wylaczona
  • Lista dozwolonych: numery telefonow, emaile lub cele czatu

Mozesz rowniez dodac BlueBubbles przez CLI:

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

Kontrola dostepu (DM + grupy)

DM:

  • Domyslnie: channels.bluebubbles.dmPolicy = "pairing".
  • Nieznani nadawcy otrzymuja kod parowania; wiadomosci sa ignorowane do momentu zatwierdzenia (kody wygasaja po 1 godzinie).
  • Zatwierdzanie przez:
    • openclaw pairing list bluebubbles
    • openclaw pairing approve bluebubbles <CODE>
  • Parowanie to domyslna wymiana tokenow. Szczegoly: Parowanie

Grupy:

  • channels.bluebubbles.groupPolicy = open | allowlist | disabled (domyslnie: allowlist).
  • channels.bluebubbles.groupAllowFrom kontroluje, kto moze wyzwalac w grupach gdy allowlist jest ustawione.

Bramkowanie wzmiankami (grupy)

BlueBubbles obsluguje bramkowanie wzmiankami dla czatow grupowych, pasujace do zachowania iMessage/WhatsApp:

  • Uzywa agents.list[].groupChat.mentionPatterns (lub messages.groupChat.mentionPatterns) do wykrywania wzmianek.
  • Gdy requireMention jest wlaczone dla grupy, agent odpowiada tylko gdy wspomniano.
  • Polecenia sterujace od autoryzowanych nadawcow omijaja bramkowanie wzmiankami.

Konfiguracja per grupe:

{
  channels: {
    bluebubbles: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: {
        "*": { requireMention: true }, // domyslne dla wszystkich grup
        "iMessage;-;chat123": { requireMention: false }, // nadpisanie dla konkretnej grupy
      },
    },
  },
}

Bramkowanie polecen

  • Polecenia sterujace (np. /config, /model) wymagaja autoryzacji.
  • Uzywa allowFrom i groupAllowFrom do okreslenia autoryzacji polecen.
  • Autoryzowani nadawcy moga uruchamiac polecenia sterujace nawet bez wzmianki w grupach.

Pisanie + potwierdzenia odczytu

  • Wskazniki pisania: Wysylane automatycznie przed i podczas generowania odpowiedzi.
  • Potwierdzenia odczytu: Kontrolowane przez channels.bluebubbles.sendReadReceipts (domyslnie: true).
  • Wskazniki pisania: OpenClaw wysyla zdarzenia rozpoczecia pisania; BlueBubbles automatycznie czysci pisanie przy wyslaniu lub timeout (reczne zatrzymanie przez DELETE jest niewiarygodne).
{
  channels: {
    bluebubbles: {
      sendReadReceipts: false, // wylacz potwierdzenia odczytu
    },
  },
}

Zaawansowane akcje

BlueBubbles obsluguje zaawansowane akcje wiadomosci gdy wlaczone w konfiguracji:

{
  channels: {
    bluebubbles: {
      actions: {
        reactions: true, // tapbacki (domyslnie: true)
        edit: true, // edycja wyslanych wiadomosci (macOS 13+, zepsute na macOS 26 Tahoe)
        unsend: true, // cofniecie wyslania wiadomosci (macOS 13+)
        reply: true, // watkowanie odpowiedzi po GUID wiadomosci
        sendWithEffect: true, // efekty wiadomosci (slam, loud itp.)
        renameGroup: true, // zmiana nazwy czatow grupowych
        setGroupIcon: true, // ustawienie ikony/zdjecia czatu grupowego (niestabilne na macOS 26 Tahoe)
        addParticipant: true, // dodawanie uczestnikow do grup
        removeParticipant: true, // usuwanie uczestnikow z grup
        leaveGroup: true, // opuszczanie czatow grupowych
        sendAttachment: true, // wysylanie zalacznikow/mediow
      },
    },
  },
}

Dostepne akcje:

  • react: Dodawanie/usuwanie reakcji tapback (messageId, emoji, remove)
  • edit: Edycja wyslanej wiadomosci (messageId, text)
  • unsend: Cofniecie wyslania wiadomosci (messageId)
  • reply: Odpowiedz na konkretna wiadomosc (messageId, text, to)
  • sendWithEffect: Wyslanie z efektem iMessage (text, to, effectId)
  • renameGroup: Zmiana nazwy czatu grupowego (chatGuid, displayName)
  • setGroupIcon: Ustawienie ikony/zdjecia czatu grupowego (chatGuid, media) — niestabilne na macOS 26 Tahoe (API moze zwrocic sukces, ale ikona sie nie synchronizuje).
  • addParticipant: Dodanie kogos do grupy (chatGuid, address)
  • removeParticipant: Usuniecie kogos z grupy (chatGuid, address)
  • leaveGroup: Opuszczenie czatu grupowego (chatGuid)
  • sendAttachment: Wyslanie mediow/plikow (to, buffer, filename, asVoice)
    • Notatki glosowe: ustaw asVoice: true z dzwiekiem MP3 lub CAF aby wyslac jako wiadomosc glosowa iMessage. BlueBubbles konwertuje MP3 na CAF podczas wysylania notatek glosowych.

ID wiadomosci (krotkie vs pelne)

OpenClaw moze wyswietlac krotkie ID wiadomosci (np. 1, 2) aby oszczedzic tokeny.

  • MessageSid / ReplyToId moga byc krotkimi ID.
  • MessageSidFull / ReplyToIdFull zawieraja pelne ID dostawcy.
  • Krotkie ID sa w pamieci; moga wygasnac po restarcie lub eksmisji z cache.
  • Akcje akceptuja krotkie lub pelne messageId, ale krotkie ID zwroca blad jesli nie sa juz dostepne.

Uzyj pelnych ID dla trwalych automatyzacji i przechowywania:

  • Szablony: {{MessageSidFull}}, {{ReplyToIdFull}}
  • Kontekst: MessageSidFull / ReplyToIdFull w payloadach przychodzacych

Zobacz Konfiguracja dla zmiennych szablonowych.

Strumieniowanie blokowe

Kontroluj, czy odpowiedzi sa wysylane jako jedna wiadomosc czy strumieniowane w blokach:

{
  channels: {
    bluebubbles: {
      blockStreaming: true, // wlacz strumieniowanie blokowe (domyslnie wylaczone)
    },
  },
}

Media + limity

  • Przychodzace zalaczniki sa pobierane i przechowywane w cache mediow.
  • Limit mediow przez channels.bluebubbles.mediaMaxMb dla mediow przychodzacych i wychodzacych (domyslnie: 8 MB).
  • Tekst wychodzacy jest dzielony na kawalki do channels.bluebubbles.textChunkLimit (domyslnie: 4000 znakow).

Referencja konfiguracji

Pelna konfiguracja: Konfiguracja

Opcje dostawcy:

  • channels.bluebubbles.enabled: Wlaczenie/wylaczenie kanalu.
  • channels.bluebubbles.serverUrl: Bazowy URL REST API BlueBubbles.
  • channels.bluebubbles.password: Haslo API.
  • channels.bluebubbles.webhookPath: Sciezka endpointu webhooka (domyslnie: /bluebubbles-webhook).
  • channels.bluebubbles.dmPolicy: pairing | allowlist | open | disabled (domyslnie: pairing).
  • channels.bluebubbles.allowFrom: Lista dozwolonych DM (identyfikatory, emaile, numery E.164, chat_id:*, chat_guid:*).
  • channels.bluebubbles.groupPolicy: open | allowlist | disabled (domyslnie: allowlist).
  • channels.bluebubbles.groupAllowFrom: Lista dozwolonych nadawcow grupowych.
  • channels.bluebubbles.groups: Konfiguracja per grupe (requireMention itp.).
  • channels.bluebubbles.sendReadReceipts: Wysylanie potwierdzen odczytu (domyslnie: true).
  • channels.bluebubbles.blockStreaming: Wlaczenie strumieniowania blokowego (domyslnie: false; wymagane do strumieniowania odpowiedzi).
  • channels.bluebubbles.textChunkLimit: Rozmiar kawalka wychodzacego w znakach (domyslnie: 4000).
  • channels.bluebubbles.chunkMode: length (domyslnie) dzieli tylko po przekroczeniu textChunkLimit; newline dzieli na pustych liniach (granice akapitow) przed dzieleniem wedlug dlugosci.
  • channels.bluebubbles.mediaMaxMb: Limit mediow przychodzacych/wychodzacych w MB (domyslnie: 8).
  • channels.bluebubbles.mediaLocalRoots: Jawna lista dozwolonych absolutnych katalogow lokalnych dozwolonych dla sciezek lokalnych mediow wychodzacych. Wysylanie sciezek lokalnych jest domyslnie odrzucane, chyba ze jest to skonfigurowane. Nadpisanie per konto: channels.bluebubbles.accounts.<accountId>.mediaLocalRoots.
  • channels.bluebubbles.historyLimit: Max wiadomosci grupowych dla kontekstu (0 wylacza).
  • channels.bluebubbles.dmHistoryLimit: Limit historii DM.
  • channels.bluebubbles.actions: Wlaczenie/wylaczenie konkretnych akcji.
  • channels.bluebubbles.accounts: Konfiguracja wielokontowa.

Powiazane 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:...
  • Bezposrednie identyfikatory: +15555550123, [email protected]
    • Jesli bezposredni identyfikator nie ma istniejacego czatu DM, OpenClaw utworzy go przez POST /api/v1/chat/new. Wymaga to wlaczenia BlueBubbles Private API.

Bezpieczenstwo

  • Zadania webhooka sa uwierzytelniane przez porownywanie parametrow zapytania guid/password lub naglowkow z channels.bluebubbles.password. Zadania z localhost sa rowniez akceptowane.
  • Trzymaj haslo API i endpoint webhooka w tajemnicy (traktuj jak dane logowania).
  • Zaufanie localhost oznacza, ze reverse proxy na tym samym hoscie moze niezamierzenie ominac haslo. Jesli proxyujesz gateway, wymagaj autoryzacji na proxy i skonfiguruj gateway.trustedProxies. Zobacz Bezpieczenstwo Gateway.
  • Wlacz HTTPS + reguly firewall na serwerze BlueBubbles jesli udostepniasz go poza LAN.

Rozwiazywanie problemow

  • Jesli zdarzenia pisania/odczytu przestaja dzialac, sprawdz logi webhooka BlueBubbles i zweryfikuj, ze sciezka gateway pasuje do channels.bluebubbles.webhookPath.
  • Kody parowania wygasaja po godzinie; uzyj openclaw pairing list bluebubbles i openclaw pairing approve bluebubbles <code>.
  • Reakcje wymagaja BlueBubbles private API (POST /api/v1/message/react); upewnij sie, ze wersja serwera go udostepnia.
  • Edycja/cofniecie wyslania wymagaja macOS 13+ i kompatybilnej wersji serwera BlueBubbles. Na macOS 26 (Tahoe) edycja jest obecnie zepsuta z powodu zmian private API.
  • Aktualizacje ikon grup moga byc niestabilne na macOS 26 (Tahoe): API moze zwrocic sukces, ale nowa ikona sie nie synchronizuje.
  • OpenClaw automatycznie ukrywa znane zepsute akcje na podstawie wersji macOS serwera BlueBubbles. Jesli edycja nadal pojawia sie na macOS 26 (Tahoe), wylacz ja recznie przez channels.bluebubbles.actions.edit=false.
  • Dla informacji o statusie/zdrowiu: openclaw status --all lub openclaw status --deep.

Ogolna referencja przepływu kanalow: Kanaly i przewodnik Pluginy.

arrow_back
Poprzedni
Channels
Następny
Discord
arrow_forward