iMessage (legacy: imsg)

Attenzione: Per i nuovi deployment iMessage, usa BlueBubbles.

L’integrazione imsg e legacy e potrebbe essere rimossa in una release futura.

Stato: integrazione CLI esterna legacy. Il Gateway esegue imsg rpc e comunica tramite JSON-RPC su stdio (nessun daemon/porta separati).

• BlueBubbles (consigliato) — Percorso iMessage preferito per i nuovi setup.
• Pairing — I DM iMessage usano la modalita pairing per impostazione predefinita.
• Riferimento configurazione — Riferimento completo dei campi iMessage.

Setup rapido

Mac locale (percorso veloce)

  ### Step 1: Installa e verifica imsg

brew install steipete/tap/imsg
imsg rpc --help

  ### Step 2: Configura OpenClaw

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "/usr/local/bin/imsg",
      dbPath: "/Users/<tu>/Library/Messages/chat.db",
    },
  },
}

  ### Step 3: Avvia il gateway

openclaw gateway

  ### Step 4: Approva il primo DM pairing (dmPolicy predefinita)

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

    Le richieste di pairing scadono dopo 1 ora.

Mac remoto via SSH

OpenClaw richiede solo un `cliPath` compatibile con stdio, quindi puoi puntare `cliPath` a uno script wrapper che fa SSH su un Mac remoto e esegue `imsg`.

#!/usr/bin/env bash
exec ssh -T gateway-host imsg "$@"

Config consigliata quando gli allegati sono abilitati:

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "user@gateway-host", // usato per il recupero allegati via SCP
      includeAttachments: true,
      // Opzionale: sovrascrivere le root degli allegati consentite.
      // I valori predefiniti includono /Users/*/Library/Messages/Attachments
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
    },
  },
}

Se `remoteHost` non e impostato, OpenClaw tenta di auto-rilevarlo analizzando lo script wrapper SSH.
`remoteHost` deve essere `host` o `user@host` (senza spazi o opzioni SSH).
OpenClaw usa controllo host-key rigoroso per SCP, quindi la chiave host del relay deve gia esistere in `~/.ssh/known_hosts`.
I percorsi degli allegati sono validati rispetto alle root consentite (`attachmentRoots` / `remoteAttachmentRoots`).

Requisiti e permessi (macOS)

• Messages deve essere autenticato sul Mac che esegue imsg.
• L’Accesso Completo al Disco e necessario per il contesto del processo che esegue OpenClaw/imsg (accesso al DB Messages).
• Il permesso di Automazione e necessario per inviare messaggi attraverso Messages.app.

Suggerimento: I permessi sono concessi per contesto di processo. Se il gateway gira headless (LaunchAgent/SSH), esegui un comando interattivo una tantum nello stesso contesto per attivare i prompt:

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

Controllo degli accessi e routing

Policy DM

`channels.imessage.dmPolicy` controlla i messaggi diretti:

- `pairing` (predefinito)
- `allowlist`
- `open` (richiede `allowFrom` che includa `"*"`)
- `disabled`

Campo allowlist: `channels.imessage.allowFrom`.

Le voci dell'allowlist possono essere handle o target di chat (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`).

Policy gruppi + menzioni

`channels.imessage.groupPolicy` controlla la gestione dei gruppi:

- `allowlist` (predefinito quando configurato)
- `open`
- `disabled`

Allowlist mittenti gruppi: `channels.imessage.groupAllowFrom`.

Fallback runtime: se `groupAllowFrom` non e impostato, i controlli mittente dei gruppi iMessage tornano a `allowFrom` quando disponibile.
Nota runtime: se `channels.imessage` e completamente assente, il runtime torna a `groupPolicy="allowlist"` e registra un avviso (anche se `channels.defaults.groupPolicy` e impostato).

Gating menzione per i gruppi:

