iMessage

​

Szybka konfiguracja

brew install steipete/tap/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>

#!/usr/bin/env bash
exec ssh -T gateway-host imsg "$@"

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "user@gateway-host", // used for SCP attachment fetches
      includeAttachments: true,
      // Optional: override allowed attachment roots.
      // Defaults include /Users/*/Library/Messages/Attachments
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
    },
  },
}

​

Wymagania i uprawnienia (macOS)

• Messages musi być zalogowane na Macu uruchamiającym imsg.
• Full Disk Access jest wymagany dla kontekstu procesu uruchamiającego OpenClaw/imsg (dostęp do bazy danych Messages).
• Uprawnienie Automation jest wymagane do wysyłania wiadomości przez Messages.app.
• Dla zaawansowanych akcji (reakcja / edycja / cofnięcie wysłania / odpowiedź w wątku / efekty / ankiety / operacje na grupach) System Integrity Protection musi być wyłączone — zobacz Włączanie prywatnego API imsg poniżej. Podstawowe wysyłanie/odbieranie tekstu i multimediów działa bez tego.

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

Not authorized to send Apple events to Messages. (-1743)

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

​

Włączanie prywatnego API imsg

• Tryb podstawowy (domyślny, bez potrzeby zmian SIP): tekst i multimedia wychodzące przez send, obserwacja/historia przychodząca, lista czatów. To otrzymujesz od razu po świeżym brew install steipete/tap/imsg oraz standardowych uprawnieniach macOS opisanych wyżej.
• Tryb prywatnego API: imsg wstrzykuje pomocniczą dylib do Messages.app, aby wywoływać wewnętrzne funkcje IMCore. To odblokowuje react, edit, unsend, reply (w wątku), sendWithEffect, poll i poll-vote (natywne ankiety Messages), renameGroup, setGroupIcon, addParticipant, removeParticipant, leaveGroup, a także wskaźniki pisania i potwierdzenia odczytu.

Zaawansowane funkcje, takie jak read, typing, launch, bogate wysyłanie wspierane przez most, modyfikacja wiadomości i zarządzanie czatem, są opcjonalne. Wymagają wyłączenia SIP i wstrzyknięcia pomocniczej dylib do Messages.app. imsg launch odmawia wstrzyknięcia, gdy SIP jest włączone.

​

Konfiguracja

1. Zainstaluj (lub zaktualizuj) imsg na Macu, na którym działa Messages.app:
   brew install steipete/tap/imsg
   imsg --version
   imsg status --json
   
   Dane wyjściowe imsg status --json raportują bridge_version, rpc_methods i selectors dla poszczególnych metod, aby przed rozpoczęciem można było zobaczyć, co obsługuje bieżąca kompilacja.
