Przechodzenie z BlueBubbles

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Kiedy ta migracja ma sens

• Masz już uruchomione imsg na tym samym Macu (lub na Macu osiągalnym przez SSH), na którym Messages.app jest zalogowana.
• Chcesz mieć o jeden element mniej — bez osobnego serwera BlueBubbles, bez punktu końcowego REST do uwierzytelniania, bez instalacji Webhook. Pojedynczy binarny plik CLI zamiast serwera + aplikacji klienckiej + pomocnika.
• Używasz obsługiwanej wersji macOS / kompilacji imsg, w której sonda prywatnego API zgłasza available: true.

​

Co robi imsg

• Odczyty pochodzą z ~/Library/Messages/chat.db przy użyciu uchwytu SQLite tylko do odczytu.
• Aktywne wiadomości przychodzące pochodzą z imsg watch / watch.subscribe, które śledzi zdarzenia systemu plików chat.db z awaryjnym odpytywaniem.
• Wysyłanie używa automatyzacji Messages.app dla zwykłego tekstu i wysyłania plików.
• Zaawansowane działania używają imsg launch, aby wstrzyknąć pomocnika imsg do Messages.app. To odblokowuje potwierdzenia odczytu, wskaźniki pisania, rozbudowane wysyłanie, edycję, cofnięcie wysłania, odpowiedzi w wątkach, tapbacki i zarządzanie grupami.
• Kompilacje dla Linuksa mogą przeglądać skopiowany chat.db, ale nie mogą wysyłać, obserwować aktywnej bazy danych Maca ani sterować Messages.app. Dla OpenClaw iMessage uruchom imsg na zalogowanym Macu albo przez wrapper SSH do tego Maca.

​

Zanim zaczniesz

1. Zainstaluj imsg na Macu, na którym działa Messages.app:
   brew install steipete/tap/imsg
   imsg --version
   imsg chats --limit 3
   
   Jeśli imsg chats kończy się błędem unable to open database file, pustym wynikiem albo authorization denied, przyznaj Pełny dostęp do dysku terminalowi, edytorowi, procesowi Node, usłudze Gateway albo procesowi nadrzędnemu SSH, który uruchamia imsg, a następnie ponownie otwórz ten proces nadrzędny.
2. Zweryfikuj powierzchnie odczytu, obserwowania, wysyłania i RPC przed zmianą konfiguracji OpenClaw:
   imsg chats --limit 10 --json | jq -s
   imsg history --chat-id 42 --limit 10 --attachments --json | jq -s
   imsg watch --chat-id 42 --reactions --json
   imsg send --chat-id 42 --text "OpenClaw imsg test"
   imsg rpc --help
   
   Zastąp 42 rzeczywistym identyfikatorem czatu z imsg chats. Wysyłanie wymaga uprawnienia Automatyzacja dla Messages.app. Jeśli OpenClaw będzie działać przez SSH, uruchom te polecenia przez ten sam wrapper SSH lub kontekst użytkownika, którego będzie używać OpenClaw.
3. Włącz most prywatnego API, gdy potrzebujesz zaawansowanych działań:
   imsg launch
   imsg status --json
   
   imsg launch wymaga wyłączenia SIP. Podstawowe wysyłanie, historia i obserwowanie działają bez imsg launch; zaawansowane działania nie.
4. Zweryfikuj most przez OpenClaw:
   openclaw channels status --probe
   
   Oczekiwany wynik to imessage.privateApi.available: true. Jeśli zgłasza false, najpierw to napraw — zobacz Wykrywanie możliwości.
5. Utwórz migawkę konfiguracji:
   cp ~/.openclaw/openclaw.json5 ~/.openclaw/openclaw.json5.bak
   

​

Tłumaczenie konfiguracji

​

Pułapka rejestru grup

1. Lista dozwolonych nadawców / celów czatu (channels.imessage.groupAllowFrom) — sprawdzana przez isAllowedIMessageSender. Dopasowuje wiadomości przychodzące według uchwytu nadawcy, chat_guid, chat_identifier albo chat_id. Taki sam kształt jak w BlueBubbles.
2. Rejestr grup (channels.imessage.groups) — sprawdzany przez resolveChannelGroupPolicy z inbound-processing.ts:199. Przy groupPolicy: "allowlist" ta bramka wymaga jednego z poniższych:
   • wpisu wieloznacznego groups: { "*": { ... } } (ustawia allowAll = true), albo
   • jawnego wpisu per chat_id w groups.

• Jednorazowy startowy warn per konto, gdy ustawiono groupPolicy: "allowlist", ale channels.imessage.groups jest puste (brak wieloznacznika "*", brak wpisów per chat_id) — wyzwalany przed nadejściem jakichkolwiek wiadomości.
• Jednorazowy per chat_id warn przy pierwszym odrzuceniu konkretnej grupy w czasie działania, wskazujący chat_id i dokładny klucz do dodania w groups, aby ją dopuścić.

