Przejście z BlueBubbles

​

Lista kontrolna migracji

1. Zweryfikuj działanie imsg bezpośrednio na Macu, na którym działa Messages.app (imsg chats, imsg history, imsg send, imsg rpc --help).
2. Skopiuj klucze zachowania z channels.bluebubbles do channels.imessage: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups, includeAttachments, attachmentRoots, mediaMaxMb, textChunkLimit, coalesceSameSenderDms oraz actions.
3. Usuń nieistniejące już klucze transportu: serverUrl, password, adresy URL webhooków oraz konfigurację serwera BlueBubbles.
4. Jeśli Gateway nie działa na Macu z aplikacją Messages, ustaw channels.imessage.cliPath na wrapper SSH, a remoteHost na potrzeby zdalnego pobierania załączników.
5. Włącz channels.imessage, uruchom ponownie Gateway, a następnie wykonaj openclaw channels status --probe --channel imessage.
6. Przetestuj jedną wiadomość bezpośrednią, jedną dozwoloną grupę, załączniki, jeśli są włączone, oraz każdą akcję prywatnego API, której agent ma używać.
7. Po zweryfikowaniu ścieżki iMessage usuń serwer BlueBubbles i starą konfigurację channels.bluebubbles.

​

Działanie imsg

• Odczyt odbywa się z ~/Library/Messages/chat.db za pomocą połączenia SQLite tylko do odczytu.
• Wiadomości przychodzące na żywo pochodzą z imsg watch / watch.subscribe, które śledzi zdarzenia systemu plików dotyczące chat.db, z mechanizmem rezerwowego cyklicznego odpytywania.
• Wysyłanie zwykłego tekstu i plików korzysta z automatyzacji Messages.app.
• Zaawansowane akcje wykorzystują imsg launch do wstrzyknięcia pomocnika imsg do Messages.app. Umożliwia to potwierdzenia odczytu, wskaźniki pisania, wysyłanie treści rozszerzonych, edycję, cofanie wysłania, odpowiedzi w wątkach, reakcje Tapback, ankiety oraz zarządzanie grupami.
• Kompilacje dla systemu Linux mogą analizować skopiowany plik chat.db, ale nie mogą wysyłać wiadomości, obserwować aktywnej bazy danych Maca ani sterować Messages.app. Aby korzystać z iMessage w OpenClaw, uruchom imsg na zalogowanym Macu lub za pośrednictwem wrappera SSH prowadzącego do tego Maca.

​

Zanim rozpoczniesz

1. Zainstaluj imsg na Macu, na którym działa Messages.app:
   brew install steipete/tap/imsg
   brew update && brew upgrade imsg
   imsg --version
   imsg chats --limit 3
   
   W typowej konfiguracji lokalnej kreator konfiguracji OpenClaw może, po potwierdzeniu przez użytkownika, zainstalować lub zaktualizować imsg przez Homebrew na Macu zalogowanym do Messages. Konfiguracjami ręcznymi i topologiami z wrapperem SSH nadal zarządza operator: powtórz aktualizację przez Homebrew w tym samym lokalnym lub zdalnym kontekście użytkownika, w którym będzie uruchamiane imsg. Jeśli imsg chats kończy się błędem unable to open database file, zwraca pusty wynik albo błąd authorization denied, przyznaj pełny dostęp do dysku terminalowi, edytorowi, procesowi Node, usłudze Gateway lub nadrzędnemu procesowi SSH, który uruchamia imsg, a następnie ponownie uruchom ten proces nadrzędny.
2. Przed zmianą konfiguracji OpenClaw zweryfikuj odczyt, obserwowanie, wysyłanie i interfejs RPC:
   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 "Test OpenClaw imsg"
   imsg rpc --help
   
   Zastąp 42 rzeczywistym identyfikatorem czatu z imsg chats. Wysyłanie wymaga uprawnienia do automatyzacji Messages.app. Jeśli OpenClaw będzie działać przez SSH, wykonaj te polecenia za pośrednictwem tego samego wrappera SSH lub w tym samym kontekście użytkownika, którego będzie używać OpenClaw. Jeśli odczyt działa, ale wysyłanie kończy się błędem AppleEvents -1743, sprawdź, czy uprawnienie do automatyzacji zostało przyznane procesowi /usr/libexec/sshd-keygen-wrapper; zobacz Wysyłanie przez wrapper SSH kończy się błędem AppleEvents -1743.