2. Wyłącz System Integrity Protection oraz (na nowoczesnym macOS) Library Validation. Wstrzyknięcie niepochodzącej od Apple pomocniczej dylib do podpisanej przez Apple aplikacji Messages.app wymaga wyłączenia SIP oraz poluzowania walidacji bibliotek. Krok SIP w trybie Recovery zależy od wersji macOS:
   • macOS 10.13-10.15 (Sierra-Catalina): wyłącz Library Validation przez Terminal, uruchom ponownie w Recovery Mode, wykonaj csrutil disable, uruchom ponownie.
   • macOS 11+ (Big Sur i nowsze), Intel: Recovery Mode (albo Internet Recovery), csrutil disable, uruchom ponownie.
   • macOS 11+, Apple Silicon: sekwencja startu przyciskiem zasilania, aby wejść do Recovery; w nowszych wersjach macOS przytrzymaj klawisz Left Shift podczas kliknięcia Continue, a następnie csrutil disable. Konfiguracje maszyn wirtualnych używają osobnego procesu, więc najpierw zrób migawkę VM.
   W macOS 11 i nowszych samo csrutil disable zwykle nie wystarcza. Apple nadal wymusza walidację bibliotek wobec Messages.app jako pliku binarnego platformy, więc pomocnik podpisany adhoc jest odrzucany (Library Validation failed: ... platform binary, but mapped file is not) nawet przy wyłączonym SIP. Po wyłączeniu SIP wyłącz także walidację bibliotek i uruchom ponownie:
   sudo defaults write /Library/Preferences/com.apple.security.libraryvalidation.plist DisableLibraryValidation -bool true
   
   macOS 26 (Tahoe), zweryfikowane na 26.5.1: wyłączone SIP plus powyższe polecenie DisableLibraryValidation wystarczają do wstrzyknięcia pomocnika w wersjach od 26.0 do 26.5.x. Nie są wymagane żadne boot-args. Plist jest czynnikiem decydującym i najczęściej pomijanym krokiem, gdy wstrzyknięcie na Tahoe kończy się niepowodzeniem:
   • Z plist: imsg launch wstrzykuje, a imsg status raportuje advanced_features: true.
   • Bez plist (nawet z wyłączonym SIP): imsg launch kończy się niepowodzeniem z Failed to launch: Timeout waiting for Messages.app to initialize. AMFI odrzuca pomocnik adhoc podczas ładowania, więc most nigdy nie staje się gotowy, a uruchomienie przekracza limit czasu. Ten timeout jest objawem, na który większość osób trafia na Tahoe, a poprawką jest powyższy plist, nie nic bardziej radykalnego.
   Zostało to potwierdzone kontrolowanym testem przed/po na macOS 26.5.1 (Apple Silicon): z plist dylib mapuje się do Messages.app, a most się uruchamia; po usunięciu plist i restarcie imsg launch generuje powyższy błąd timeout, a dylib nie jest zmapowana. Jeśli wstrzykiwanie imsg launch albo konkretne selectors zaczynają zwracać fałsz po uaktualnieniu macOS, ta blokada jest zwykle przyczyną. Sprawdź stan SIP i walidacji bibliotek, zanim uznasz, że nie powiódł się sam krok SIP. Jeśli te ustawienia są poprawne, a most nadal nie może wykonać wstrzyknięcia, zbierz imsg status --json oraz wynik imsg launch i zgłoś to do projektu imsg zamiast osłabiać dodatkowe systemowe mechanizmy bezpieczeństwa. Wykonaj procedurę Apple w trybie odzyskiwania dla swojego Maca, aby wyłączyć SIP przed uruchomieniem imsg launch.
3. Wstrzyknij pomocnika. Przy wyłączonym SIP i zalogowanej aplikacji Messages.app:
   imsg launch
   
   imsg launch odmawia wstrzyknięcia, gdy SIP jest nadal włączony, więc służy to także jako potwierdzenie, że krok 2 zadziałał.
4. Zweryfikuj most z OpenClaw:
   openclaw channels status --probe
   
   Wpis iMessage powinien zgłaszać works, a imsg status --json | jq '{rpc_methods, selectors}' powinno pokazać możliwości udostępniane przez Twoją wersję macOS. Tworzenie ankiet wymaga selectors.pollPayloadMessage; głosowanie wymaga zarówno selectors.pollVoteMessage, jak i metody RPC poll.vote. Plugin OpenClaw ogłasza tylko akcje obsługiwane przez zbuforowaną sondę, natomiast pusta pamięć podręczna pozostaje optymistyczna i sonduje przy pierwszym wysłaniu.

​

Gdy nie możesz wyłączyć SIP

• imsg wraca do trybu podstawowego — tylko tekst + media + odbieranie.
• Plugin OpenClaw nadal ogłasza wysyłanie tekstu/mediów i monitorowanie przychodzące; ukrywa tylko react, edit, unsend, reply, sendWithEffect oraz operacje grupowe z powierzchni akcji (zgodnie z bramką możliwości dla poszczególnych metod).
• Możesz uruchomić osobnego Maca bez Apple Silicon (albo dedykowanego Maca bota) z wyłączonym SIP dla obciążenia iMessage, pozostawiając SIP włączony na swoich głównych urządzeniach. Zobacz Dedykowany użytkownik bota macOS (osobna tożsamość iMessage) poniżej.