- iMessage non ha metadati di menzione nativi
- il rilevamento menzione usa pattern regex (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`)
- senza pattern configurati, il gating menzione non puo essere applicato

I comandi di controllo da mittenti autorizzati possono bypassare il gating menzione nei gruppi.

Sessioni e risposte deterministiche

- I DM usano routing diretto; i gruppi usano routing di gruppo.
- Con il `session.dmScope=main` predefinito, i DM iMessage collassano nella sessione principale dell'agent.
- Le sessioni di gruppo sono isolate (`agent:<agentId>:imessage:group:<chat_id>`).
- Le risposte tornano a iMessage usando i metadati canale/target di origine.

Comportamento thread simil-gruppo:

Alcuni thread iMessage multi-partecipante possono arrivare con `is_group=false`.
Se quel `chat_id` e configurato esplicitamente sotto `channels.imessage.groups`, OpenClaw lo tratta come traffico di gruppo (gating di gruppo + isolamento sessione di gruppo).

Pattern di deployment

Usa un Apple ID dedicato e un utente macOS separato cosi il traffico bot e isolato dal tuo profilo Messages personale.

Flusso tipico:

1. Crea/accedi con un utente macOS dedicato.
2. Accedi a Messages con l'Apple ID del bot in quell'utente.
3. Installa `imsg` in quell'utente.
4. Crea un wrapper SSH cosi OpenClaw puo eseguire `imsg` nel contesto di quell'utente.
5. Punta `channels.imessage.accounts.<id>.cliPath` e `.dbPath` a quel profilo utente.

La prima esecuzione potrebbe richiedere approvazioni GUI (Automazione + Accesso Completo al Disco) nella sessione utente bot.

Topologia comune:

- il gateway gira su Linux/VM
- iMessage + `imsg` gira su un Mac nella tua tailnet
- il wrapper `cliPath` usa SSH per eseguire `imsg`
- `remoteHost` abilita il recupero allegati via SCP

Esempio:

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "[email protected]",
      includeAttachments: true,
      dbPath: "/Users/bot/Library/Messages/chat.db",
    },
  },
}

#!/usr/bin/env bash
exec ssh -T [email protected] imsg "$@"

Usa chiavi SSH cosi sia SSH che SCP sono non-interattivi.
Assicurati che la chiave host sia fidata prima (ad esempio `ssh [email protected]`) cosi `known_hosts` e popolato.

iMessage supporta configurazione per account sotto `channels.imessage.accounts`.

Ogni account puo sovrascrivere campi come `cliPath`, `dbPath`, `allowFrom`, `groupPolicy`, `mediaMaxMb`, impostazioni dello storico e allowlist delle root degli allegati.

Media, segmentazione e target di consegna

- l'ingestione degli allegati in ingresso e opzionale: `channels.imessage.includeAttachments`
- i percorsi degli allegati remoti possono essere recuperati via SCP quando `remoteHost` e impostato
- i percorsi degli allegati devono corrispondere alle root consentite:
  - `channels.imessage.attachmentRoots` (locale)
  - `channels.imessage.remoteAttachmentRoots` (modalita SCP remota)
  - pattern root predefinito: `/Users/*/Library/Messages/Attachments`
- SCP usa controllo host-key rigoroso (`StrictHostKeyChecking=yes`)
- dimensione media in uscita usa `channels.imessage.mediaMaxMb` (predefinito 16 MB)

- limite segmentazione testo: `channels.imessage.textChunkLimit` (predefinito 4000)
- modalita segmentazione: `channels.imessage.chunkMode`
  - `length` (predefinito)
  - `newline` (divisione per paragrafi prima)

Target espliciti preferiti:

- `chat_id:123` (consigliato per routing stabile)
- `chat_guid:...`
- `chat_identifier:...`

Anche i target handle sono supportati:

- `imessage:+1555...`
- `sms:+1555...`
- `[email protected]`

imsg chats --limit 20

Scritture configurazione

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

Disabilita:

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

Risoluzione problemi

Valida il binario e il supporto RPC:

imsg rpc --help
openclaw channels status --probe

Se il probe riporta RPC non supportato, aggiorna `imsg`.

Controlla:

- `channels.imessage.dmPolicy`
- `channels.imessage.allowFrom`
- approvazioni pairing (`openclaw pairing list imessage`)

Controlla:

- `channels.imessage.groupPolicy`
- `channels.imessage.groupAllowFrom`
- comportamento allowlist di `channels.imessage.groups`
- configurazione pattern di menzione (`agents.list[].groupChat.mentionPatterns`)

Controlla:

- `channels.imessage.remoteHost`
- `channels.imessage.remoteAttachmentRoots`
- autenticazione chiave SSH/SCP dall'host del gateway
- la chiave host esiste in `~/.ssh/known_hosts` sull'host del gateway
- leggibilita del percorso remoto sul Mac che esegue Messages

Ri-esegui in un terminale GUI interattivo nello stesso contesto utente/sessione e approva i prompt:

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

Conferma che Accesso Completo al Disco + Automazione siano concessi per il contesto del processo che esegue OpenClaw/`imsg`.

Riferimenti configurazione

• Riferimento configurazione - iMessage
• Configurazione gateway
• Pairing
• BlueBubbles