iMessage (przestarzaly: imsg)

Ostrzezenie: Dla nowych wdrozen iMessage uzyj BlueBubbles.

Integracja imsg jest przestarzala i moze zostac usunieta w przyszlym wydaniu.

Status: przestarzala integracja z zewnetrznym CLI. Gateway uruchamia imsg rpc i komunikuje sie przez JSON-RPC na stdio (brak oddzielnego demona/portu).

• BlueBubbles (zalecany) — Zalecana sciezka iMessage dla nowych instalacji.
• Parowanie — DM iMessage domyslnie uzywaja trybu parowania.
• Referencja konfiguracji — Pelna referencja pol iMessage.

Szybka konfiguracja

Lokalny Mac (szybka sciezka)

  ### Krok 1: Zainstaluj i zweryfikuj imsg

brew install steipete/tap/imsg
imsg rpc --help

  ### Krok 2: Skonfiguruj OpenClaw

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

  ### Krok 3: Uruchom gateway

openclaw gateway

  ### Krok 4: Zatwierdz pierwsze parowanie DM (domyslne dmPolicy)

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

    Zadania parowania wygasaja po 1 godzinie.

Zdalny Mac przez SSH

OpenClaw wymaga jedynie zgodnego ze stdio `cliPath`, wiec mozesz wskazac `cliPath` na skrypt opakowujacy, ktory SSHuje do zdalnego Maca i uruchamia `imsg`.

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

Zalecana konfiguracja gdy zalaczniki sa wlaczone:

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "user@gateway-host", // uzywany do pobrania zalacznikow SCP
      includeAttachments: true,
      // Opcjonalnie: nadpisz dozwolone korzenie zalacznikow.
      // Domyslnie zawieraja /Users/*/Library/Messages/Attachments
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
    },
  },
}

Jesli `remoteHost` nie jest ustawiony, OpenClaw probuje go automatycznie wykryc parsujac skrypt opakowujacy SSH.
`remoteHost` musi byc `host` lub `user@host` (bez spacji ani opcji SSH).
OpenClaw uzywa scislego sprawdzania klucza hosta dla SCP, wiec klucz hosta przekaznika musi juz istniec w `~/.ssh/known_hosts`.
Sciezki zalacznikow sa walidowane wobec dozwolonych korzeni (`attachmentRoots` / `remoteAttachmentRoots`).

Wymagania i uprawnienia (macOS)

• Messages musi byc zalogowane na Macu z imsg.
• Pelny dostep do dysku jest wymagany dla kontekstu procesu uruchamiajacego OpenClaw/imsg (dostep do bazy danych Messages).
• Uprawnienia automatyzacji sa wymagane do wysylania wiadomosci przez Messages.app.

Wskazowka: Uprawnienia sa nadawane per kontekst procesu. Jesli gateway dziala bez glowicowo (LaunchAgent/SSH), uruchom jednorazowe interaktywne polecenie w tym samym kontekscie, aby wyzwolic monity:

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

Kontrola dostepu i routing

Polityka DM

`channels.imessage.dmPolicy` kontroluje wiadomosci bezposrednie:

- `pairing` (domyslnie)
- `allowlist`
- `open` (wymaga `allowFrom` zawierajacego `"*"`)
- `disabled`

Pole listy dozwolonych: `channels.imessage.allowFrom`.