3. Włącz most prywatnego API. Jest on zdecydowanie zalecany dla iMessage w OpenClaw, ponieważ zależą od niego odpowiedzi, reakcje Tapback, efekty, ankiety, odpowiedzi z załącznikami i akcje grupowe:
   imsg launch
   imsg status --json
   
   Polecenie imsg launch wymaga wyłączenia SIP (a we współczesnych wersjach macOS także złagodzenia weryfikacji bibliotek — zobacz Włączanie prywatnego API imsg). Podstawowe wysyłanie, historia i obserwowanie działają bez imsg launch; pełny zestaw akcji iMessage w OpenClaw nie działa.
4. Po włączeniu channels.imessage i uruchomieniu Gateway zweryfikuj most za pośrednictwem OpenClaw:
   openclaw channels status --probe
   
   Konto iMessage powinno zgłaszać stan works; z opcją --json dane sondy zawierają privateApi.available: true. Jeśli wartość wynosi false, najpierw napraw ten problem — zobacz Wykrywanie możliwości. Sondowanie wymaga osiągalnego Gateway (w przeciwnym razie CLI zwraca wyłącznie dane z konfiguracji) i obejmuje tylko skonfigurowane, włączone konta.
5. Utwórz kopię konfiguracji:
   cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
   

​

Przeniesienie konfiguracji

​

Pułapka rejestru grup

1. Lista dozwolonych nadawców / celów czatu (channels.imessage.groupAllowFrom) — dopasowuje identyfikator nadawcy lub cel czatu (wpisy chat_id:, chat_guid:, chat_identifier:). Jeśli groupAllowFrom nie jest ustawione, ta brama używa zastępczo allowFrom; jawne groupAllowFrom: [] wyłącza ten mechanizm zastępczy i odrzuca każdą wiadomość grupową przy groupPolicy: "allowlist".
2. Rejestr grup (channels.imessage.groups) — z kluczami będącymi numerycznymi wartościami iMessage chat_id:
   • Brak bloku groups (lub pusty blok): grupy przechodzą przez tę bramę, o ile brama 1 ma niepustą efektywną listę dozwolonych nadawców; filtrowanie nadawców kontroluje dostęp i nie pojawia się ostrzeżenie startowe o odrzucaniu wszystkich wiadomości.
   • groups z wpisami, ale bez "*": przechodzą tylko wymienione klucze chat_id. Dodanie dowolnej grupy zmienia rejestr w listę dozwolonych nawet przy groupPolicy: "open".
   • groups: { "*": { ... } }: każda grupa przechodzi przez tę bramę.

• Raz dla każdego konta podczas uruchamiania, gdy ustawiono groupPolicy: "allowlist", a efektywna lista dozwolonych nadawców grupowych jest pusta: imessage: groupPolicy="allowlist" for account "<id>" but no group sender allowlist is configured .... Ustaw groupAllowFrom (lub allowFrom), aby dopuścić nadawców; samo dodanie groups nie spełnia wymagań bramy nadawców.
• Raz dla każdego chat_id podczas działania, gdy rejestr odrzuca grupę: imessage: dropping group message from chat_id=<id> ... not in channels.imessage.groups allowlist, ze wskazaniem dokładnego klucza, który należy dodać.

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

​

Krok po kroku

1. Przenieś konfigurację. Podczas edycji pozostaw nowy blok wyłączony; stary blok channels.bluebubbles jest ignorowany przez bieżącą wersję OpenClaw i może pozostać obok jako punkt odniesienia:
   {
     channels: {
       imessage: {
         enabled: false, // zmień na true, gdy wszystko będzie gotowe do przełączenia
         cliPath: "/opt/homebrew/bin/imsg",
         dmPolicy: "pairing",
         allowFrom: ["+15555550123"], // skopiuj z bluebubbles.allowFrom
         groupPolicy: "allowlist",
         groupAllowFrom: [], // skopiuj z bluebubbles.groupAllowFrom
         groups: { "*": { requireMention: true } }, // symbol wieloznaczny skopiuj bez zmian; wpisom poszczególnych czatów nadaj klucze według chat_id
         // działania są domyślnie włączone; ustaw poszczególne przełączniki na false, aby je wyłączyć
       },
     },
   }
   
