​

iMessage (legacy: imsg)

Zalecane: Do nowych konfiguracji iMessage używaj BlueBubbles. Kanał imsg jest starszą integracją zewnętrznego CLI i może zostać usunięty w przyszłej wersji.

​

Szybka konfiguracja (dla początkujących)

1. Upewnij się, że aplikacja Messages jest zalogowana na tym Macu.
2. Zainstaluj imsg:
   • brew install steipete/tap/imsg
3. Skonfiguruj OpenClaw z channels.imessage.cliPath i channels.imessage.dbPath.
4. Uruchom gateway i zatwierdź wszystkie monity macOS (Automatyzacja + Pełny dostęp do dysku).

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

​

Czym to jest

• Kanał iMessage oparty na imsg w systemie macOS.
• Deterministyczne routowanie: odpowiedzi zawsze wracają do iMessage.
• DM-y współdzielą główną sesję agenta; grupy są izolowane (agent:<agentId>:imessage:group:<chat_id>).
• Jeśli wątek z wieloma uczestnikami dotrze z is_group=false, nadal możesz go izolować, chat_id używając channels.imessage.groups (zobacz „Wątki typu grupowego” poniżej).

​

Zapisy konfiguracji

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

​

Wymagania

• macOS z zalogowaną aplikacją Messages.
• Pełny dostęp do dysku dla OpenClaw + imsg (dostęp do bazy danych Messages).
• Uprawnienie Automatyzacji podczas wysyłania.
• channels.imessage.cliPath może wskazywać dowolne polecenie, które pośredniczy stdin/stdout (na przykład skrypt opakowujący, który łączy się przez SSH z innym Makiem i uruchamia imsg rpc).

​

Rozwiązywanie problemów z macOS Privacy and Security TCC

• Pełny dostęp do dysku: zezwól na dostęp procesowi uruchamiającemu OpenClaw (oraz wszelkim powłokom/opakowaniom SSH, które wykonują imsg). Jest to wymagane do odczytu bazy danych Messages (chat.db).
• Automatyzacja → Messages: zezwól procesowi uruchamiającemu OpenClaw (i/lub terminalowi) na kontrolowanie Messages.app w celu wysyłania wychodzących.
• Stan zdrowia CLI imsg: sprawdź, czy imsg jest zainstalowane i obsługuje RPC (imsg rpc --help).

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

​

Konfiguracja (szybka ścieżka)

1. Upewnij się, że aplikacja Messages jest zalogowana na tym Macu.
2. Skonfiguruj iMessage i uruchom gateway.

​

Dedykowany użytkownik macOS dla bota (dla izolowanej tożsamości)

1. Utwórz dedykowane Apple ID (przykład: [email protected]).
   • Apple może wymagać numeru telefonu do weryfikacji / 2FA.
2. Utwórz użytkownika macOS (przykład: openclawhome) i zaloguj się do niego.
3. Otwórz Messages na tym użytkowniku macOS i zaloguj się do iMessage przy użyciu Apple ID bota.
4. Włącz Zdalne logowanie (Ustawienia systemowe → Ogólne → Udostępnianie → Zdalne logowanie).
5. Zainstaluj imsg:
   • brew install steipete/tap/imsg
6. Skonfiguruj SSH tak, aby ssh <bot-macos-user>@localhost true działało bez hasła.
7. Ustaw channels.imessage.accounts.bot.cliPath na opakowanie SSH, które uruchamia imsg jako użytkownik bota.

#!/usr/bin/env bash
set -euo pipefail

# Run an interactive SSH once first to accept host keys:
#   ssh <bot-macos-user>@localhost true
exec /usr/bin/ssh -o BatchMode=yes -o ConnectTimeout=5 -T <bot-macos-user>@localhost \
  "/usr/local/bin/imsg" "$@"

{
  channels: {
    imessage: {
      enabled: true,
      accounts: {
        bot: {
          name: "Bot",
          enabled: true,
          cliPath: "/path/to/imsg-bot",
          dbPath: "/Users/<bot-macos-user>/Library/Messages/chat.db",
        },
      },
    },
  },
}

​

Wariant zdalny/SSH (opcjonalny)

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

{
  channels: {
    imessage: {
      cliPath: "~/imsg-ssh", // SSH wrapper to remote Mac
      remoteHost: "user@gateway-host", // for SCP file transfer
      includeAttachments: true,
    },
  },
}

​

Zdalny Mac przez Tailscale (przykład)

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

• Upewnij się, że Mac jest zalogowany do Messages, a Zdalne logowanie jest włączone.
• Użyj kluczy SSH, aby ssh [email protected] działało bez monitów.
• remoteHost powinno odpowiadać celowi SSH, aby SCP mogło pobierać załączniki.

