Passaggio da BlueBubbles

​

Lista di controllo per la migrazione

1. Verifica direttamente imsg sul Mac che esegue Messages.app (imsg chats, imsg history, imsg send, imsg rpc --help).
2. Copia le chiavi di comportamento da channels.bluebubbles a channels.imessage: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups, includeAttachments, attachmentRoots, mediaMaxMb, textChunkLimit, coalesceSameSenderDms e actions.
3. Elimina le chiavi di trasporto che non esistono più: serverUrl, password, gli URL dei webhook e la configurazione del server BlueBubbles.
4. Se il Gateway non è in esecuzione sul Mac con Messages, imposta channels.imessage.cliPath su un wrapper SSH e configura remoteHost per il recupero remoto degli allegati.
5. Abilita channels.imessage, riavvia il Gateway, quindi esegui openclaw channels status --probe --channel imessage.
6. Verifica un messaggio diretto, un gruppo consentito, gli allegati se abilitati e ogni azione dell’API privata che prevedi venga utilizzata dall’agente.
7. Elimina il server BlueBubbles e la vecchia configurazione channels.bluebubbles dopo aver verificato il percorso iMessage.

​

Funzionamento di imsg

• Le letture provengono da ~/Library/Messages/chat.db tramite un handle SQLite di sola lettura.
• I messaggi in ingresso in tempo reale provengono da imsg watch / watch.subscribe, che monitora gli eventi del file system di chat.db con il polling come meccanismo di riserva.
• Gli invii utilizzano l’automazione di Messages.app per i normali messaggi di testo e file.
• Le azioni avanzate utilizzano imsg launch per inserire l’helper imsg in Messages.app. Ciò abilita le conferme di lettura, gli indicatori di digitazione, gli invii avanzati, la modifica, l’annullamento dell’invio, le risposte nei thread, i tapback, i sondaggi e la gestione dei gruppi.
• Le build Linux possono esaminare una copia di chat.db, ma non possono inviare messaggi, monitorare il database attivo del Mac o controllare Messages.app. Per iMessage in OpenClaw, esegui imsg sul Mac su cui è stato effettuato l’accesso oppure tramite un wrapper SSH verso tale Mac.

​

Prima di iniziare

1. Installa imsg sul Mac che esegue Messages.app:
   brew install steipete/tap/imsg
   brew update && brew upgrade imsg
   imsg --version
   imsg chats --limit 3
   
   Per la normale configurazione locale, la procedura di configurazione di OpenClaw può proporre un’installazione o un aggiornamento di imsg tramite Homebrew, previa conferma dell’utente, sul Mac con Messages su cui è stato effettuato l’accesso. La configurazione manuale e le topologie con wrapper SSH restano gestite dall’operatore: ripeti l’aggiornamento Homebrew nello stesso contesto utente locale o remoto che eseguirà imsg. Se imsg chats non riesce con unable to open database file, non produce alcun risultato oppure restituisce authorization denied, concedi l’accesso completo al disco al terminale, all’editor, al processo Node, al servizio Gateway o al processo SSH padre che avvia imsg, quindi riapri tale processo padre.
2. Verifica le funzionalità di lettura, monitoraggio, invio e RPC prima di modificare la configurazione di OpenClaw:
   imsg chats --limit 10 --json | jq -s
   imsg history --chat-id 42 --limit 10 --attachments --json | jq -s
   imsg watch --chat-id 42 --reactions --json
   imsg send --chat-id 42 --text "OpenClaw imsg test"
   imsg rpc --help
   
   Sostituisci 42 con un ID chat reale ottenuto da imsg chats. L’invio richiede l’autorizzazione di automazione per Messages.app. Se OpenClaw verrà eseguito tramite SSH, esegui questi comandi tramite lo stesso wrapper SSH o contesto utente che utilizzerà OpenClaw. Se le letture funzionano ma gli invii non riescono con AppleEvents -1743, verifica se l’autorizzazione di automazione è stata assegnata a /usr/libexec/sshd-keygen-wrapper; consulta Gli invii tramite wrapper SSH non riescono con AppleEvents -1743.
