iMessage

​

Configurazione rapida

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

​

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.

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

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

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

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.

​

Configurazione

1. Installa (o aggiorna) imsg sul Mac che esegue Messages.app:
   brew install steipete/tap/imsg
   imsg --version
   imsg 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.

​

Quando non puoi disabilitare SIP

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

​

Binding di conversazione ACP

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

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

​

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

{
  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

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

​

Coalescenza dei DM con invio diviso (comando + URL in un’unica composizione)

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

{
  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

​

Recupero inbound dopo un riavvio del bridge o del Gateway

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

​

Segnale visibile all’operatore

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

​

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"

​

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