​

Kontrola dostępu i routing

{
  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 rozmów ACP

• Uruchom /acp spawn codex --bind here wewnątrz DM albo dozwolonego czatu grupowego.
• Przyszłe wiadomości w tej samej rozmowie iMessage będą kierowane do utworzonej sesji ACP.
• /new i /reset resetują tę samą powiązaną sesję ACP w miejscu.
• /acp close zamyka sesję ACP i usuwa powiązanie.

• znormalizowanego uchwytu DM, takiego jak +15555550123 albo user@example.com
• chat_id:<id> (zalecane dla stabilnych powiązań grup)
• 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 wdrożenia

{
  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 "$@"

​

Media, dzielenie na części 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 dzielonych wysyłek DM (polecenie + URL w jednej kompozycji)

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

{
  channels: {
    imessage: {
      coalesceSameSenderDms: true, // opt in (default: false)
    },
  },
}

{
  messages: {
    inbound: {
      byChannel: {
        // 7000 ms covers observed Messages.app URL-preview delays.
        imessage: 7000,
      },
    },
  },
}

​

Scenariusze i co widzi agent

​

Odzyskiwanie przychodzących wiadomości po restarcie mostka lub Gateway

• Deduplikacja odtworzeń. Każda wysłana przychodząca wiadomość jest rejestrowana według swojego Apple GUID w trwałym stanie Plugin (imessage.inbound-dedupe), zajmowana podczas ingestii i zatwierdzana po obsłużeniu (zwalniana przy błędzie przejściowym, aby można było ponowić próbę). Wszystko, co już obsłużono, jest odrzucane zamiast wysyłane drugi raz. To pozwala odzyskiwaniu agresywnie odtwarzać bez księgowania każdej wiadomości osobno.
• Odzyskiwanie po przestoju. Przy starcie monitor zapamiętuje ostatni wysłany chat.db rowid (utrwalony kursor per konto) i przekazuje go do imsg watch.subscribe jako since_rowid, więc imsg odtwarza wiersze, które trafiły podczas niedostępności Gateway, a potem śledzi na żywo. Odtwarzanie jest ograniczone do najnowszych wierszy i do wiadomości mających maksymalnie ~2 godziny, a deduplikacja odrzuca wszystko, co już obsłużono.
• Bariera wieku przestarzałych zaległości. Wiersze powyżej granicy startowej są rzeczywiście na żywo; taki, którego data wysłania jest o ponad ~15 minut starsza niż czas przybycia, jest zaległością opróżnioną przez Push i jest tłumiony. Odtworzone wiersze (na granicy lub poniżej) używają zamiast tego szerszego okna odzyskiwania, więc niedawno pominięta wiadomość zostanie dostarczona, a dawna historia nie.

​

Sygnał widoczny dla operatora

imessage: suppressed stale inbound backlog account=<id> sent=<iso> recovery=<bool> (<N> suppressed since start)

​

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"

​

Wskaźniki odniesienia konfiguracji

• Dokumentacja konfiguracji - iMessage
• Konfiguracja Gateway
• Parowanie

​

Powiązane

• Przegląd kanałów — wszystkie obsługiwane kanały
• Usunięcie BlueBubbles i ścieżka imsg iMessage — ogłoszenie i podsumowanie migracji
• Przejście z BlueBubbles — tabela tłumaczenia konfiguracji i przełączenie krok po kroku
• Parowanie — uwierzytelnianie DM i przepływ parowania
• Grupy — zachowanie czatu grupowego i bramkowanie wzmianek
• Routing kanałów — routing sesji dla wiadomości
• Bezpieczeństwo — model dostępu i utwardzanie