iMessage (legacy: imsg)

Per i nuovi deployment iMessage, usa BlueBubbles.L’integrazione imsg è legacy e potrebbe essere rimossa in una futura release.

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

BlueBubbles (recommended)

Percorso iMessage preferito per le nuove configurazioni.

Pairing

I DM di iMessage usano per impostazione predefinita la modalità pairing.

Configuration reference

Riferimento completo dei campi iMessage.

Configurazione rapida

Local Mac (fast path)
Remote Mac over SSH

Install and verify imsg

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

Configure OpenClaw

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

Start gateway

openclaw gateway

Approve first DM pairing (default dmPolicy)

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

Le richieste di pairing scadono dopo 1 ora.

OpenClaw richiede solo un cliPath compatibile con stdio, quindi puoi impostare cliPath su uno script wrapper che esegue SSH verso un Mac remoto ed esegue imsg.

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

Configurazione consigliata quando gli allegati sono abilitati:

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

Se remoteHost non è impostato, OpenClaw tenta di rilevarlo automaticamente analizzando lo script wrapper SSH. remoteHost deve essere host oppure user@host (senza spazi né opzioni SSH). OpenClaw usa la verifica rigorosa della chiave host per SCP, quindi la chiave host del relay deve già esistere in ~/.ssh/known_hosts. I percorsi degli allegati vengono convalidati rispetto alle radici consentite (attachmentRoots / remoteAttachmentRoots).

Requisiti e permessi (macOS)

Messages deve aver effettuato l’accesso sul Mac che esegue imsg.
È richiesto l’accesso completo al disco per il contesto di processo che esegue OpenClaw/imsg (accesso al DB di Messages).
È richiesto il permesso Automazione per inviare messaggi tramite Messages.app.

I permessi vengono concessi per contesto di processo. Se il gateway viene eseguito headless (LaunchAgent/SSH), esegui un comando interattivo una tantum nello stesso contesto per attivare le richieste:

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

Controllo degli accessi e instradamento

DM policy
Group policy + mentions
Sessions and deterministic replies

channels.imessage.dmPolicy controlla i messaggi diretti:

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

Campo allowlist: channels.imessage.allowFrom.Le voci allowlist possono essere handle o destinazioni chat (chat_id:*, chat_guid:*, chat_identifier:*).

channels.imessage.groupPolicy controlla la gestione dei gruppi:

allowlist (predefinito quando configurato)
open
disabled

Allowlist dei mittenti del gruppo: channels.imessage.groupAllowFrom.Fallback runtime: se groupAllowFrom non è impostato, i controlli dei mittenti dei gruppi iMessage ripiegano su allowFrom quando disponibile. Nota runtime: se channels.imessage manca completamente, il runtime ripiega su groupPolicy="allowlist" e registra un avviso (anche se channels.defaults.groupPolicy è impostato).Controllo delle menzioni per i gruppi:

iMessage non ha metadati di menzione nativi
il rilevamento delle menzioni usa pattern regex (agents.list[].groupChat.mentionPatterns, fallback messages.groupChat.mentionPatterns)
senza pattern configurati, il controllo delle menzioni non può essere applicato

I comandi di controllo provenienti da mittenti autorizzati possono bypassare il controllo delle menzioni nei gruppi.

I DM usano l’instradamento diretto; i gruppi usano l’instradamento di gruppo.
Con il valore predefinito session.dmScope=main, i DM di iMessage confluiscono nella sessione principale dell’agente.
Le sessioni di gruppo sono isolate (agent:<agentId>:imessage:group:<chat_id>).
Le risposte vengono instradate di nuovo verso iMessage usando i metadati del canale/destinazione di origine.

Comportamento dei thread simili a gruppi:Alcuni thread iMessage con più partecipanti possono arrivare con is_group=false. Se quel chat_id è configurato esplicitamente in channels.imessage.groups, OpenClaw lo tratta come traffico di gruppo (controlli di gruppo + isolamento della sessione di gruppo).

Binding delle conversazioni ACP

Le chat iMessage legacy possono anche essere associate a sessioni ACP. Flusso operativo rapido:

Esegui /acp spawn codex --bind here nel DM o nella chat di gruppo consentita.
I messaggi futuri nella stessa conversazione iMessage verranno instradati alla sessione ACP generata.
/new e /reset reimpostano sul posto la stessa sessione ACP associata.
/acp close chiude la sessione ACP e rimuove l’associazione.

Le associazioni persistenti configurate sono supportate tramite voci bindings[] di primo livello con type: "acp" e match.channel: "imessage". match.peer.id può usare:

handle DM normalizzato come +15555550123 oppure 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" },
    },
  ],
}

Consulta ACP Agents per il comportamento condiviso dei binding ACP.

Pattern di deployment

Dedicated bot macOS user (separate iMessage identity)