3. Abilita il bridge dell’API privata. È fortemente consigliato per iMessage in OpenClaw, poiché le risposte, i tapback, gli effetti, i sondaggi, le risposte agli allegati e le azioni sui gruppi dipendono da esso:
   imsg launch
   imsg status --json
   
   imsg launch richiede che SIP sia disabilitato (e, nelle versioni moderne di macOS, che la convalida delle librerie sia attenuata; consulta Abilitazione dell’API privata di imsg). L’invio di base, la cronologia e il monitoraggio funzionano senza imsg launch; l’intera gamma di azioni iMessage di OpenClaw no.
4. Dopo aver abilitato channels.imessage e avviato il Gateway, verifica il bridge tramite OpenClaw:
   openclaw channels status --probe
   
   L’account iMessage dovrebbe indicare works; con --json, il payload della verifica include privateApi.available: true. Se indica false, risolvi prima questo problema; consulta Rilevamento delle funzionalità. La verifica richiede un Gateway raggiungibile (in caso contrario, la CLI ripiega su un output basato esclusivamente sulla configurazione) e controlla solo gli account configurati e abilitati.
5. Crea un’istantanea della configurazione:
   cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
   

​

Traduzione della configurazione

​

Insidia del registro dei gruppi

1. Elenco consentiti dei mittenti/destinatari delle chat (channels.imessage.groupAllowFrom): verifica la corrispondenza con l’identificativo del mittente o con il destinatario della chat (voci chat_id:, chat_guid:, chat_identifier:). Quando groupAllowFrom non è impostato, questo controllo usa come ripiego allowFrom; un groupAllowFrom: [] esplicito disabilita tale ripiego e scarta ogni messaggio di gruppo con groupPolicy: "allowlist".
2. Registro dei gruppi (channels.imessage.groups): usa come chiave il valore numerico chat_id di iMessage:
   • Nessun blocco groups (o un blocco vuoto): i gruppi superano questo controllo purché il controllo 1 disponga di un elenco consentiti effettivo e non vuoto per i mittenti; il filtro dei mittenti regola l’accesso e all’avvio non viene emesso alcun avviso relativo allo scarto totale.
   • groups con voci ma senza "*": vengono accettate solo le chiavi chat_id elencate. L’inserimento di un qualsiasi gruppo trasforma il registro in un elenco consentiti, anche con groupPolicy: "open".
   • groups: { "*": { ... } }: ogni gruppo supera questo controllo.

• Una volta per account all’avvio, quando è impostato groupPolicy: "allowlist" e l’elenco consentiti effettivo dei mittenti dei gruppi è vuoto: imessage: groupPolicy="allowlist" for account "<id>" but no group sender allowlist is configured .... Impostare groupAllowFrom (o allowFrom) per ammettere i mittenti; l’aggiunta del solo groups non soddisfa il controllo dei mittenti.
• Una volta per chat_id durante l’esecuzione, quando il registro scarta un gruppo: imessage: dropping group message from chat_id=<id> ... not in channels.imessage.groups allowlist, indicando la chiave esatta da aggiungere.

{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123", "chat_guid:any;-;..."],
    },
  },
}

​

Procedura dettagliata

1. Traduci la configurazione. Mantieni il nuovo blocco disabilitato durante la modifica; il vecchio blocco channels.bluebubbles viene ignorato dalla versione attuale di OpenClaw e può rimanere accanto come riferimento:
   {
     channels: {
       imessage: {
         enabled: false, // imposta su true quando sei pronto per la migrazione
         cliPath: "/opt/homebrew/bin/imsg",
         dmPolicy: "pairing",
         allowFrom: ["+15555550123"], // copia da bluebubbles.allowFrom
         groupPolicy: "allowlist",
         groupAllowFrom: [], // copia da bluebubbles.groupAllowFrom
         groups: { "*": { requireMention: true } }, // il carattere jolly viene copiato letteralmente; modifica le chiavi delle voci per chat usando chat_id
         // le azioni sono abilitate per impostazione predefinita; imposta i singoli interruttori su false per disabilitarle
       },
     },
   }
   
