iMessage

​

Configurazione rapida

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

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

#!/usr/bin/env bash
exec 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.

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

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

• 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.

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.

​

Configurazione

1. Installare (o aggiornare) imsg sul Mac che esegue Messages.app:
   brew install steipete/tap/imsg
   brew update && brew upgrade imsg
   imsg --version
   imsg 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.

​

Quando SIP rimane abilitato

• 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: { "*": { "requireMention": true } },
    },
  },
}

{
  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

• 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.

• 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>

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

​

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 bash
exec 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

{
  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

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

​

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

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

{
  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

​

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

• 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 è.

​

Segnale visibile all’operatore

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

​

Migrazione

​

Risoluzione dei problemi

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

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

launchctl kickstart -k system/com.apple.apsd
launchctl kickstart -k gui/$(id -u)/com.apple.CommCenter
launchctl kickstart -k gui/$(id -u)/com.apple.identityservicesd
launchctl kickstart -k gui/$(id -u)/com.apple.imagent
imsg launch
openclaw gateway restart

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

openclaw channels status --probe --channel imessage

imsg chats --limit 1
imsg 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