Passaggio da BlueBubbles

Il supporto per BlueBubbles è stato rimosso. OpenClaw supporta iMessage solo tramite il Plugin imessage incluso, che controlla steipete/imsg tramite JSON-RPC e accede alla stessa superficie API privata utilizzata da BlueBubbles (react, edit, unsend, reply, sendWithEffect, sondaggi nativi, gestione dei gruppi, allegati). Un unico eseguibile CLI sostituisce il server BlueBubbles, l'app client e l'infrastruttura webhook: nessun endpoint REST, nessuna autenticazione webhook.

Questa guida illustra la migrazione delle vecchie configurazioni channels.bluebubbles a channels.imessage. Non sono supportati altri percorsi di migrazione. Nella versione attuale di OpenClaw, un blocco channels.bluebubbles residuo è inerte: nessun componente di runtime lo legge.

Lista di controllo per la migrazione

Il percorso sicuro più breve, se conosci già la tua vecchia configurazione BlueBubbles:

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

imsg è una CLI macOS locale per Messages. OpenClaw avvia imsg rpc come processo figlio e comunica tramite JSON-RPC su stdin/stdout. Non sono presenti server HTTP, URL webhook, demoni in background, agenti di avvio o porte da esporre.

• 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/imsgbrew update && brew upgrade imsgimsg --versionimsg 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 -simsg history --chat-id 42 --limit 10 --attachments --json | jq -simsg watch --chat-id 42 --reactions --jsonimsg 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 launchimsg 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

iMessage e BlueBubbles condividono la maggior parte delle chiavi di comportamento a livello di canale. Ciò che cambia è il trasporto (server REST rispetto a CLI locale) e il formato della chiave del registro dei gruppi.

Le configurazioni con più account (channels.bluebubbles.accounts.*) si traducono direttamente in channels.imessage.accounts.*.

Insidia del registro dei gruppi

Il plugin iMessage integrato esegue consecutivamente due controlli per i gruppi. Un messaggio di gruppo deve superarli entrambi per raggiungere l'agente:

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.

L'insidia della migrazione: BlueBubbles usava come chiavi delle voci groups il GUID o l'identificatore della chat, mentre il registro di iMessage usa il valore numerico chat_id. Le voci per singolo gruppo copiate alla lettera creano un registro non vuoto le cui chiavi non corrispondono mai; di conseguenza, ogni messaggio di gruppo viene scartato al controllo 2. Copiare alla lettera la voce jolly "*"; modificare le chiavi delle voci relative a gruppi specifici usando i valori chat_id ottenuti da imsg chats.

Entrambi i percorsi di scarto sono visibili al livello di log predefinito tramite righe warn:

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

I messaggi diretti continuano a funzionare in entrambi i casi: seguono un percorso di codice diverso, quindi il corretto funzionamento dei messaggi diretti non dimostra che l'instradamento dei gruppi funzioni.

La configurazione minima limitata ai mittenti con groupPolicy: "allowlist":

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

Questa configurazione ammette i mittenti configurati in qualsiasi gruppo. Aggiungere voci groups per limitare le chat consentite o impostare opzioni per singola chat, come requireMention; copiare alla lettera la voce "*" di BlueBubbles, ma modificare le chiavi delle voci specifiche usando i valori numerici chat_id di iMessage.

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

iMessage recupera i messaggi persi mentre il Gateway non era in esecuzione: all'avvio riproduce i messaggi a partire dall'ultimo rowid inviato tramite imsg watch.subscribe since_rowid, li deduplica in base al GUID e un limite sull'età dei messaggi arretrati obsoleti impedisce la "bomba di messaggi arretrati" dovuta allo svuotamento Push. Questa procedura avviene tramite la connessione RPC di imsg, quindi funziona anche nelle configurazioni remote di cliPath tramite SSH; le configurazioni locali dispongono di un intervallo di recupero più ampio perché possono leggere chat.db. Consulta Recupero dei messaggi in entrata dopo il riavvio di un bridge o del Gateway.

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

Non esiste un runtime BlueBubbles supportato a cui tornare. Se la verifica di iMessage non riesce, imposta channels.imessage.enabled: false, riavvia il Gateway, risolvi il problema che blocca imsg e riprova la migrazione.

La cache delle risposte risiede nello stato SQLite del Plugin. Quando è presente, openclaw doctor --fix importa e archivia il vecchio file complementare imessage/reply-cache.jsonl.

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.