iMessage

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

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

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

​

Abilitazione dell’API privata imsg

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

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.

​

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

​

Quando non puoi disabilitare SIP

• 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: { "*": { "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 delle conversazioni ACP

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

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

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

​

Scritture di configurazione

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

​

Coalescing dei DM inviati in modo suddiviso (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: {
        // 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

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

​

Semantica di cursore e tentativi

{
  "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 <N> failures; advancing cursor past it
imessage catchup: fetched <X> rows across chats, capped to perRunLimit=<Y>

​

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.

​

Risoluzione dei problemi

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

#!/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 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