// dokumentacja openclaw

Integracja OpenClaw z iMessage — konfiguracja na macOS

Wprowadzenie

OpenClaw obsługuje iMessage przez dwa mechanizmy: starszą integrację imsg (CLI) oraz zalecaną dla nowych wdrożeń platformę BlueBubbles. Starszy mechanizm imsg komunikuje się przez JSON-RPC na stdio, a Gateway samodzielnie zarządza procesem imsg rpc.

Dla nowych instalacji zalecana jest migracja na BlueBubbles, które oferuje stabilniejsze połączenie i bogatszą funkcjonalność.

Wymagania

  • Mac z zalogowanym kontem w aplikacji Wiadomości (Messages)
  • Full Disk Access — wymagany do odczytu bazy danych chat.db
  • Uprawnienie Automation — potrzebne do wysyłania wiadomości
  • Uprawnienia są zależne od kontekstu — wdrożenia bez interfejsu graficznego (headless) wymagają jednorazowej konfiguracji w trybie interaktywnym

Instalacja lokalna na macOS

  1. Zainstaluj imsg przez Homebrew i zweryfikuj poleceniem imsg rpc --help
  2. Skonfiguruj OpenClaw, wskazując ścieżkę CLI i lokalizację bazy danych chat.db
  3. Uruchom Gateway
  4. Zatwierdź prośby o parowanie DM (wygasają po 1 godzinie)

Zdalny Mac przez SSH

Możesz wskazać ścieżkę CLI na skrypt opakowujący (wrapper), który tworzy tunel SSH do zdalnego Maca. Konfiguracja obsługuje ustawienie remoteHost do pobierania załączników przez SCP ze ścisłą weryfikacją klucza hosta.

Wzorce wdrożeń:

  • Dedykowany użytkownik macOS — izolowana tożsamość bota
  • Zdalny Mac przez Tailscale — SSH wrapper z bezpiecznym tunelem
  • Konfiguracja wielokontowa — nadpisania pól per konto

Kontrola dostępu

Polityka DM

  • pairing (domyślny) — kod parowania do zatwierdzenia
  • allowlist — tylko skonfigurowane numery/identyfikatory
  • open — otwarty dostęp
  • disabled — DM zablokowane

Polityka grup

  • allowlist (domyślny przy konfiguracji) — tylko dozwolone grupy
  • open — otwarte dla wszystkich
  • disabled — grupy zablokowane

Obsługa wzmianek

iMessage nie posiada natywnych metadanych wzmianek, dlatego system korzysta z wzorców regex. Komendy kontrolne od autoryzowanych nadawców mogą obejść bramkowanie wzmianek w grupach.

Routing sesji

DM domyślnie trafiają do głównej sesji agenta. Grupy korzystają z izolowanego routingu w formacie: agent:<agentId>:imessage:group:<chat_id>. Wieloosobowe wątki oznaczone jako nie-grupowe mogą być jawnie skonfigurowane jako ruch grupowy.

Powiązania konwersacji ACP

Obsługiwane jest dynamiczne powiązanie: /acp spawn codex --bind here oraz trwałe powiązania skonfigurowane we wpisach bindings[] na najwyższym poziomie.

Media i dostarczanie

  • Załączniki — opcjonalne, kontrolowane flagą includeAttachments
  • Limit tekstu — 4000 znaków domyślnie (textChunkLimit)
  • Limit mediów — 16 MB domyślnie (mediaMaxMb)
  • Preferowane formaty adresowania — chat_id:, chat_guid: lub chat_identifier:

Rozwiązywanie problemów

  • Walidacja binarki — sprawdź, czy imsg rpc jest dostępne i obsługuje RPC
  • Polityka DM — zweryfikuj listę dozwolonych i status parowania
  • Wiadomości grupowe — sprawdź konfigurację polityki grup
  • Ścieżki załączników — waliduj ścieżki zdalnych załączników
  • Uprawnienia macOS — ponowna autoryzacja w ustawieniach TCC (Full Disk Access, Automation)
Wróc do dokumentacji