iMessage

Stato: integrazione CLI esterna nativa. Gateway avvia imsg rpc e comunica tramite JSON-RPC su stdio (nessun daemon/porta separati). Le azioni avanzate richiedono imsg launch e una verifica riuscita dell'API privata.

Configurazione rapida

brew install steipete/tap/imsgimsg rpc --helpimsg launchopenclaw channels status --probe

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

openclaw gateway

openclaw pairing list imessageopenclaw pairing approve imessage <CODE>

#!/usr/bin/env bashexec 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"],},},}

Requisiti e autorizzazioni (macOS)

• Messages deve avere l'accesso effettuato sul Mac che esegue imsg.
• È richiesto Accesso completo al disco per il contesto di processo che esegue OpenClaw/imsg (accesso al DB di Messages).
• È richiesta l'autorizzazione Automazione per inviare messaggi tramite Messages.app.
• Per le azioni avanzate (reazione / modifica / annullamento invio / risposta in thread / effetti / operazioni sui gruppi), System Integrity Protection deve essere disabilitata — vedi Abilitazione dell'API privata imsg sotto. L'invio/ricezione di testo e contenuti multimediali di base funziona senza.

Abilitazione dell'API privata imsg

imsg viene distribuito in due modalità operative:

• Modalità base (predefinita, non sono necessarie modifiche a SIP): testo e contenuti multimediali in uscita tramite send, monitoraggio/cronologia in ingresso, elenco chat. È ciò che ottieni subito con una nuova installazione brew install steipete/tap/imsg più le autorizzazioni macOS standard indicate sopra.
• Modalità API privata: imsg inietta una dylib helper in Messages.app per chiamare funzioni interne di IMCore. Questo sblocca react, edit, unsend, reply (in thread), sendWithEffect, renameGroup, setGroupIcon, addParticipant, removeParticipant, leaveGroup, oltre agli indicatori di digitazione e alle conferme di lettura.

Per accedere alla superficie di azioni avanzate documentata in questa pagina del canale, ti serve la modalità API privata. Il README di imsg è esplicito sul requisito:

Funzionalità avanzate come read, typing, launch, invio avanzato basato su bridge, mutazione dei messaggi e gestione delle chat sono facoltative. Richiedono che SIP sia disabilitato e che una dylib helper venga iniettata in Messages.app. imsg launch rifiuta l'iniezione quando SIP è abilitato.

La tecnica di iniezione dell'helper usa la dylib di imsg per raggiungere le API private di Messages. Nel percorso iMessage di OpenClaw non c'è alcun server di terze parti o runtime BlueBubbles.

Configurazione

1. Installa (o aggiorna) imsg sul Mac che esegue Messages.app:

   brew install steipete/tap/imsgimsg --versionimsg status --json

   L'output di imsg status --json riporta bridge_version, rpc_methods e i selectors per metodo, così puoi vedere cosa supporta la build corrente prima di iniziare.

2. Disabilita System Integrity Protection. Questo dipende dalla versione di macOS perché il requisito Apple sottostante dipende dal sistema operativo e dall'hardware:

   • macOS 10.13–10.15 (Sierra–Catalina): disabilita Library Validation tramite Terminale, riavvia in Recovery Mode, esegui csrutil disable, riavvia.
   • macOS 11+ (Big Sur e successivi), Intel: Recovery Mode (o Internet Recovery), csrutil disable, riavvia.
   • macOS 11+, Apple Silicon: sequenza di avvio con il pulsante di accensione per entrare in Recovery; nelle versioni recenti di macOS tieni premuto il tasto Shift sinistro quando fai clic su Continua, poi csrutil disable. Le configurazioni con macchine virtuali seguono un flusso separato — crea prima uno snapshot della VM.
   • macOS 26 / Tahoe: le policy di convalida delle librerie e i controlli di entitlement privati di imagent sono stati ulteriormente irrigiditi; imsg potrebbe richiedere una build aggiornata per restare compatibile. Se l'iniezione di imsg launch o selectors specifici iniziano a restituire false dopo un aggiornamento major di macOS, controlla le note di rilascio di imsg prima di presumere che il passaggio SIP sia riuscito.

   Segui il flusso Recovery Mode di Apple per il tuo Mac per disabilitare SIP prima di eseguire imsg launch.

