Mainstream messaging

iMessage

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

BlueBubbles (fallback legacy)

Continua a usarlo per il routing esistente basato su BlueBubbles; evitalo per nuove configurazioni quando imsg è adatto.

Abbinamento

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

Riferimento di configurazione

Riferimento completo dei campi iMessage.

Configurazione rapida

Mac locale (percorso rapido)

Installa e verifica imsg

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

Configura OpenClaw

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

Avvia il gateway

openclaw gateway

Approva il primo abbinamento DM (dmPolicy predefinita)

openclaw pairing list imessage
openclaw pairing approve imessage &lt;CODE&gt;

Le richieste di abbinamento scadono dopo 1 ora.

Mac remoto tramite SSH

OpenClaw richiede solo un cliPath compatibile con stdio, quindi puoi puntare cliPath a uno script wrapper che si collega via SSH a 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", // 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"],
},
},
}

Se remoteHost non è impostato, OpenClaw tenta di rilevarlo automaticamente analizzando lo script wrapper SSH. remoteHost deve essere host o user@host (senza spazi o opzioni SSH). OpenClaw usa il controllo rigoroso 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 avere l'accesso effettuato sul Mac che esegue imsg.
È richiesto Accesso completo al disco per il contesto del processo che esegue OpenClaw/imsg (accesso al DB di Messages).
È richiesto il permesso di automazione per inviare messaggi tramite Messages.app.

Tip

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

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

Controllo degli accessi e routing

Criterio DM

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:*).

Criterio di gruppo + menzioni

channels.imessage.groupPolicy controlla la gestione dei gruppi:

allowlist (predefinito quando configurato)
open
disabled

Allowlist dei mittenti di gruppo: channels.imessage.groupAllowFrom.

Fallback runtime: se groupAllowFrom non è impostato, i controlli dei mittenti dei gruppi iMessage ricadono su allowFrom quando disponibile. Nota runtime: se channels.imessage manca completamente, il runtime ricade su groupPolicy="allowlist" e registra un avviso (anche se channels.defaults.groupPolicy è impostato).

Controllo delle menzioni per i gruppi:

iMessage non ha metadati nativi per le menzioni
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 da mittenti autorizzati possono bypassare il controllo delle menzioni nei gruppi.

Sessioni e risposte deterministiche

I DM usano il routing diretto; i gruppi usano il routing di gruppo.
Con session.dmScope=main predefinito, i DM iMessage confluiscono nella sessione principale dell'agente.
Le sessioni di gruppo sono isolate (agent:<agentId>:imessage:group:<chat_id>).
Le risposte tornano a iMessage usando i metadati di 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 (controllo di gruppo + isolamento della sessione di gruppo).

Binding delle conversazioni ACP

Le chat iMessage legacy possono anche essere associate a sessioni ACP.

Flusso rapido per l'operatore:

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

I binding persistenti configurati sono supportati tramite voci bindings[] di primo livello con type: "acp" e match.channel: "imessage".

match.peer.id può usare:

handle DM normalizzato come +15555550123 o [email protected]
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" },
    },
  ],
}

Vedi Agenti ACP per il comportamento condiviso dei binding ACP.

Schemi di distribuzione

Utente macOS dedicato per il bot (identità iMessage separata)

Usa un Apple ID e un utente macOS dedicati in modo che il traffico del bot sia isolato dal tuo profilo Messages personale.

Flusso tipico:

Crea/accedi a un utente macOS dedicato.
Accedi a Messages con l'Apple ID del bot in quell'utente.
Installa imsg in quell'utente.
Crea un wrapper SSH in modo che OpenClaw possa eseguire imsg nel contesto di quell'utente.
Punta channels.imessage.accounts.<id>.cliPath e .dbPath a quel profilo utente.

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

Mac remoto tramite Tailscale (esempio)

Topologia comune:

il gateway viene eseguito su Linux/VM
iMessage + imsg viene eseguito 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: "[email protected]",
  includeAttachments: true,
  dbPath: "/Users/bot/Library/Messages/chat.db",
},
},
}

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

Usa chiavi SSH in modo che sia SSH sia SCP siano non interattivi. Assicurati prima che la chiave host sia considerata attendibile (per esempio ssh [email protected]) così known_hosts viene popolato.

Schema multi-account

iMessage supporta la configurazione per account in channels.imessage.accounts.

Ogni account può sovrascrivere campi come cliPath, dbPath, allowFrom, groupPolicy, mediaMaxMb, impostazioni della cronologia e allowlist delle radici degli allegati.

Media, suddivisione in blocchi e destinazioni di consegna

Allegati e media

l'ingestione 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 il controllo rigoroso della chiave host (StrictHostKeyChecking=yes)
la dimensione dei media in uscita usa channels.imessage.mediaMaxMb (predefinito 16 MB)

Suddivisione in blocchi in uscita

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

Formati di indirizzamento

Destinazioni esplicite preferite:

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

Sono supportate anche le destinazioni handle:

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

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

Disabilita:

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

Risoluzione dei problemi

imsg non trovato o RPC non supportato

Convalida il binario e il supporto RPC:

imsg rpc --help
openclaw channels status --probe

Se il probe segnala RPC non supportato, aggiorna imsg.

I DM vengono ignorati

Controlla:

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

I messaggi di gruppo vengono ignorati

Controlla:

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

Gli allegati remoti non riescono

Controlla:

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

Le richieste di permesso macOS sono state perse

Riesegui 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 per il contesto del processo che esegue OpenClaw/imsg.

Puntatori al riferimento di configurazione

Correlati

Panoramica dei canali — tutti i canali supportati
Abbinamento — autenticazione tramite DM e flusso di abbinamento
Gruppi — comportamento delle chat di gruppo e gating delle menzioni
Instradamento dei canali — instradamento delle sessioni per i messaggi
Sicurezza — modello di accesso e rafforzamento

# Configurazione rapida

Mac locale (percorso rapido)

Installa e verifica imsg

Configura OpenClaw

Avvia il gateway

Approva il primo abbinamento DM (dmPolicy predefinita)

Mac remoto tramite SSH

# Requisiti e permessi (macOS)

# Controllo degli accessi e routing

Criterio DM

Criterio di gruppo + menzioni

Sessioni e risposte deterministiche

# Binding delle conversazioni ACP

# Schemi di distribuzione

# Media, suddivisione in blocchi e destinazioni di consegna

# Scritture di configurazione

# Risoluzione dei problemi

# Puntatori al riferimento di configurazione

# Correlati

Configurazione rapida

Requisiti e permessi (macOS)

Controllo degli accessi e routing

Binding delle conversazioni ACP

Schemi di distribuzione

Media, suddivisione in blocchi e destinazioni di consegna

Scritture di configurazione

Risoluzione dei problemi

Puntatori al riferimento di configurazione

Correlati