iMessage

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

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.
• Full Disk Access è richiesto per il contesto di processo che esegue OpenClaw/imsg (accesso al database di Messages).
• L'autorizzazione Automation è richiesta per inviare messaggi tramite Messages.app.
• Per le azioni avanzate (react / edit / unsend / threaded reply / effects / polls / group ops), System Integrity Protection deve essere disabilitata: vedi Abilitare l'API privata imsg di seguito. L'invio/ricezione di testo e contenuti multimediali di base funziona senza.

Not authorized to send Apple events to Messages. (-1743)

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

Abilitare l'API privata imsg

imsg viene distribuito con due modalità operative:

• Modalità di base (predefinita, nessuna modifica SIP necessaria): testo e contenuti multimediali in uscita tramite send, watch/history in ingresso, elenco chat. Questo è ciò che ottieni subito da 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 IMCore. Questo sblocca react, edit, unsend, reply (con thread), sendWithEffect, poll e poll-vote (sondaggi nativi di Messages), renameGroup, setGroupIcon, addParticipant, removeParticipant, leaveGroup, oltre a indicatori di digitazione e conferme di lettura.

Per raggiungere la superficie di azioni avanzate documentata in questa pagina del canale, hai bisogno della modalità API privata. Il README di imsg è esplicito sul requisito:

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

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

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 selectors per metodo, così puoi vedere cosa supporta la build corrente prima di iniziare.

2. Disabilita System Integrity Protection e (su macOS moderni) Library Validation. L'iniezione di una dylib helper non Apple nella Messages.app firmata da Apple richiede SIP disattivata e la convalida delle librerie allentata. Il passaggio SIP in modalità Recovery è specifico per versione macOS:

   • 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 pulsante di accensione per entrare in Recovery; nelle versioni macOS recenti tieni premuto il tasto Left Shift quando fai clic su Continue, poi csrutil disable. Le configurazioni con macchina virtuale seguono un flusso separato, quindi crea prima uno snapshot della VM.

   Su macOS 11 e successivi, di solito csrutil disable da solo non basta. Apple continua ad applicare la convalida delle librerie a Messages.app come binario di piattaforma, quindi un helper firmato ad hoc viene rifiutato (Library Validation failed: ... platform binary, but mapped file is not) anche con SIP disattivata. Dopo aver disabilitato SIP, disabilita anche la convalida delle librerie e riavvia:

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

   macOS 26 (Tahoe), verificato su 26.5.1: SIP disattivata più il comando DisableLibraryValidation sopra è sufficiente per iniettare l'helper da 26.0 a 26.5.x. Non sono richiesti boot-args. Il plist è il fattore decisivo e il passaggio mancante più comune quando l'iniezione fallisce su Tahoe:

   • Con il plist: imsg launch inietta e imsg status riporta advanced_features: true.
   • Senza il plist (anche con SIP disattivata): imsg launch fallisce con Failed to launch: Timeout waiting for Messages.app to initialize. AMFI rifiuta l'helper ad hoc al caricamento, quindi il bridge non diventa mai pronto e l'avvio va in timeout. Quel timeout è il sintomo che la maggior parte delle persone incontra su Tahoe, e la correzione è il plist sopra, non qualcosa di più drastico.

   Questo è stato confermato con un prima/dopo controllato su macOS 26.5.1 (Apple Silicon): con il plist, la dylib viene mappata in Messages.app e il bridge si avvia; rimuovi il plist e riavvia, e imsg launch produce l'errore di timeout sopra con la dylib non mappata.

   Se l'iniezione di imsg launch o specifici selectors iniziano a restituire false dopo un aggiornamento di macOS, questo gate è la causa più comune. Controlla lo stato di SIP e della convalida delle librerie prima di presumere che il passaggio SIP stesso sia fallito. Se queste impostazioni sono corrette e il bridge non riesce ancora a eseguire l'iniezione, raccogli imsg status --json insieme all'output di imsg launch e segnalalo al progetto imsg invece di indebolire ulteriori controlli di sicurezza a livello di sistema.

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

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

   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 '{rpc_methods, selectors}' dovrebbe mostrare le capacità esposte dalla tua build di macOS. La creazione di sondaggi richiede selectors.pollPayloadMessage; il voto richiede sia selectors.pollVoteMessage sia il metodo RPC poll.vote. Il Plugin OpenClaw pubblicizza solo le azioni supportate dalla probe memorizzata nella cache, mentre una cache vuota resta ottimistica ed esegue la probe al primo dispatch.

Se openclaw channels status --probe segnala 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 available: true nella cache continuerà a pubblicizzare le azioni finché la probe successiva non lo aggiorna.

Quando non puoi disabilitare SIP

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

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

Controllo degli accessi e routing

{  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 di conversazione ACP

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

Flusso rapido per operatori:

• Esegui /acp spawn codex --bind here dentro il DM o la chat di gruppo consentita.
• I messaggi futuri in quella 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 user@example.com
• 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: "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 "$@"

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 segnala 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,        polls: true,      },    },  },}

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

Scritture di configurazione

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

Disattiva:

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

