iMessage

​

Szybka konfiguracja

brew install steipete/tap/imsg
brew update && brew upgrade imsg
imsg rpc --help
imsg launch
openclaw channels status --probe

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "/usr/local/bin/imsg",
      dbPath: "/Users/user/Library/Messages/chat.db",
    },
  },
}

openclaw gateway

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

ssh messages-mac 'brew install steipete/tap/imsg && brew update && brew upgrade imsg'

#!/usr/bin/env bash
exec ssh -T messages-mac imsg "$@"

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "user@gateway-host", // używane do pobierania załączników przez SCP
      includeAttachments: true,
      // Opcjonalnie: dodatkowe dozwolone katalogi główne załączników (łączone z domyślnym
      // /Users/*/Library/Messages/Attachments).
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
    },
  },
}

​

Wymagania i uprawnienia (macOS)

• Na Macu, na którym działa imsg, użytkownik musi być zalogowany do Wiadomości.
• Kontekst procesu uruchamiającego OpenClaw/imsg wymaga pełnego dostępu do dysku (dostęp do bazy danych Wiadomości).
• Wysyłanie wiadomości przez Messages.app wymaga uprawnienia do automatyzacji.
• W przypadku zaawansowanych działań (reakcja / edycja / cofnięcie wysłania / odpowiedź w wątku / efekty / ankiety / operacje grupowe) ochrona integralności systemu musi być wyłączona — zobacz Włączanie prywatnego API imsg. Podstawowe wysyłanie i odbieranie tekstu oraz multimediów działa bez jej wyłączania.

imsg chats --limit 1
# lub
imsg send <handle> "test"

Brak uprawnień do wysyłania zdarzeń Apple do Wiadomości. (-1743)

kTCCServiceAppleEvents | /usr/libexec/sshd-keygen-wrapper | auth_value=0 | com.apple.MobileSMS

​

Włączanie prywatnego API imsg

• Tryb podstawowy (domyślny, nie wymaga zmian SIP): wychodzący tekst i multimedia przez send, obserwowanie i historia wiadomości przychodzących oraz lista czatów. Te funkcje są dostępne od razu po świeżej instalacji brew install steipete/tap/imsg i przyznaniu opisanych powyżej standardowych uprawnień systemu macOS.
• Tryb prywatnego API: imsg wstrzykuje pomocniczą bibliotekę dylib do Messages.app, aby wywoływać wewnętrzne funkcje IMCore. Odblokowuje to react, edit, unsend, reply (w wątku), sendWithEffect, poll i poll-vote (natywne ankiety Wiadomości), renameGroup, setGroupIcon, addParticipant, removeParticipant, leaveGroup, a także wskaźniki pisania i potwierdzenia odczytu.

Funkcje zaawansowane, takie jak read, typing, launch, rozbudowane wysyłanie obsługiwane przez most, modyfikowanie wiadomości i zarządzanie czatami, są opcjonalne. Wymagają wyłączenia SIP i wstrzyknięcia pomocniczej biblioteki dylib do Messages.app. imsg launch odmawia wstrzyknięcia, gdy SIP jest włączona.

​

Konfiguracja

1. Zainstaluj (lub uaktualnij) imsg na Macu, na którym działa Messages.app:
   brew install steipete/tap/imsg
   brew update && brew upgrade imsg
   imsg --version
   imsg status --json
   
   Dane wyjściowe imsg status --json zawierają bridge_version, rpc_methods oraz selectors dla poszczególnych metod, dzięki czemu przed rozpoczęciem można sprawdzić, co obsługuje bieżąca kompilacja.