Wpisy listy dozwolonych moga byc identyfikatorami lub celami czatu (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`).

Polityka grupowa + wzmianki

`channels.imessage.groupPolicy` kontroluje obsluge grup:

- `allowlist` (domyslnie gdy skonfigurowane)
- `open`
- `disabled`

Lista dozwolonych nadawcow grupowych: `channels.imessage.groupAllowFrom`.

Zastepczym runtime: jesli `groupAllowFrom` nie jest ustawione, sprawdzenia nadawcow grupowych iMessage stosuja zastepczym `allowFrom` gdy dostepne.
Uwaga runtime: jesli `channels.imessage` calkowicie brakuje, runtime stosuje zastepczym `groupPolicy="allowlist"` i loguje ostrzezenie (nawet jesli `channels.defaults.groupPolicy` jest ustawione).

Bramkowanie wzmiankami dla grup:

- iMessage nie ma natywnych metadanych wzmianek
- wykrywanie wzmianek uzywa wzorcow regex (`agents.list[].groupChat.mentionPatterns`, zastepczym `messages.groupChat.mentionPatterns`)
- bez skonfigurowanych wzorcow bramkowanie wzmiankami nie moze byc egzekwowane

Polecenia sterujace od autoryzowanych nadawcow moga ominac bramkowanie wzmiankami w grupach.

Sesje i deterministyczne odpowiedzi

- DM uzywaja bezposredniego routingu; grupy uzywaja routingu grupowego.
- Z domyslnym `session.dmScope=main`, DM iMessage zwijaja sie do glownej sesji agenta.
- Sesje grupowe sa izolowane (`agent:<agentId>:imessage:group:<chat_id>`).
- Odpowiedzi routuja z powrotem do iMessage uzywajac metadanych kanalu/celu pochodzenia.

Grupowe zachowanie watkowe:

Niektore wielouczestnikowe watki iMessage moga przychodzic z `is_group=false`.
Jesli ten `chat_id` jest jawnie skonfigurowany pod `channels.imessage.groups`, OpenClaw traktuje go jako ruch grupowy (bramkowanie grupowe + izolacja sesji grupowej).

Wzorce wdrozenia

Uzyj dedykowanego Apple ID i uzytkownika macOS, aby ruch bota byl izolowany od twojego osobistego profilu Messages.

Typowy przeplyw:

1. Utworz/zaloguj sie na dedykowanego uzytkownika macOS.
2. Zaloguj sie do Messages z Apple ID bota w tym uzytkowniku.
3. Zainstaluj `imsg` w tym uzytkowniku.
4. Utworz skrypt opakowujacy SSH, aby OpenClaw mogl uruchomic `imsg` w kontekscie tego uzytkownika.
5. Wskazz `channels.imessage.accounts.<id>.cliPath` i `.dbPath` na profil tego uzytkownika.

Pierwsze uruchomienie moze wymagac zatwierdzenia GUI (Automatyzacja + Pelny dostep do dysku) w sesji uzytkownika bota.

Czesta topologia:

- gateway dziala na Linux/VM
- iMessage + `imsg` dziala na Macu w twoim tailnet
- skrypt opakowujacy `cliPath` uzywa SSH do uruchamiania `imsg`
- `remoteHost` umozliwia pobieranie zalacznikow SCP

Przyklad:

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "[email protected]",
      includeAttachments: true,
      dbPath: "/Users/bot/Library/Messages/chat.db",
    },
  },
}

#!/usr/bin/env bash
exec ssh -T [email protected] imsg "$@"

Uzyj kluczy SSH, aby zarowno SSH, jak i SCP byly nieinteraktywne.
Upewnij sie, ze klucz hosta jest zaufany (np. `ssh [email protected]`), aby `known_hosts` byl wypelniony.

iMessage obsluguje konfiguracje per konto pod `channels.imessage.accounts`.

Kazde konto moze nadpisywac pola takie jak `cliPath`, `dbPath`, `allowFrom`, `groupPolicy`, `mediaMaxMb`, ustawienia historii i listy dozwolonych korzeni zalacznikow.

Media, dzielenie na kawalki i cele dostarczania

- pobieranie przychodzacych zalacznikow jest opcjonalne: `channels.imessage.includeAttachments`
- zdalne sciezki zalacznikow moga byc pobierane przez SCP gdy `remoteHost` jest ustawiony
- sciezki zalacznikow musza pasowac do dozwolonych korzeni:
  - `channels.imessage.attachmentRoots` (lokalne)
  - `channels.imessage.remoteAttachmentRoots` (tryb zdalny SCP)
  - domyslny wzorzec korzenia: `/Users/*/Library/Messages/Attachments`
- SCP uzywa scislego sprawdzania klucza hosta (`StrictHostKeyChecking=yes`)
- rozmiar mediow wychodzacych uzywa `channels.imessage.mediaMaxMb` (domyslnie 16 MB)

- limit kawalka tekstu: `channels.imessage.textChunkLimit` (domyslnie 4000)
- tryb kawalka: `channels.imessage.chunkMode`
  - `length` (domyslnie)
  - `newline` (dzielenie najpierw po akapitach)

Preferowane jawne cele:

- `chat_id:123` (zalecane dla stabilnego routingu)
- `chat_guid:...`
- `chat_identifier:...`

Cele identyfikatorowe sa rowniez obslugiwane:

- `imessage:+1555...`
- `sms:+1555...`
- `[email protected]`

imsg chats --limit 20

Zapisy konfiguracji

iMessage domyslnie pozwala na zapisy konfiguracji wyzwalane z kanalu (dla /config set|unset gdy commands.config: true).

Wylacz:

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

Rozwiazywanie problemow

Zweryfikuj plik binarny i obsluge RPC:

imsg rpc --help
openclaw channels status --probe

Jesli sonda raportuje RPC nieobslugiwane, zaktualizuj `imsg`.

Sprawdz:

- `channels.imessage.dmPolicy`
- `channels.imessage.allowFrom`
- zatwierdzenia parowania (`openclaw pairing list imessage`)

Sprawdz:

- `channels.imessage.groupPolicy`
- `channels.imessage.groupAllowFrom`
- zachowanie listy dozwolonych `channels.imessage.groups`
- konfiguracje wzorcow wzmianek (`agents.list[].groupChat.mentionPatterns`)

Sprawdz:

- `channels.imessage.remoteHost`
- `channels.imessage.remoteAttachmentRoots`
- autoryzacje kluczami SSH/SCP z hosta gateway
- klucz hosta istnieje w `~/.ssh/known_hosts` na hoscie gateway
- czytelnosc zdalnej sciezki na Macu z Messages

Uruchom ponownie w interaktywnym terminalu GUI w tym samym kontekscie uzytkownika/sesji i zatwierdz monity:

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

Potwierdz, ze Pelny dostep do dysku + Automatyzacja sa nadane dla kontekstu procesu uruchamiajacego OpenClaw/`imsg`.

Wskazowki referencji konfiguracji

• Referencja konfiguracji - iMessage
• Konfiguracja Gateway
• Parowanie
• BlueBubbles