iMessage

Stato: integrazione CLI esterna nativa. Il Gateway avvia imsg rpc e comunica tramite JSON-RPC su stdio, senza daemon o porta separati. La modalità API privata è fortemente consigliata per un canale iMessage completo; risposte, tapback, effetti, sondaggi, risposte agli allegati e azioni di gruppo richiedono imsg launch e una verifica riuscita dell'API privata.

Per la comune configurazione locale, la procedura di configurazione di OpenClaw può proporre, previa conferma dell'utente, l'installazione o l'aggiornamento di imsg tramite Homebrew sul Mac con accesso effettuato a Messaggi. La configurazione manuale e le topologie con wrapper SSH restano a carico dell'operatore: installare o aggiornare imsg nello stesso contesto utente che eseguirà il Gateway o il wrapper.

Configurazione rapida

brew install steipete/tap/imsgbrew update && brew upgrade 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>

ssh messages-mac 'brew install steipete/tap/imsg && brew update && brew upgrade imsg'

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

{channels: {imessage: {  enabled: true,  cliPath: "~/.openclaw/scripts/imsg-ssh",  remoteHost: "user@gateway-host", // usato per recuperare gli allegati tramite SCP  includeAttachments: true,  // Facoltativo: ulteriori radici consentite per gli allegati (unite a quella  // predefinita /Users/*/Library/Messages/Attachments).  attachmentRoots: ["/Users/*/Library/Messages/Attachments"],  remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],},},}

Requisiti e autorizzazioni (macOS)

• Sul Mac che esegue imsg deve essere stato effettuato l'accesso a Messaggi.
• L'accesso completo al disco è obbligatorio per il contesto del processo che esegue OpenClaw/imsg (accesso al database di Messaggi).
• L'autorizzazione di automazione è obbligatoria per inviare messaggi tramite Messages.app.
• Per le azioni avanzate (reazione / modifica / annullamento dell'invio / risposta in thread / effetti / sondaggi / operazioni sui gruppi), la protezione dell'integrità del sistema deve essere disabilitata; vedere Abilitazione dell'API privata di imsg. L'invio e la ricezione di testo e contenuti multimediali di base funzionano senza disabilitarla.

Non autorizzato a inviare eventi Apple a Messaggi. (-1743)

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

Abilitazione dell'API privata di imsg

imsg viene distribuito con due modalità operative. Per OpenClaw, la modalità API privata è la configurazione consigliata perché fornisce al canale le azioni native di iMessage attese dagli utenti. La modalità di base resta utile per installazioni a basso rischio, per la verifica iniziale o per host sui quali non è possibile disabilitare SIP.

• Modalità di base (predefinita, non richiede modifiche a SIP): testo e contenuti multimediali in uscita tramite send, monitoraggio/cronologia in entrata, elenco delle chat. È quanto viene fornito immediatamente da una nuova installazione di brew install steipete/tap/imsg con le autorizzazioni macOS standard indicate sopra.
• Modalità API privata: imsg inserisce una dylib helper in Messages.app per chiamare funzioni interne di IMCore. Ciò abilita react, edit, unsend, reply (in thread), sendWithEffect, poll e poll-vote (sondaggi nativi di Messaggi), renameGroup, setGroupIcon, addParticipant, removeParticipant, leaveGroup, oltre agli indicatori di digitazione e alle conferme di lettura.

L'insieme di azioni consigliato in questa pagina richiede la modalità API privata. Il README di imsg indica esplicitamente il requisito:

Le funzionalità avanzate come read, typing, launch, invio avanzato supportato dal bridge, modifica dei messaggi e gestione delle chat sono facoltative. Richiedono che SIP sia disabilitato e che una dylib helper venga inserita in Messages.app. imsg launch rifiuta di eseguire l'inserimento quando SIP è abilitato.

La tecnica di inserimento dell'helper utilizza la dylib di imsg per accedere alle API private di Messaggi. Nel percorso iMessage di OpenClaw non sono presenti server di terze parti né un runtime BlueBubbles.

Configurazione

1. Installare (o aggiornare) imsg sul Mac che esegue Messages.app:

   brew install steipete/tap/imsgbrew update && brew upgrade imsgimsg --versionimsg status --json

   L'output di imsg status --json riporta bridge_version, rpc_methods e selectors per ciascun metodo, in modo da mostrare ciò che la build corrente supporta prima dell'avvio.

2. Disabilitare System Integrity Protection e, nelle versioni moderne di macOS, Library Validation. L'iniezione di una dylib ausiliaria non Apple nel componente firmato da Apple Messages.app richiede che SIP sia disabilitato e che la convalida delle librerie sia meno restrittiva. Il passaggio relativo a SIP in modalità di recupero dipende dalla versione di macOS:

   • macOS 10.13-10.15 (Sierra-Catalina): disabilitare Library Validation tramite Terminale, riavviare in modalità di recupero, eseguire csrutil disable, quindi riavviare.
   • macOS 11+ (Big Sur e versioni successive), Intel: accedere alla modalità di recupero (o al recupero via Internet), eseguire csrutil disable, quindi riavviare.
   • macOS 11+, Apple Silicon: usare la sequenza di avvio con il pulsante di accensione per accedere alla modalità di recupero; nelle versioni recenti di macOS tenere premuto il tasto Maiusc sinistro quando si fa clic su Continue, quindi eseguire csrutil disable. Le configurazioni delle macchine virtuali seguono una procedura separata, quindi creare prima uno snapshot della VM.

   Su macOS 11 e versioni successive, il solo comando csrutil disable di solito non è sufficiente. Apple continua ad applicare la convalida delle librerie a Messages.app in quanto binario della piattaforma, quindi un componente ausiliario con firma ad hoc viene rifiutato (Library Validation failed: ... platform binary, but mapped file is not) anche con SIP disabilitato. Dopo aver disabilitato SIP, disabilitare anche la convalida delle librerie e riavviare:

   sudo defaults write /Library/Preferences/com.apple.security.libraryvalidation.plist DisableLibraryValidation -bool true

   macOS 26 (Tahoe), verificato sulla versione 26.5.1: SIP disabilitato insieme al comando DisableLibraryValidation riportato sopra è sufficiente per iniettare il componente ausiliario dalle versioni 26.0 alla 26.5.x. Non sono necessari boot-args. Il plist è il fattore determinante e il passaggio mancante più comune quando l'iniezione non riesce su Tahoe:

   • Con il plist: imsg launch esegue l'iniezione e imsg status restituisce advanced_features: true.
   • Senza il plist (anche con SIP disabilitato): imsg launch non riesce e restituisce Failed to launch: Timeout waiting for Messages.app to initialize. AMFI rifiuta il componente ausiliario con firma ad hoc durante il caricamento, quindi il bridge non diventa mai pronto e l'avvio scade. Questo timeout è il sintomo riscontrato più spesso su Tahoe; la soluzione è il plist indicato sopra, non interventi più drastici.

   Se l'iniezione di imsg launch o specifiche funzionalità di selectors iniziano a restituire false dopo un aggiornamento di macOS, questo controllo è in genere la causa. Verificare lo stato di SIP e della convalida delle librerie prima di presumere che il passaggio relativo a SIP non sia riuscito. Se tali impostazioni sono corrette e il bridge non riesce comunque a eseguire l'iniezione, raccogliere imsg status --json insieme all'output di imsg launch e segnalarlo al progetto imsg, invece di indebolire ulteriori controlli di sicurezza a livello di sistema.

3. Iniettare il componente ausiliario. Con SIP disabilitato e l'accesso eseguito in Messages.app:

   imsg launch

   imsg launch rifiuta di eseguire l'iniezione se SIP è ancora abilitato, quindi questo comando funge anche da conferma dell'esecuzione del passaggio 2.

4. Verificare il bridge da OpenClaw:

   openclaw channels status --probe

   La voce iMessage dovrebbe restituire works e imsg status --json | jq '{rpc_methods, selectors}' dovrebbe mostrare le funzionalità esposte dalla build di macOS in uso. La creazione di sondaggi richiede selectors.pollPayloadMessage; la votazione richiede sia selectors.pollVoteMessage sia il metodo RPC poll.vote. Il plugin OpenClaw pubblicizza solo le azioni supportate dal probe memorizzato nella cache, mentre con una cache vuota mantiene un comportamento ottimistico ed esegue il probe al primo invio.

Se openclaw channels status --probe segnala il canale come works, ma azioni specifiche generano "iMessage <action> richiede il bridge API privato imsg" al momento dell'invio, eseguire nuovamente imsg launch: il componente ausiliario può disconnettersi (riavvio di Messages.app, aggiornamento del sistema operativo e così via) e lo stato available: true memorizzato nella cache continuerà a pubblicizzare le azioni finché il probe successivo non lo aggiornerà.

Quando SIP rimane abilitato

Se la disabilitazione di SIP non è accettabile per il proprio modello di minaccia:

• imsg passa alla modalità di base: solo testo, contenuti multimediali e ricezione.
• Il plugin OpenClaw continua a pubblicizzare l'invio di testo/contenuti multimediali e il monitoraggio in entrata; nasconde react, edit, unsend, reply, sendWithEffect e le operazioni di gruppo dalla superficie delle azioni, in base al controllo delle funzionalità per ciascun metodo.
• È possibile utilizzare un Mac separato non Apple Silicon (o un Mac dedicato al bot) con SIP disabilitato per il carico di lavoro iMessage, mantenendo SIP abilitato sui dispositivi principali. Consultare Utente macOS dedicato al bot (identità iMessage separata) più avanti.

Controllo degli accessi e instradamento

{  channels: {    imessage: {      groupPolicy: "allowlist",      groupAllowFrom: ["+15555550123"],      groups: {        "*": { systemPrompt: "Usa l'ortografia britannica." },        "8421": {          requireMention: true,          systemPrompt: "Questa è la chat del turno di reperibilità. Limita le risposte a meno di 3 frasi.",        },        "9907": {          // soppressione esplicita: il carattere jolly "Usa l'ortografia britannica." non si applica qui          systemPrompt: "",        },      },    },  },}

Associazioni delle conversazioni ACP

Le chat iMessage possono essere associate a sessioni ACP.

Procedura rapida per l'operatore:

• Eseguire /acp spawn codex --bind here all'interno del messaggio diretto o della chat di gruppo consentita.
• I messaggi successivi nella stessa conversazione iMessage vengono instradati alla sessione ACP avviata.
• /new e /reset reimpostano sul posto la stessa sessione ACP associata.
• /acp close chiude la sessione ACP e rimuove l'associazione.

Le associazioni persistenti configurate usano voci bindings[] di primo livello con type: "acp" e match.channel: "imessage".

match.peer.id può usare:

• un handle normalizzato per messaggi diretti, come +15555550123 o user@example.com
• chat_id:<id> (consigliato per associazioni 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" },    },  ],}

Consultare Agenti ACP per il comportamento condiviso delle associazioni ACP.

Modelli di distribuzione

{  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 bashexec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"

Contenuti multimediali, suddivisione e destinazioni di consegna

imsg chats --limit 20

Azioni dell'API privata

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

Tutte le azioni sono abilitate per impostazione predefinita; usare channels.imessage.actions per disabilitarle singolarmente:

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

Scritture della configurazione

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

Per disabilitarle:

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

Aggregazione dei DM con invio suddiviso (comando + URL in un'unica composizione)

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

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

Nella maggior parte delle configurazioni, le due righe arrivano a OpenClaw a circa 0.8-2.0 s di distanza. Senza aggregazione, l'agente riceve soltanto il comando nel turno 1 (e spesso risponde «inviami l'URL») prima che l'URL arrivi nel turno 2. Ciò dipende dalla pipeline di invio di Apple, non da OpenClaw né da imsg.

channels.imessage.coalesceSameSenderDms abilita per un DM il buffering delle righe consecutive dello stesso mittente. Quando imsg espone il marcatore strutturale dell'anteprima URL balloon_bundle_id: "com.apple.messages.URLBalloonProvider" in una delle righe di origine, OpenClaw unisce soltanto quell'effettivo invio suddiviso e mantiene tutte le altre righe nel buffer come turni distinti. Nelle build imsg meno recenti, che non emettono alcun metadato del fumetto, OpenClaw non può distinguere un invio suddiviso da invii separati, quindi ripiega sull'unione del gruppo. In questo modo viene mantenuto il comportamento precedente all'introduzione dei metadati, anziché trasformare gli invii suddivisi Dump <url> in due turni. Le chat di gruppo continuano a distribuire ogni messaggio separatamente, preservando la struttura dei turni tra più utenti.

{  channels: {    imessage: {      coalesceSameSenderDms: true, // abilitazione esplicita (valore predefinito: false)    },  },}

{  messages: {    inbound: {      byChannel: {        // 7000 ms coprono i ritardi osservati delle anteprime URL di Messages.app.        imessage: 7000,      },    },  },}

Scenari e contenuto ricevuto dall'agente

La colonna «Flag attivo» mostra il comportamento su una build imsg che emette balloon_bundle_id. Nelle build imsg meno recenti che non emettono alcun metadato del fumetto, le righe indicate di seguito come «Due turni»/«N turni» ricadono invece in un'unione legacy (un solo turno): OpenClaw non può distinguere strutturalmente un invio suddiviso da invii separati, quindi mantiene l'unione precedente all'introduzione dei metadati. La separazione precisa si attiva quando la build emette i metadati del fumetto.

Ripristino dei messaggi in ingresso dopo il riavvio di un bridge o del Gateway

iMessage recupera i messaggi persi mentre il Gateway era inattivo e, allo stesso tempo, elimina la vecchia «raffica di arretrati» che Apple può riversare dopo un ripristino Push. Il comportamento predefinito è sempre attivo e si basa sulla deduplicazione dei messaggi in ingresso.

• Deduplicazione della riproduzione. Ogni messaggio in ingresso distribuito viene registrato tramite il relativo GUID Apple nello stato persistente del Plugin (imessage.inbound-dedupe), acquisito durante l'ingestione e confermato dopo la gestione (rilasciato in caso di errore transitorio, affinché possa essere riprovato). Tutto ciò che è già stato gestito viene eliminato anziché essere distribuito due volte. Questo consente al ripristino di riprodurre in modo aggressivo senza una contabilità per singolo messaggio.
• Ripristino dopo l'inattività. All'avvio, il monitor memorizza l'ultimo rowid chat.db distribuito (un cursore persistente per account) e lo passa a imsg watch.subscribe come since_rowid, affinché imsg riproduca le righe arrivate mentre il Gateway era inattivo e poi prosegua con quelle in tempo reale. La riproduzione è limitata alle 500 righe più recenti e ai messaggi risalenti al massimo a circa 2 ore prima; la deduplicazione elimina tutto ciò che è già stato gestito.
• Limite temporale per gli arretrati obsoleti. Le righe oltre il limite di avvio sono effettivamente in tempo reale; una riga la cui data di invio precede di oltre circa 15 minuti quella di arrivo appartiene agli arretrati riversati da Push e viene eliminata. Le righe riprodotte (in corrispondenza o al di sotto del limite) utilizzano invece la finestra di ripristino più ampia, così un messaggio perso di recente viene consegnato, mentre la cronologia remota non lo è.

Il ripristino funziona sia con le configurazioni cliPath locali sia con quelle remote, perché la riproduzione since_rowid viene eseguita tramite la stessa connessione RPC imsg. La differenza risiede nella finestra: quando il Gateway può leggere chat.db (in locale), fissa il limite del rowid di avvio, limita l'intervallo di riproduzione e consegna i messaggi persi risalenti al massimo a un paio d'ore prima. Tramite una connessione SSH cliPath remota, non può leggere il database, quindi la riproduzione non è limitata e ogni riga utilizza il limite temporale in tempo reale: recupera comunque i messaggi persi di recente ed elimina comunque gli arretrati obsoleti, ma con la finestra in tempo reale più ristretta. Per usufruire della finestra di ripristino più ampia, eseguire il Gateway sul Mac che ospita Messaggi.

Segnale visibile all'operatore

Gli arretrati eliminati vengono registrati al livello predefinito e non vengono mai ignorati silenziosamente (il flag recovery indica quale finestra è stata applicata):

imessage: arretrato obsoleto in ingresso eliminato account=<id> inviato=<iso> ripristino=<bool> (&lt;N&gt; eliminati dall'avvio)

Migrazione

channels.imessage.catchup.* è deprecato: il ripristino dopo l'inattività è automatico e non richiede alcuna configurazione per le nuove installazioni. Le configurazioni esistenti con catchup.enabled: true continuano a essere rispettate come profilo di compatibilità per la finestra di riproduzione del ripristino. I blocchi di recupero disabilitati (enabled: false o senza enabled: true) sono stati ritirati; openclaw doctor --fix li rimuove.

Risoluzione dei problemi

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

imsg chats --limit 10 --jsonimsg watch --chat-id <chat-id> --jsonsqlite3 ~/Library/Messages/chat.db \"select datetime(max(date)/1000000000 + 978307200, 'unixepoch', 'localtime'), max(ROWID) from message;"

launchctl kickstart -k system/com.apple.apsdlaunchctl kickstart -k gui/$(id -u)/com.apple.CommCenterlaunchctl kickstart -k gui/$(id -u)/com.apple.identityservicesdlaunchctl kickstart -k gui/$(id -u)/com.apple.imagentimsg launchopenclaw gateway restart

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

openclaw channels status --probe --channel imessage

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

Riferimenti per la configurazione

• Riferimento per la configurazione - iMessage
• Configurazione del Gateway
• Associazione

Contenuti correlati

• Panoramica dei canali — tutti i canali supportati
• Rimozione di BlueBubbles e percorso iMessage con imsg — annuncio e riepilogo della migrazione
• Migrazione da BlueBubbles — tabella di conversione della configurazione e passaggio graduale
• Associazione — autenticazione dei messaggi diretti e flusso di associazione
• Gruppi — comportamento delle chat di gruppo e controllo tramite menzione
• Instradamento dei canali — instradamento delle sessioni per i messaggi
• Sicurezza — modello di accesso e rafforzamento della sicurezza