2. Wyłącz System Integrity Protection oraz (we współczesnych wersjach macOS) Library Validation. Wstrzyknięcie pomocniczej biblioteki dylib firmy innej niż Apple do podpisanego przez Apple procesu Messages.app wymaga wyłączenia SIP oraz złagodzenia weryfikacji bibliotek. Krok dotyczący SIP w trybie odzyskiwania zależy od wersji macOS:
   • macOS 10.13–10.15 (Sierra–Catalina): wyłącz Library Validation za pomocą Terminala, uruchom ponownie komputer w trybie odzyskiwania, wykonaj csrutil disable, a następnie ponownie uruchom komputer.
   • macOS 11+ (Big Sur i nowsze), Intel: przejdź do trybu odzyskiwania (lub odzyskiwania przez Internet), wykonaj csrutil disable, a następnie ponownie uruchom komputer.
   • macOS 11+, Apple Silicon: użyj sekwencji uruchamiania przyciskiem zasilania, aby przejść do trybu odzyskiwania; w najnowszych wersjach macOS przytrzymaj klawisz Left Shift podczas klikania Continue, a następnie wykonaj csrutil disable. Konfiguracje maszyn wirtualnych wymagają osobnej procedury, dlatego najpierw utwórz migawkę maszyny wirtualnej.
   W systemie macOS 11 i nowszych samo csrutil disable zwykle nie wystarcza. Apple nadal wymusza weryfikację bibliotek dla Messages.app jako pliku binarnego platformy, dlatego pomocniczy komponent podpisany ad hoc zostaje odrzucony (Library Validation failed: ... platform binary, but mapped file is not) nawet przy wyłączonym SIP. Po wyłączeniu SIP wyłącz również weryfikację bibliotek i ponownie uruchom komputer:
   sudo defaults write /Library/Preferences/com.apple.security.libraryvalidation.plist DisableLibraryValidation -bool true
   
   macOS 26 (Tahoe), zweryfikowano w wersji 26.5.1: wyłączony SIP wraz z powyższym poleceniem DisableLibraryValidation wystarcza do wstrzyknięcia komponentu pomocniczego we wszystkich wersjach od 26.0 do 26.5.x. Żadne argumenty rozruchowe nie są wymagane. Plik plist jest czynnikiem decydującym i najczęściej pomijanym krokiem, gdy wstrzykiwanie w Tahoe kończy się niepowodzeniem:
   • Z plikiem plist: imsg launch wykonuje wstrzyknięcie, a imsg status zgłasza advanced_features: true.
   • Bez pliku plist (nawet przy wyłączonym SIP): imsg launch kończy się niepowodzeniem z komunikatem Failed to launch: Timeout waiting for Messages.app to initialize. AMFI odrzuca podczas ładowania komponent pomocniczy podpisany ad hoc, przez co most nigdy nie osiąga gotowości, a uruchamianie przekracza limit czasu. To przekroczenie limitu czasu jest objawem, z którym większość osób spotyka się w Tahoe; rozwiązaniem jest powyższy plik plist, a nie bardziej drastyczne działania.
   Jeśli po uaktualnieniu macOS wstrzykiwanie imsg launch lub określone selectors zaczynają zwracać wartość false, zwykle przyczyną jest ta blokada. Zanim uznasz, że sam krok dotyczący SIP się nie powiódł, sprawdź stan SIP i weryfikacji bibliotek. Jeśli te ustawienia są prawidłowe, ale most nadal nie może wykonać wstrzyknięcia, zbierz imsg status --json wraz z wynikiem imsg launch i zgłoś problem w projekcie imsg zamiast osłabiać dodatkowe zabezpieczenia całego systemu.
3. Wstrzyknij komponent pomocniczy. Po wyłączeniu SIP i zalogowaniu się w Messages.app:
   imsg launch
   
   imsg launch odmawia wykonania wstrzyknięcia, jeśli SIP jest nadal włączony, więc służy to również jako potwierdzenie wykonania kroku 2.
4. Zweryfikuj most z poziomu OpenClaw:
   openclaw channels status --probe
   
   Wpis iMessage powinien zgłaszać works, a imsg status --json | jq '{rpc_methods, selectors}' powinien przedstawiać możliwości udostępniane przez używaną kompilację macOS. Tworzenie ankiet wymaga selectors.pollPayloadMessage; głosowanie wymaga zarówno selectors.pollVoteMessage, jak i metody RPC poll.vote. Plugin OpenClaw udostępnia tylko działania obsługiwane przez wynik sondowania zapisany w pamięci podręcznej, natomiast przy pustej pamięci podręcznej zachowuje optymistyczne założenia i wykonuje sondowanie przy pierwszym wysłaniu.

​

Gdy SIP pozostaje włączony

• imsg przechodzi do trybu podstawowego — obsługuje tylko tekst, multimedia i odbieranie.
• Plugin OpenClaw nadal udostępnia wysyłanie tekstu i multimediów oraz monitorowanie wiadomości przychodzących; ukrywa react, edit, unsend, reply, sendWithEffect i operacje grupowe z powierzchni działań (zgodnie z blokadą możliwości poszczególnych metod).
• Można użyć osobnego komputera Mac bez Apple Silicon (lub dedykowanego komputera Mac dla bota) z wyłączonym SIP do obsługi obciążenia iMessage, pozostawiając SIP włączony na urządzeniach głównych. Zobacz poniżej sekcję Dedykowany użytkownik macOS dla bota (osobna tożsamość iMessage).

​

Kontrola dostępu i trasowanie

{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: { "*": { "requireMention": true } },
    },
  },
}

{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: {
        "*": { systemPrompt: "Use British spelling." },
        "8421": {
          requireMention: true,
          systemPrompt: "This is the on-call rotation chat. Keep replies under 3 sentences.",
        },
        "9907": {
          // explicit suppression: the wildcard "Use British spelling." does not apply here
          systemPrompt: "",
        },
      },
    },
  },
}

​

Powiązania konwersacji ACP

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

• znormalizowanego uchwytu wiadomości bezpośredniej, takiego jak +15555550123 lub user@example.com
• chat_id:<id> (zalecane dla stabilnych powiązań grupowych)
• chat_guid:<guid>
• chat_identifier:<identifier>

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: { agent: "codex", backend: "acpx", mode: "persistent" },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "imessage",
        accountId: "default",
        peer: { kind: "group", id: "chat_id:123" },
      },
      acp: { label: "codex-group" },
    },
  ],
}

​

Wzorce wdrażania

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "bot@mac-mini.tailnet-1234.ts.net",
      includeAttachments: true,
      dbPath: "/Users/bot/Library/Messages/chat.db",
    },
  },
}