​

Kontrola dostępu (DM-y + grupy)

• Domyślnie: channels.imessage.dmPolicy = "pairing".
• Nieznani nadawcy otrzymują kod parowania; wiadomości są ignorowane do czasu zatwierdzenia (kody wygasają po 1 godzinie).
• Zatwierdzanie przez:
  • openclaw pairing list imessage
  • openclaw pairing approve imessage <CODE>
• Parowanie jest domyślną wymianą tokenów dla DM-ów iMessage. Szczegóły: Parowanie

• channels.imessage.groupPolicy = open | allowlist | disabled.
• channels.imessage.groupAllowFrom kontroluje, kto może wyzwalać w grupach, gdy ustawione jest allowlist.
• Bramka wzmianek używa agents.list[].groupChat.mentionPatterns (lub messages.groupChat.mentionPatterns), ponieważ iMessage nie ma natywnych metadanych wzmianek.
• Nadpisanie wieloagentowe: ustaw wzorce per agent w agents.list[].groupChat.mentionPatterns.

​

Jak to działa (zachowanie)

• imsg strumieniuje zdarzenia wiadomości; gateway normalizuje je do wspólnej koperty kanału.
• Odpowiedzi zawsze wracają do tego samego identyfikatora czatu lub uchwytu.

​

Wątki typu grupowego (is_group=false)

• izolacji sesji (oddzielny klucz sesji agent:<agentId>:imessage:group:<chat_id>)
• list dozwolonych dla grup / zachowania bramkowania wzmianek

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

​

Media + limity

• Opcjonalne wczytywanie załączników przez channels.imessage.includeAttachments.
• Limit mediów przez channels.imessage.mediaMaxMb.

​

Limity

• Tekst wychodzący jest dzielony na fragmenty do channels.imessage.textChunkLimit (domyślnie 4000).
• Opcjonalne dzielenie po nowych liniach: ustaw channels.imessage.chunkMode="newline", aby dzielić po pustych liniach (granice akapitów) przed dzieleniem według długości.
• Wysyłanie mediów jest ograniczone przez channels.imessage.mediaMaxMb (domyślnie 16).

​

Adresowanie / cele dostarczania

• chat_id:123 (preferowane)
• chat_guid:...
• chat_identifier:...
• bezpośrednie uchwyty: imessage:+1555 / sms:+1555 / [email protected]

imsg chats --limit 20

​

Referencja konfiguracji (iMessage)

• channels.imessage.enabled: włącz/wyłącz uruchamianie kanału.
• channels.imessage.cliPath: ścieżka do imsg.
• channels.imessage.dbPath: ścieżka bazy danych Messages.
• channels.imessage.remoteHost: host SSH dla transferu załączników przez SCP, gdy cliPath wskazuje zdalnego Maca (np. user@gateway-host). Automatycznie wykrywane z opakowania SSH, jeśli nie ustawione.
• channels.imessage.service: imessage | sms | auto.
• channels.imessage.region: region SMS.
• channels.imessage.dmPolicy: pairing | allowlist | open | disabled (domyślnie: parowanie).
• channels.imessage.allowFrom: lista dozwolonych DM-ów (uchwyty, e-maile, numery E.164 lub chat_id:*). open wymaga "*". iMessage nie ma nazw użytkowników; używaj uchwytów lub celów czatu.
• channels.imessage.groupPolicy: open | allowlist | disabled (domyślnie: lista dozwolonych).
• channels.imessage.groupAllowFrom: lista dozwolonych nadawców w grupach.
• channels.imessage.historyLimit / channels.imessage.accounts.*.historyLimit: maksymalna liczba wiadomości grupowych do włączenia jako kontekst (0 wyłącza).
• channels.imessage.dmHistoryLimit: limit historii DM w turach użytkownika. Nadpisania per użytkownik: channels.imessage.dms["<handle>"].historyLimit.
• channels.imessage.groups: domyślne ustawienia per grupa + lista dozwolonych (użyj "*" dla globalnych domyślnych).
• channels.imessage.includeAttachments: wczytywanie załączników do kontekstu.
• channels.imessage.mediaMaxMb: limit mediów przychodzących/wychodzących (MB).
• channels.imessage.textChunkLimit: rozmiar fragmentu wychodzącego (znaki).
• channels.imessage.chunkMode: length (domyślne) lub newline do dzielenia po pustych liniach (granice akapitów) przed dzieleniem według długości.

• agents.list[].groupChat.mentionPatterns (lub messages.groupChat.mentionPatterns).
• messages.responsePrefix.