Coalescenza dei DM con invio diviso (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 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 coalescenza, l'agente riceve solo il comando al turno 1, risponde (spesso "send me the URL") e vede l'URL solo al turno 2 — quando il contesto del comando è già perso. Questo è il flusso di invio di Apple, non qualcosa introdotto da OpenClaw o imsg.

channels.imessage.coalesceSameSenderDms abilita per un DM il buffering di righe consecutive dello stesso mittente. Quando imsg espone il marcatore strutturale dell'anteprima URL balloon_bundle_id: "com.apple.messages.URLBalloonProvider" su una delle righe sorgente, OpenClaw unisce solo quel vero invio diviso e mantiene eventuali altre righe in buffer come turni separati. Nelle build imsg più vecchie che non emettono affatto metadati del fumetto, OpenClaw non può distinguere un invio diviso da invii separati, quindi ripiega sull'unione del bucket. Questo preserva il comportamento precedente ai metadati invece di far regredire gli invii divisi Dump <url> in due turni. 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: {        // 7000 ms covers observed Messages.app URL-preview delays.        imessage: 7000,      },    },  },}

Scenari e cosa vede l'agente

La colonna "Flag attivo" mostra il comportamento su una build imsg che emette balloon_bundle_id. Nelle build imsg più vecchie che non emettono alcun metadato balloon, le righe sotto contrassegnate come "Due turni" / "N turni" ricadono invece in un merging legacy (un turno): OpenClaw non può distinguere strutturalmente un invio suddiviso da invii separati, quindi preserva il merge precedente ai metadati. La separazione precisa si attiva quando la build emette metadati balloon.

Recupero inbound dopo un riavvio del bridge o del Gateway

iMessage recupera i messaggi persi mentre il Gateway era inattivo e, allo stesso tempo, sopprime la vecchia "bomba di backlog" che Apple può svuotare dopo un recupero Push. Il comportamento predefinito è sempre attivo, costruito sulla deduplicazione inbound.

• Deduplicazione replay. Ogni messaggio inbound sottoposto a dispatch viene registrato tramite il suo GUID Apple nello stato persistente del Plugin (imessage.inbound-dedupe), reclamato all'ingestione e confermato dopo la gestione (rilasciato in caso di errore transitorio, così può essere ritentato). Tutto ciò che è già stato gestito viene scartato invece di essere inviato due volte. È questo che permette al recupero di eseguire replay aggressivi senza bookkeeping per messaggio.
• Recupero del downtime. All'avvio, il monitor ricorda l'ultimo rowid chat.db inviato (un cursore persistito per account) e lo passa a imsg watch.subscribe come since_rowid, così imsg riproduce le righe arrivate mentre il Gateway era inattivo, poi segue il live. Il replay è limitato alle righe più recenti e ai messaggi vecchi fino a ~2 ore, e la deduplicazione scarta tutto ciò che è già stato gestito.
• Recinto di età per il backlog obsoleto. Le righe sopra il confine di avvio sono davvero live; una il cui timestamp di invio è più vecchio di ~15 minuti rispetto al suo arrivo è il backlog svuotato da Push e viene soppressa. Le righe riprodotte (al confine o sotto) usano invece la finestra di recupero più ampia, così un messaggio perso di recente viene consegnato mentre la cronologia antica no.

Il recupero funziona sia con setup cliPath locali sia remoti, perché il replay since_rowid passa sulla stessa connessione RPC imsg. La differenza è la finestra: quando il Gateway può leggere chat.db (locale), ancora il confine rowid di avvio, limita l'intervallo di replay e consegna i messaggi persi vecchi fino a un paio d'ore. Su un cliPath SSH remoto non può leggere il database, quindi il replay non è limitato e ogni riga usa il recinto di età live: recupera comunque i messaggi persi di recente e sopprime comunque il vecchio backlog, solo con la finestra live più stretta. Esegui il Gateway sul Mac di Messages per la finestra di recupero più ampia.

Segnale visibile all'operatore

Il backlog soppresso viene registrato al livello predefinito, mai scartato silenziosamente (il flag recovery mostra quale finestra è stata applicata):

imessage: suppressed stale inbound backlog account=<id> sent=<iso> recovery=<bool> (&lt;N&gt; suppressed since start)

Migrazione

channels.imessage.catchup.* è deprecato — il recupero del downtime ora è automatico e non richiede configurazione per i nuovi setup. Le configurazioni esistenti con catchup.enabled: true restano rispettate come profilo di compatibilità per la finestra di replay del recupero. I blocchi catchup disabilitati (enabled: false o assenza di enabled: true) sono 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"

Puntatori al riferimento di configurazione

• Riferimento di configurazione - iMessage
• Configurazione Gateway
• Pairing

Correlati

• Panoramica dei canali — tutti i canali supportati
• Rimozione di BlueBubbles e il percorso iMessage imsg — annuncio e riepilogo della migrazione
• Migrazione da BlueBubbles — tabella di traduzione della configurazione e cutover passo per passo
• Pairing — autenticazione DM e flusso di pairing
• Gruppi — comportamento delle chat di gruppo e gating delle menzioni
• Instradamento canale — instradamento delle sessioni per i messaggi
• Sicurezza — modello di accesso e hardening