3. Inietta l'helper. Con SIP disabilitato e accesso effettuato in Messages.app:

   imsg launch

   imsg launch rifiuta l'iniezione quando SIP è ancora abilitato, quindi funge anche da conferma che il passaggio 2 ha avuto effetto.

4. Verifica il bridge da OpenClaw:

   openclaw channels status --probe

   La voce iMessage dovrebbe riportare works, e imsg status --json | jq '.selectors' dovrebbe mostrare retractMessagePart: true più gli eventuali selettori di modifica / digitazione / lettura esposti dalla tua build macOS. Il gating per metodo del plugin OpenClaw in actions.ts pubblicizza solo azioni il cui selettore sottostante è true, quindi la superficie di azioni che vedi nell'elenco strumenti dell'agente riflette ciò che il bridge può effettivamente fare su questo host.

Se openclaw channels status --probe riporta il canale come works ma azioni specifiche generano "iMessage <action> requires the imsg private API bridge" al momento del dispatch, esegui di nuovo imsg launch — l'helper può disattivarsi (riavvio di Messages.app, aggiornamento del sistema operativo, ecc.) e lo stato memorizzato nella cache available: true continuerà a pubblicizzare le azioni finché la prossima verifica non lo aggiorna.

Quando non puoi disabilitare SIP

Se SIP disabilitato non è accettabile per il tuo modello di minaccia:

• imsg torna alla modalità base — solo testo + contenuti multimediali + ricezione.
• Il plugin OpenClaw continua a pubblicizzare l'invio di testo/media e il monitoraggio in ingresso; nasconde solo react, edit, unsend, reply, sendWithEffect e le operazioni sui gruppi dalla superficie di azioni (secondo il gate di capacità per metodo).
• Puoi eseguire un Mac non Apple Silicon separato (o un Mac dedicato al bot) con SIP disattivato per il carico iMessage, mantenendo SIP abilitato sui dispositivi principali. Vedi Utente macOS dedicato al bot (identità iMessage separata) sotto.

Controllo degli accessi e instradamento

{  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: "",        },      },    },  },}

Binding delle conversazioni ACP

Le chat iMessage legacy possono anche essere associate a sessioni ACP.

Flusso rapido per l'operatore:

• Esegui /acp spawn codex --bind here dentro il DM o la chat di gruppo consentita.
• I messaggi futuri nella stessa conversazione iMessage vengono instradati alla sessione ACP generata.
• /new e /reset reimpostano la stessa sessione ACP associata sul posto.
• /acp close chiude la sessione ACP e rimuove il binding.

I binding persistenti configurati sono supportati tramite voci bindings[] di primo livello con type: "acp" e match.channel: "imessage".

match.peer.id può usare:

• handle DM normalizzato come +15555550123 o [email protected]
• chat_id:<id> (consigliato per binding di gruppo stabili)
• chat_guid:<guid>
• chat_identifier:<identifier>

Esempio:

{  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" },    },  ],}

Vedi Agenti ACP per il comportamento condiviso dei binding ACP.

Pattern di distribuzione

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

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

Media, suddivisione in blocchi e target di consegna

imsg chats --limit 20

Azioni API private

Quando imsg launch è in esecuzione e openclaw channels status --probe riporta privateApi.available: true, lo strumento di messaggistica può usare azioni native di iMessage oltre ai normali invii di testo.

{  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,    },  },}

Scritture di configurazione

iMessage consente per impostazione predefinita le scritture di configurazione avviate dal canale (per /config set|unset quando commands.config: true).

Disabilita:

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

Coalescing dei DM inviati in modo suddiviso (comando + URL in un'unica composizione)

Quando un utente digita insieme un comando e un URL, per esempio Dump https://example.com/article, l'app Messaggi di Apple divide l'invio in due righe chat.db separate:

1. Un messaggio di testo ("Dump").
2. Un fumetto di anteprima URL ("https://...") con immagini di anteprima OG come allegati.

Le due righe arrivano a OpenClaw a circa 0,8-2,0 s di distanza nella maggior parte delle configurazioni. Senza aggregazione, l'agente riceve il comando da solo al turno 1, risponde (spesso "mandami l'URL") e vede l'URL solo al turno 2, quando il contesto del comando è già perso. Questo dipende dalla pipeline di invio di Apple, non da qualcosa introdotto da OpenClaw o imsg.

channels.imessage.coalesceSameSenderDms fa sì che un DM unisca righe consecutive dello stesso mittente in un singolo turno dell'agente. Le chat di gruppo continuano a essere inviate per messaggio, così la struttura dei turni multiutente viene preservata.

{  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,      },    },  },}