{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123", "chat_guid:any;-;..."],
      groups: {
        "*": { requireMention: true },
      },
    },
  },
}

​

Krok po kroku

1. Dodaj blok iMessage obok istniejącego bloku BlueBubbles. Zachowaj stary blok tylko jako źródło do kopiowania, dopóki nowa ścieżka nie zostanie zweryfikowana:
   {
     channels: {
       bluebubbles: {
         enabled: true,
         // ... existing config ...
       },
       imessage: {
         enabled: false, // turn on after the dry run below
         cliPath: "/opt/homebrew/bin/imsg",
         dmPolicy: "pairing",
         allowFrom: ["+15555550123"], // copy from bluebubbles.allowFrom
         groupPolicy: "allowlist",
         groupAllowFrom: [], // copy from bluebubbles.groupAllowFrom
         groups: { "*": { requireMention: true } }, // copy from bluebubbles.groups — silently drops groups if missing, see "Group registry footgun" above
         actions: {
           reactions: true,
           edit: true,
           unsend: true,
           reply: true,
           sendWithEffect: true,
           sendAttachment: true,
         },
       },
     },
   }
   
2. Sonda dry-run — uruchom Gateway i potwierdź, że iMessage zgłasza dobry stan:
   openclaw gateway
   openclaw channels status
   openclaw channels status --probe   # expect imessage.privateApi.available: true
   
   Ponieważ imessage.enabled nadal ma wartość false, żaden przychodzący ruch iMessage nie jest jeszcze routowany — ale --probe ćwiczy most, dzięki czemu wykryjesz problemy z uprawnieniami lub instalacją przed przełączeniem.
3. Przełącz. Usuń konfigurację BlueBubbles i włącz iMessage jedną edycją konfiguracji:
   {
     channels: {
       imessage: { enabled: true /* ... */ },
     },
   }
   
   Uruchom ponownie Gateway. Przychodzący ruch iMessage przechodzi teraz przez dołączony Plugin.
4. Zweryfikuj DM. Wyślij agentowi wiadomość bezpośrednią; potwierdź, że odpowiedź dotarła.
5. Zweryfikuj grupy osobno. DM i grupy używają różnych ścieżek kodu — powodzenie DM nie dowodzi, że grupy są routowane. Wyślij agentowi wiadomość w sparowanym czacie grupowym i potwierdź, że odpowiedź dotarła. Jeśli grupa milknie (brak odpowiedzi agenta, brak błędu), sprawdź log Gateway pod kątem imessage: dropping group message from chat_id=<id> albo startowego wiersza imessage: groupPolicy="allowlist" but channels.imessage.groups is empty — oba pojawiają się na domyślnym poziomie logowania. Jeśli którykolwiek się pojawi, blok groups jest brakujący lub pusty — zobacz powyżej „Pułapka rejestru grup”.
6. Zweryfikuj powierzchnię akcji — ze sparowanego DM poproś agenta o reakcję, edycję, cofnięcie wysłania, odpowiedź, wysłanie zdjęcia oraz (w grupie) zmianę nazwy grupy / dodanie lub usunięcie uczestnika. Każda akcja powinna natywnie pojawić się w Messages.app. Jeśli którakolwiek zgłasza „iMessage <action> requires the imsg private API bridge”, uruchom ponownie imsg launch i odśwież channels status --probe.
7. Usuń serwer i konfigurację BlueBubbles, gdy DM, grupy i akcje iMessage zostaną zweryfikowane. OpenClaw nie będzie używać channels.bluebubbles.

​

Szybki przegląd parytetu akcji

​

Parowanie, sesje i powiązania ACP

• Zatwierdzenia parowania przenoszą się według uchwytu. Nie musisz ponownie zatwierdzać znanych nadawców — channels.imessage.allowFrom rozpoznaje te same ciągi +15555550123 / user@example.com, których używało BlueBubbles.
• Sesje pozostają ograniczone do agenta + czatu. DM zwijają się do głównej sesji agenta przy domyślnym session.dmScope=main; sesje grup pozostają izolowane według chat_id. Klucze sesji różnią się (agent:<id>:imessage:group:<chat_id> względem odpowiednika BlueBubbles) — stara historia rozmów pod kluczami sesji BlueBubbles nie przechodzi do sesji iMessage.
• Powiązania ACP odwołujące się do match.channel: "bluebubbles" trzeba zaktualizować do "imessage". Kształty match.peer.id (chat_id:, chat_guid:, chat_identifier:, sam uchwyt) są identyczne.

​

Brak kanału wycofania

​

Powiązane

• iMessage — pełna dokumentacja kanału iMessage, w tym konfiguracja imsg launch i wykrywanie możliwości.
• /channels/bluebubbles — starszy URL przekierowujący do tego przewodnika migracji.
• Parowanie — uwierzytelnianie DM i przepływ parowania.
• Routing kanałów — jak Gateway wybiera kanał dla odpowiedzi wychodzących.