2. Esegui la migrazione e la verifica. Imposta channels.imessage.enabled: true, riavvia il Gateway e verifica che il canale risulti integro:
   openclaw gateway restart
   openclaw channels status --probe --channel imessage   # attenditi "works"; --json mostra privateApi.available: true
   
   La verifica richiede un Gateway raggiungibile e controlla solo gli account configurati e abilitati. Usa i comandi diretti imsg in Prima di iniziare per convalidare il Mac stesso.
3. Verifica i messaggi diretti. Invia un messaggio diretto all’agente e verifica che la risposta venga recapitata.
4. Verifica separatamente i gruppi. I messaggi diretti e i gruppi seguono percorsi di codice diversi: il corretto funzionamento dei messaggi diretti non dimostra che l’instradamento dei gruppi funzioni. Invia un messaggio in una chat di gruppo consentita e verifica che la risposta venga recapitata. Se il gruppo non riceve più risposte (nessuna risposta dell’agente, nessun errore), controlla nel log del Gateway le due righe warn indicate sopra in “Insidia del registro dei gruppi”. L’avviso all’avvio indica che l’elenco effettivo dei mittenti consentiti è vuoto; un avviso relativo a uno specifico chat_id indica che un registro groups popolato non contiene quella chat.
5. Verifica le azioni disponibili. Da un messaggio diretto associato, chiedi all’agente di aggiungere una reazione, modificare, annullare l’invio, rispondere, inviare una foto e, in un gruppo, rinominare il gruppo oppure aggiungere o rimuovere un partecipante. Ogni azione deve essere eseguita in modo nativo in Messages.app. Se un’azione genera l’errore iMessage <action> requires the imsg private API bridge, esegui nuovamente imsg launch e aggiorna lo stato con openclaw channels status --probe.
6. Rimuovi il server BlueBubbles e il blocco channels.bluebubbles dopo aver verificato i messaggi diretti, i gruppi e le azioni di iMessage. OpenClaw non legge channels.bluebubbles.

​

Confronto rapido delle azioni

​

Associazione, sessioni e collegamenti ACP

• Gli elenchi di elementi consentiti vengono mantenuti in base all’identificativo. channels.imessage.allowFrom riconosce le stesse stringhe +15555550123 / user@example.com usate da BlueBubbles: copiale letteralmente.
• Le approvazioni dell’archivio delle associazioni non vengono trasferite. L’archivio delle associazioni è specifico per ciascun canale e nulla migra il vecchio archivio di BlueBubbles. I mittenti approvati esclusivamente tramite associazione devono associarsi nuovamente con iMessage; in alternativa, aggiungi i loro identificativi a allowFrom.
• Le sessioni rimangono circoscritte a ogni coppia agente + chat. Con il valore predefinito session.dmScope=main, i messaggi diretti confluiscono nella sessione principale dell’agente; le sessioni di gruppo rimangono isolate per chat_id (agent:<agentId>:imessage:group:<chat_id>). La cronologia precedente delle conversazioni associata alle chiavi di sessione di BlueBubbles non viene trasferita nelle sessioni di iMessage.
• I collegamenti ACP che fanno riferimento a match.channel: "bluebubbles" devono essere modificati in "imessage". I formati di match.peer.id (chat_id:, chat_guid:, chat_identifier:, identificativo senza prefisso) sono identici.

​

Nessun canale di ripristino

​

Contenuti correlati

• Rimozione di BlueBubbles e percorso iMessage tramite imsg — breve annuncio e riepilogo per gli operatori.
• iMessage — riferimento completo del canale iMessage, inclusi la configurazione di imsg launch e il rilevamento delle funzionalità.
• /channels/bluebubbles — URL precedente che reindirizza a questa guida alla migrazione.
• Associazione — autenticazione dei messaggi diretti e flusso di associazione.
• Instradamento dei canali — modalità con cui il Gateway seleziona un canale per le risposte in uscita.