Scenari e cosa vede l'agente

Recupero dopo inattività del gateway

Quando il gateway è offline (crash, riavvio, sleep del Mac, macchina spenta), imsg watch riprende dallo stato corrente di chat.db quando il gateway torna attivo: qualsiasi cosa arrivata durante l'intervallo, per impostazione predefinita, non viene mai vista. Il recupero riproduce quei messaggi al successivo avvio, così l'agente non perde silenziosamente il traffico in ingresso.

Il recupero è disabilitato per impostazione predefinita. Abilitalo per canale:

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)    },  },}

Come viene eseguito

Un passaggio per ogni avvio di monitorIMessageProvider, sequenziato come imsg launch pronto → watch.subscribe → performIMessageCatchup → ciclo di invio live. Il recupero usa chats.list + messages.history per chat tramite lo stesso client JSON-RPC usato da imsg watch. Tutto ciò che arriva durante il passaggio di recupero attraversa normalmente l'invio live; la cache di deduplicazione in ingresso esistente assorbe qualsiasi sovrapposizione con le righe riprodotte.

Ogni riga riprodotta viene inoltrata attraverso il percorso di invio live (evaluateIMessageInbound + dispatchInboundMessage), quindi allowlist, criteri di gruppo, debouncer, cache echo e conferme di lettura si comportano in modo identico sui messaggi riprodotti e live.

Semantica di cursore e tentativi

Il recupero mantiene un cursore per account in <openclawStateDir>/imessage/catchup/<account>__<hash>.json (la directory di stato di OpenClaw è ~/.openclaw per impostazione predefinita, sovrascrivibile con OPENCLAW_STATE_DIR):

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

• Il cursore avanza a ogni invio riuscito e resta fermo quando l'invio di una riga genera un'eccezione: l'avvio successivo riprova la stessa riga dal cursore trattenuto.
• Dopo maxFailureRetries eccezioni consecutive sullo stesso guid, il recupero registra un warn e forza l'avanzamento del cursore oltre il messaggio bloccato, così gli avvii successivi possono progredire.
• I guid già abbandonati vengono saltati a vista (senza tentativo di invio) nelle esecuzioni successive e conteggiati sotto skippedGivenUp nel riepilogo dell'esecuzione.

Segnali visibili all'operatore

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

Una riga WARN ... capped to perRunLimit significa che un singolo avvio non ha svuotato tutto il backlog. Aumenta perRunLimit (massimo 500) se i tuoi intervalli superano regolarmente il passaggio predefinito da 50 righe.

Quando lasciarlo disattivato

• Il Gateway viene eseguito continuamente con riavvio automatico tramite watchdog e gli intervalli sono sempre < pochi secondi: il valore predefinito disattivato va bene.
• Il volume DM è basso e i messaggi persi non cambierebbero il comportamento dell'agente: la finestra iniziale firstRunLookbackMinutes può inviare contesto vecchio inatteso alla prima abilitazione.

Quando attivi il recupero, il primo avvio senza cursore guarda indietro solo di firstRunLookbackMinutes (30 min per impostazione predefinita), non per l'intera finestra maxAgeMinutes: questo evita di riprodurre una lunga cronologia di messaggi precedenti all'abilitazione.

Risoluzione dei problemi

imsg rpc --helpimsg status --jsonopenclaw channels status --probe

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

openclaw channels status --probe --channel imessage

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

Riferimenti alla configurazione

• Riferimento di configurazione - iMessage
• Configurazione del Gateway
• Pairing

Correlati

• Panoramica dei canali — tutti i canali supportati
• Rimozione di BlueBubbles e percorso iMessage con imsg — annuncio e riepilogo della migrazione
• Provenienza da BlueBubbles — tabella di traduzione della configurazione e passaggio guidato
• Pairing — autenticazione DM e flusso di pairing
• Gruppi — comportamento delle chat di gruppo e gating delle menzioni
• Routing dei canali — routing della sessione per i messaggi
• Sicurezza — modello di accesso e hardening