Usa un Apple ID e un utente macOS dedicati, così il traffico del bot rimane isolato dal tuo profilo personale di Messages.Flusso tipico:

Crea/accedi con un utente macOS dedicato.
Accedi a Messages con l’Apple ID del bot per quell’utente.
Installa imsg per quell’utente.
Crea un wrapper SSH così OpenClaw può eseguire imsg nel contesto di quell’utente.
Imposta channels.imessage.accounts.<id>.cliPath e .dbPath sul profilo di quell’utente.

La prima esecuzione può richiedere approvazioni GUI (Automazione + Accesso completo al disco) nella sessione utente del bot.

Remote Mac over Tailscale (example)

Topologia comune:

il gateway viene eseguito su Linux/VM
iMessage + imsg vengono eseguiti su un Mac nella tua tailnet
il wrapper cliPath usa SSH per eseguire imsg
remoteHost abilita il recupero degli allegati tramite SCP

Esempio:

{
  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 "$@"

Usa chiavi SSH così sia SSH sia SCP siano non interattivi. Assicurati prima che la chiave host sia affidabile (ad esempio ssh bot@mac-mini.tailnet-1234.ts.net) così known_hosts venga popolato.

Multi-account pattern

iMessage supporta la configurazione per account sotto channels.imessage.accounts.Ogni account può sovrascrivere campi come cliPath, dbPath, allowFrom, groupPolicy, mediaMaxMb, impostazioni della cronologia e allowlist delle radici degli allegati.

Supporti multimediali, suddivisione e destinazioni di consegna

Attachments and media

l’acquisizione degli allegati in ingresso è facoltativa: channels.imessage.includeAttachments
i percorsi degli allegati remoti possono essere recuperati tramite SCP quando remoteHost è impostato
i percorsi degli allegati devono corrispondere alle radici consentite:
- channels.imessage.attachmentRoots (locale)
- channels.imessage.remoteAttachmentRoots (modalità SCP remota)
- pattern radice predefinito: /Users/*/Library/Messages/Attachments
SCP usa la verifica rigorosa della chiave host (StrictHostKeyChecking=yes)
la dimensione dei media in uscita usa channels.imessage.mediaMaxMb (predefinito 16 MB)

Outbound chunking

limite di suddivisione del testo: channels.imessage.textChunkLimit (predefinito 4000)
modalità di suddivisione: channels.imessage.chunkMode
- length (predefinita)
- newline (suddivisione prima per paragrafi)

Addressing formats

Destinazioni esplicite consigliate:

chat_id:123 (consigliato per un instradamento stabile)
chat_guid:...
chat_identifier:...

Sono supportate anche le destinazioni handle:

imessage:+1555...
sms:+1555...
user@example.com

imsg chats --limit 20

Scritture di configurazione

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

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

Risoluzione dei problemi

imsg not found or RPC unsupported

Convalida il binario e il supporto RPC:

imsg rpc --help
openclaw channels status --probe

Se il probe segnala che RPC non è supportato, aggiorna imsg.

DMs are ignored

Verifica:

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

Group messages are ignored

Verifica:

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

Remote attachments fail

Verifica:

channels.imessage.remoteHost
channels.imessage.remoteAttachmentRoots
autenticazione con chiave SSH/SCP dall’host gateway
la chiave host esiste in ~/.ssh/known_hosts sull’host gateway
leggibilità del percorso remoto sul Mac che esegue Messages

macOS permission prompts were missed

Esegui di nuovo in un terminale GUI interattivo nello stesso contesto utente/sessione e approva le richieste:

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

Conferma che Accesso completo al disco + Automazione siano concessi al contesto di processo che esegue OpenClaw/imsg.

Puntatori al riferimento di configurazione

Correlati

Channels Overview — tutti i canali supportati
Pairing — autenticazione DM e flusso pairing
Groups — comportamento delle chat di gruppo e controllo delle menzioni
Channel Routing — instradamento delle sessioni per i messaggi
Security — modello di accesso e hardening

Overview

Messaging platforms

Configuration

​iMessage (legacy: imsg)

BlueBubbles (recommended)

Pairing

Configuration reference

​Configurazione rapida

​Requisiti e permessi (macOS)

​Controllo degli accessi e instradamento

​Binding delle conversazioni ACP

​Pattern di deployment

​Supporti multimediali, suddivisione e destinazioni di consegna

​Scritture di configurazione

​Risoluzione dei problemi

​Puntatori al riferimento di configurazione

​Correlati

iMessage (legacy: imsg)

Configurazione rapida

Requisiti e permessi (macOS)

Controllo degli accessi e instradamento

Binding delle conversazioni ACP

Pattern di deployment

Supporti multimediali, suddivisione e destinazioni di consegna

Scritture di configurazione

Risoluzione dei problemi

Puntatori al riferimento di configurazione

Correlati