2. Przełącz i wykonaj test. Ustaw channels.imessage.enabled: true, uruchom ponownie Gateway i potwierdź, że kanał zgłasza prawidłowy stan:
   openclaw gateway restart
   openclaw channels status --probe --channel imessage   # oczekiwane "works"; --json pokazuje privateApi.available: true
   
   Test wymaga dostępnego Gateway i sprawdza tylko skonfigurowane, włączone konta. Użyj bezpośrednich poleceń imsg z sekcji Zanim zaczniesz, aby sprawdzić samego Maca.
3. Sprawdź wiadomości prywatne. Wyślij agentowi wiadomość prywatną i potwierdź, że odpowiedź dotarła.
4. Sprawdź grupy osobno. Wiadomości prywatne i grupowe korzystają z różnych ścieżek kodu — powodzenie wiadomości prywatnych nie dowodzi, że routing grup działa. Wyślij wiadomość na dozwolonym czacie grupowym i potwierdź, że odpowiedź dotarła. Jeśli grupa zamilknie (brak odpowiedzi agenta i brak błędu), sprawdź dziennik Gateway pod kątem dwóch wierszy warn z opisanej wyżej sekcji „Pułapka rejestru grup”. Ostrzeżenie podczas uruchamiania oznacza, że efektywna lista dozwolonych nadawców jest pusta; ostrzeżenie dla konkretnego chat_id oznacza, że wypełniony rejestr groups nie zawiera tego czatu.
5. Sprawdź dostępne działania. W sparowanej wiadomości prywatnej poproś agenta o dodanie reakcji, edycję, cofnięcie wysłania, odpowiedź, wysłanie zdjęcia oraz — w grupie — zmianę nazwy grupy lub dodanie bądź usunięcie uczestnika. Każde działanie powinno zostać wykonane natywnie w Messages.app. Jeśli którekolwiek działanie zgłosi iMessage <action> requires the imsg private API bridge, ponownie uruchom imsg launch i odśwież stan za pomocą openclaw channels status --probe.
6. Usuń serwer BlueBubbles i blok channels.bluebubbles, gdy wiadomości prywatne, grupy i działania iMessage zostaną zweryfikowane. OpenClaw nie odczytuje channels.bluebubbles.

​

Skrócone porównanie obsługiwanych działań

​

Parowanie, sesje i powiązania ACP

• Listy dozwolonych są przenoszone według identyfikatora. channels.imessage.allowFrom rozpoznaje te same ciągi +15555550123 / user@example.com, których używało BlueBubbles — skopiuj je bez zmian.
• Zatwierdzenia z magazynu parowania nie są przenoszone. Magazyn parowania jest osobny dla każdego kanału i nic nie przenosi starego magazynu BlueBubbles. Nadawcy zatwierdzeni wyłącznie przez parowanie muszą ponownie sparować się w iMessage albo musisz dodać ich identyfikatory do allowFrom.
• Sesje pozostają ograniczone do agenta i czatu. Wiadomości prywatne są scalane z główną sesją agenta przy domyślnym ustawieniu session.dmScope=main; sesje grupowe pozostają odizolowane dla każdego chat_id (agent:<agentId>:imessage:group:<chat_id>). Stara historia rozmów zapisana pod kluczami sesji BlueBubbles nie jest przenoszona do sesji iMessage.
• Powiązania ACP odwołujące się do match.channel: "bluebubbles" trzeba zmienić na "imessage". Postacie match.peer.id (chat_id:, chat_guid:, chat_identifier:, sam identyfikator) są identyczne.

​

Brak kanału wycofania zmian

​

Powiązane

• Usunięcie BlueBubbles i ścieżka iMessage oparta na imsg — krótkie ogłoszenie i podsumowanie dla operatora.
• iMessage — pełna dokumentacja kanału iMessage, w tym konfiguracja imsg launch i wykrywanie możliwości.
• /channels/bluebubbles — starszy adres URL przekierowujący do tego przewodnika migracji.
• Parowanie — uwierzytelnianie wiadomości prywatnych i proces parowania.
• Routing kanałów — sposób, w jaki Gateway wybiera kanał dla odpowiedzi wychodzących.