iMessage

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

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.
• W przypadku zaawansowanych akcji (reakcja / edycja / cofnięcie wysłania / odpowiedź w wątku / efekty / operacje na grupach) funkcja System Integrity Protection musi być wyłączona — zobacz poniżej Włączanie prywatnego API imsg. Podstawowe wysyłanie/odbieranie tekstu i multimediów działa bez tego.

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

​

Włączanie prywatnego API imsg

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

Zaawansowane funkcje, takie jak read, typing, launch, rozbudowane wysyłanie wspierane przez bridge, mutacja wiadomości i zarządzanie czatami, są opcjonalne. Wymagają wyłączenia SIP oraz wstrzyknięcia pomocniczej biblioteki 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
   
   Wynik imsg status --json raportuje bridge_version, rpc_methods oraz selectors dla poszczególnych metod, dzięki czemu możesz sprawdzić, co obsługuje bieżąca kompilacja, zanim zaczniesz.
2. Wyłącz System Integrity Protection. Jest to zależne od wersji macOS, ponieważ podstawowe wymaganie Apple zależy od systemu operacyjnego i sprzętu:
   • macOS 10.13–10.15 (Sierra–Catalina): wyłącz Library Validation przez Terminal, uruchom ponownie w trybie Recovery Mode, uruchom csrutil disable, zrestartuj.
   • macOS 11+ (Big Sur i nowsze), Intel: Recovery Mode (albo Internet Recovery), csrutil disable, restart.
   • macOS 11+, Apple Silicon: sekwencja uruchamiania przyciskiem zasilania, aby wejść do Recovery; w nowszych wersjach macOS przytrzymaj klawisz Left Shift, gdy klikasz Continue, a następnie csrutil disable. Konfiguracje maszyn wirtualnych używają osobnej procedury — najpierw zrób snapshot VM.
   • macOS 26 / Tahoe: zasady library-validation i kontrole prywatnych uprawnień imagent zostały jeszcze bardziej zaostrzone; imsg może wymagać zaktualizowanej kompilacji, aby nadążyć. Jeśli po dużej aktualizacji macOS wstrzyknięcie imsg launch albo konkretne selectors zaczynają zwracać false, sprawdź informacje o wydaniu imsg, zanim uznasz, że krok SIP się powiódł.
   Wykonaj procedurę Apple dla trybu Recovery odpowiednią dla Twojego Maca, aby wyłączyć SIP przed uruchomieniem imsg launch.
3. Wstrzyknij helper. Przy wyłączonym SIP i zalogowanym Messages.app:
   imsg launch
   
   imsg launch odmawia wstrzyknięcia, gdy SIP nadal jest włączone, więc działa to również jako potwierdzenie, że krok 2 został wykonany.
4. Zweryfikuj bridge z OpenClaw:
   openclaw channels status --probe
   
   Wpis iMessage powinien raportować works, a imsg status --json | jq '.selectors' powinien pokazywać retractMessagePart: true oraz wszystkie selektory edycji / pisania / odczytu ujawniane przez Twoją kompilację macOS. Bramkowanie poszczególnych metod Pluginu OpenClaw w actions.ts reklamuje tylko akcje, których bazowy selektor ma wartość true, więc obszar akcji widoczny na liście narzędzi agenta odzwierciedla to, co bridge może faktycznie zrobić na tym hoście.

​

Gdy nie możesz wyłączyć SIP

• imsg wraca do trybu podstawowego — tylko tekst + multimedia + odbiór.
• Plugin OpenClaw nadal reklamuje wysyłanie tekstu/multimediów i monitorowanie przychodzące; po prostu ukrywa react, edit, unsend, reply, sendWithEffect oraz operacje na grupach z obszaru 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 poniżej Dedykowany użytkownik macOS bota (osobna tożsamość iMessage).

​

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 konwersacji ACP

• Uruchom /acp spawn codex --bind here w DM-ie lub dozwolonym czacie grupowym.
• Przyszłe wiadomości w tej samej konwersacji 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 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 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 "$@"

​

Multimedia, dzielenie i targety 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,
      },
    },
  },
}

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

​

Zapisy konfiguracji

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

​

Scalanie dzielonych wysyłek DM-ów (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: {
        // 2500 ms works for most setups; raise to 4000 ms if your Mac is
        // slow or under memory pressure (observed gap can stretch past 2 s
        // then).
        imessage: 2500,
      },
    },
  },
}

​

Scenariusze i to, co widzi agent

​

Nadrabianie po przestoju Gateway

channels: {
  imessage: {
    catchup: {
      enabled: true,             // master switch (default: false)
      maxAgeMinutes: 120,        // skip rows older than now - 2h (default: 120, clamp 1..720)
      perRunLimit: 50,           // max rows replayed per startup (default: 50, clamp 1..500)
      firstRunLookbackMinutes: 30, // first run with no cursor: look back 30 min (default: 30)
      maxFailureRetries: 10,     // give up on a wedged guid after 10 dispatch failures (default: 10)
    },
  },
}

​

Jak to działa

​

Semantyka kursora i ponawiania

{
  "lastSeenMs": 1717900800000,
  "lastSeenRowid": 482910,
  "updatedAt": 1717900801234,
  "failureRetries": { "<guid>": 1 }
}

• Kursor przesuwa się po każdym udanym wysłaniu i jest zatrzymywany, gdy wysłanie wiersza rzuci błąd — następne uruchomienie ponawia ten sam wiersz od zatrzymanego kursora.
• Po maxFailureRetries kolejnych rzutach błędu dla tego samego guid nadrabianie zapisuje warn i wymusza przesunięcie kursora poza zablokowaną wiadomość, aby kolejne uruchomienia mogły iść naprzód.
• GUID-y, dla których już się poddano, są pomijane po wykryciu (bez próby wysłania) w późniejszych uruchomieniach i liczone pod skippedGivenUp w podsumowaniu przebiegu.

​

Sygnały widoczne dla operatora

imessage catchup: replayed=N skippedFromMe=… skippedGivenUp=… failed=… givenUp=… fetchedCount=…
imessage catchup: giving up on guid=<guid> after <N> failures; advancing cursor past it
imessage catchup: fetched <X> rows across chats, capped to perRunLimit=<Y>

​

Kiedy pozostawić wyłączone

• Gateway działa ciągle z automatycznym restartem przez watchdog, a przerwy są zawsze krótsze niż kilka sekund — domyślne wyłączenie jest w porządku.
• Wolumen DM jest niski, a pominięte wiadomości nie zmieniłyby zachowania agenta — początkowe okno firstRunLookbackMinutes może wysłać zaskakujący stary kontekst przy pierwszym włączeniu.

​

Rozwiązywanie problemów

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

#!/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 referencji konfiguracji

• Referencja 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 instrukcja przełączenia 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