#!/usr/bin/env bash
exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"

​

Multimedia, dzielenie na fragmenty i cele dostarczania

imsg chats --limit 20

​

Akcje prywatnego API

{
  channels: {
    imessage: {
      actions: {
        reactions: true,
        edit: true,
        unsend: true,
        reply: true,
        sendWithEffect: true,
        sendAttachment: true,
        renameGroup: true,
        setGroupIcon: true,
        addParticipant: true,
        removeParticipant: true,
        leaveGroup: true,
        polls: true,
      },
    },
  },
}

{
  channels: {
    imessage: {
      sendReadReceipts: false,
    },
  },
}

​

Zapisy konfiguracji

{
  channels: {
    imessage: {
      configWrites: false,
    },
  },
}

​

Scalanie podzielonych wiadomości prywatnych (polecenie + adres URL w jednej kompozycji)

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

{
  channels: {
    imessage: {
      coalesceSameSenderDms: true, // włączenie opcjonalne (domyślnie: false)
    },
  },
}

{
  messages: {
    inbound: {
      byChannel: {
        // 7000 ms obejmuje zaobserwowane opóźnienia podglądu adresów URL w Messages.app.
        imessage: 7000,
      },
    },
  },
}

​

Scenariusze i dane widoczne dla agenta

​

Odzyskiwanie wiadomości przychodzących po ponownym uruchomieniu mostu lub Gateway

• Deduplikacja powtórzeń. Każda przekazana wiadomość przychodząca jest rejestrowana według identyfikatora GUID Apple w trwałym stanie pluginu (imessage.inbound-dedupe): zostaje zarezerwowana podczas pobierania i zatwierdzona po obsłużeniu (rezerwacja jest zwalniana po przejściowym błędzie, aby umożliwić ponowną próbę). Wszystko, co już obsłużono, jest odrzucane zamiast przekazywane dwukrotnie. Umożliwia to agresywne odtwarzanie podczas odzyskiwania bez prowadzenia ewidencji poszczególnych wiadomości.
• Odzyskiwanie po przestoju. Podczas uruchamiania monitor zapamiętuje ostatni przekazany identyfikator rowid chat.db (trwały kursor dla każdego konta) i przekazuje go do imsg watch.subscribe jako since_rowid, dzięki czemu imsg odtwarza wiersze otrzymane podczas niedostępności Gateway, a następnie śledzi wiadomości na żywo. Odtwarzanie jest ograniczone do 500 najnowszych wierszy oraz wiadomości sprzed maksymalnie około 2 godzin, a deduplikacja odrzuca wszystko, co już obsłużono.
• Ograniczenie wieku nieaktualnych zaległości. Wiersze powyżej granicy uruchomienia są faktycznie odbierane na żywo; jeśli data wysłania jednego z nich jest starsza od czasu nadejścia o ponad około 15 minut, jest on zaległością opróżnioną przez Push i zostaje stłumiony. Odtwarzane wiersze (na granicy lub poniżej niej) korzystają natomiast z szerszego okna odzyskiwania, dzięki czemu niedawno pominięta wiadomość zostaje dostarczona, a dawna historia nie.

​

Sygnał widoczny dla operatora

imessage: stłumiono nieaktualne zaległe wiadomości przychodzące account=<id> sent=<iso> recovery=<bool> (<N> stłumionych od uruchomienia)

​

Migracja

​

Rozwiązywanie problemów

imsg rpc --help
imsg status --json
openclaw channels status --probe

imsg chats --limit 10 --json
imsg watch --chat-id <chat-id> --json
sqlite3 ~/Library/Messages/chat.db \
  "select datetime(max(date)/1000000000 + 978307200, 'unixepoch', 'localtime'), max(ROWID) from message;"

launchctl kickstart -k system/com.apple.apsd
launchctl kickstart -k gui/$(id -u)/com.apple.CommCenter
launchctl kickstart -k gui/$(id -u)/com.apple.identityservicesd
launchctl kickstart -k gui/$(id -u)/com.apple.imagent
imsg launch
openclaw gateway restart

#!/usr/bin/env bash
exec ssh -T messages-mac imsg "$@"

openclaw channels status --probe --channel imessage

imsg chats --limit 1
imsg send <handle> "test"

​

Odnośniki do dokumentacji konfiguracji

• Dokumentacja konfiguracji — iMessage
• Konfiguracja Gateway
• Parowanie

​

Powiązane materiały

• Przegląd kanałów — wszystkie obsługiwane kanały
• Usunięcie BlueBubbles i ścieżka iMessage oparta na imsg — ogłoszenie i podsumowanie migracji
• Przejście z BlueBubbles — tabela mapowania konfiguracji i instrukcja migracji krok po kroku
• Parowanie — uwierzytelnianie wiadomości prywatnych i proces parowania
• Grupy — działanie czatów grupowych i ograniczanie obsługi na podstawie wzmianek
• Routing kanałów — routing sesji dla wiadomości
• Bezpieczeństwo — model dostępu i wzmacnianie zabezpieczeń