Se provieni da BlueBubbles

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Checklist di migrazione

1. Verifica imsg direttamente sul Mac che esegue Messages.app (imsg chats, imsg history, imsg send e 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, URL dei webhook e configurazione del server BlueBubbles.
4. Se il Gateway non è in esecuzione sul Mac di Messages, imposta channels.imessage.cliPath su un wrapper SSH e imposta remoteHost per il recupero remoto degli allegati.
5. Con il Gateway arrestato, abilita channels.imessage, quindi esegui openclaw channels status --probe --channel imessage.
6. Testa un DM, un gruppo consentito, gli allegati se abilitati e ogni azione API privata che ti aspetti che l’agente usi.
7. Elimina il server BlueBubbles e la vecchia configurazione channels.bluebubbles dopo aver verificato il percorso iMessage.

​

Quando questa migrazione ha senso

• Esegui già imsg sullo stesso Mac (o su uno raggiungibile tramite SSH) in cui Messages.app ha effettuato l’accesso.
• Vuoi un componente in meno da gestire: nessun server BlueBubbles separato, nessun endpoint REST da autenticare, nessun cablaggio di webhook. Un singolo binario CLI invece di server + app client + helper.
• Usi una build macOS / imsg supportata in cui il probe dell’API privata segnala available: true.

​

Cosa fa imsg

• Le letture provengono da ~/Library/Messages/chat.db usando un handle SQLite di sola lettura.
• I messaggi in ingresso live provengono da imsg watch / watch.subscribe, che segue gli eventi del filesystem di chat.db con un fallback basato su polling.
• Gli invii usano l’automazione di Messages.app per i normali invii di testo e file.
• Le azioni avanzate usano imsg launch per iniettare l’helper imsg in Messages.app. Questo sblocca conferme di lettura, indicatori di digitazione, invii avanzati, modifica, annullamento dell’invio, risposta in thread, tapback e gestione dei gruppi.
• Le build Linux possono ispezionare un chat.db copiato, ma non possono inviare, osservare il database live del Mac o controllare Messages.app. Per OpenClaw iMessage, esegui imsg sul Mac con accesso effettuato o tramite un wrapper SSH verso quel Mac.

​

Prima di iniziare

1. Installa imsg sul Mac che esegue Messages.app:
   brew install steipete/tap/imsg
   imsg --version
   imsg chats --limit 3
   
   Se imsg chats fallisce con unable to open database file, output vuoto o authorization denied, concedi Accesso completo al disco al terminale, all’editor, al processo Node, al servizio Gateway o al processo padre SSH che avvia imsg, quindi riapri quel processo padre.
2. Verifica le superfici di lettura, osservazione, 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 da imsg chats. L’invio richiede l’autorizzazione Automazione per Messages.app. Se OpenClaw verrà eseguito tramite SSH, esegui questi comandi tramite lo stesso wrapper SSH o contesto utente che userà OpenClaw.
3. Abilita il bridge API privata quando ti servono azioni avanzate:
   imsg launch
   imsg status --json
   
   imsg launch richiede che SIP sia disabilitato. Invio di base, cronologia e osservazione funzionano senza imsg launch; le azioni avanzate no.
4. Dopo aver aggiunto una configurazione channels.imessage abilitata, verifica il bridge tramite OpenClaw:
   openclaw channels status --probe
   
   Devi ottenere imessage.privateApi.available: true. Se segnala false, correggi prima questo aspetto: consulta Rilevamento delle capacità. channels status --probe esegue il probe solo degli account configurati e abilitati.
5. Crea uno snapshot della configurazione:
   cp ~/.openclaw/openclaw.json5 ~/.openclaw/openclaw.json5.bak
   

​

Traduzione della configurazione

​

Trappola del registro dei gruppi

1. Allowlist del mittente / destinatario chat (channels.imessage.groupAllowFrom): controllata da isAllowedIMessageSender. Abbina i messaggi in ingresso per handle del mittente, chat_guid, chat_identifier o chat_id. Stessa forma di BlueBubbles.
2. Registro dei gruppi (channels.imessage.groups): controllato da resolveChannelGroupPolicy da inbound-processing.ts:199. Con groupPolicy: "allowlist", questo gate richiede:
   • una voce wildcard groups: { "*": { ... } } (imposta allowAll = true), oppure
   • una voce esplicita per chat_id sotto groups.

• Un warn di avvio una tantum per account quando groupPolicy: "allowlist" è impostato ma channels.imessage.groups è vuoto (nessuna wildcard "*", nessuna voce per chat_id): attivato prima che arrivi qualsiasi messaggio.
• Un warn una tantum per chat_id la prima volta che uno specifico gruppo viene eliminato a runtime, indicando il chat_id e la chiave esatta da aggiungere a groups per consentirlo.

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

​

Passo dopo passo

1. Aggiungi un blocco iMessage accanto al blocco BlueBubbles esistente. Mantienilo disabilitato mentre il Gateway sta ancora instradando il traffico BlueBubbles:
   {
     channels: {
       bluebubbles: {
         enabled: true,
         // ... existing config ...
       },
       imessage: {
         enabled: false,
         cliPath: "/opt/homebrew/bin/imsg",
         dmPolicy: "pairing",
         allowFrom: ["+15555550123"], // copy from bluebubbles.allowFrom
         groupPolicy: "allowlist",
         groupAllowFrom: [], // copy from bluebubbles.groupAllowFrom
         groups: { "*": { requireMention: true } }, // copy from bluebubbles.groups — silently drops groups if missing, see "Group registry footgun" above
         actions: {
           reactions: true,
           edit: true,
           unsend: true,
           reply: true,
           sendWithEffect: true,
           sendAttachment: true,
         },
       },
     },
   }
   
2. Esegui un probe prima che il traffico conti — arresta il Gateway, abilita temporaneamente il blocco iMessage e conferma dalla CLI che iMessage risulti integro:
   openclaw gateway stop
   # edit config: channels.imessage.enabled = true
   openclaw channels status --probe --channel imessage   # expect imessage.privateApi.available: true
   
   channels status --probe esegue il probe solo degli account configurati e abilitati. Non riavviare il Gateway con BlueBubbles e iMessage entrambi abilitati, a meno che tu non voglia intenzionalmente eseguire entrambi i monitor di canale. Se non stai effettuando subito il passaggio, reimposta channels.imessage.enabled su false prima di riavviare il Gateway. Usa i comandi diretti imsg in Prima di iniziare per validare il Mac prima di abilitare il traffico OpenClaw.
3. Effettua il passaggio. Quando l’account iMessage abilitato risulta integro, rimuovi la configurazione BlueBubbles e mantieni iMessage abilitato:
   {
     channels: {
       imessage: { enabled: true /* ... */ },
     },
   }
   
   Riavvia il Gateway. Il traffico iMessage in ingresso ora passa attraverso il Plugin incluso.
4. Verifica i DM. Invia all’agente un messaggio diretto; conferma che la risposta arrivi.
5. Verifica i gruppi separatamente. DM e gruppi seguono percorsi di codice diversi: il successo dei DM non prova che i gruppi siano instradati. Invia all’agente un messaggio in una chat di gruppo associata e conferma che la risposta arrivi. Se il gruppo diventa silenzioso (nessuna risposta dell’agente, nessun errore), controlla nel log del Gateway la presenza di imessage: dropping group message from chat_id=<id> o della riga di avvio imessage: groupPolicy="allowlist" but channels.imessage.groups is empty: entrambe vengono emesse al livello di log predefinito. Se compare una delle due, il blocco groups è mancante o vuoto: vedi “Group registry footgun” sopra.
6. Verifica la superficie delle azioni — da un DM associato, chiedi all’agente di reagire, modificare, annullare l’invio, rispondere, inviare una foto e (in un gruppo) rinominare il gruppo / aggiungere o rimuovere un partecipante. Ogni azione dovrebbe arrivare nativamente in Messages.app. Se una qualsiasi restituisce “iMessage <action> requires the imsg private API bridge”, esegui di nuovo imsg launch e aggiorna channels status --probe.
7. Rimuovi il server e la configurazione BlueBubbles dopo aver verificato DM, gruppi e azioni di iMessage. OpenClaw non userà channels.bluebubbles.

​

Parità delle azioni in sintesi

​

Associazione, sessioni e binding ACP

• Le approvazioni di associazione vengono trasferite per handle. Non devi riapprovare i mittenti noti: channels.imessage.allowFrom riconosce le stesse stringhe +15555550123 / user@example.com usate da BlueBubbles.
• Le sessioni restano limitate per agente + chat. I DM confluiscono nella sessione principale dell’agente con il valore predefinito session.dmScope=main; le sessioni di gruppo restano isolate per chat_id. Le chiavi di sessione differiscono (agent:<id>:imessage:group:<chat_id> rispetto all’equivalente BlueBubbles): la vecchia cronologia delle conversazioni sotto le chiavi di sessione BlueBubbles non viene trasferita nelle sessioni iMessage.
• I binding ACP che fanno riferimento a match.channel: "bluebubbles" devono essere aggiornati a "imessage". Le forme di match.peer.id (chat_id:, chat_guid:, chat_identifier:, handle semplice) sono identiche.

​

Nessun canale di rollback

​

Correlati

• Rimozione di BlueBubbles e percorso iMessage imsg — breve annuncio e riepilogo per gli operatori.
• iMessage — riferimento completo del canale iMessage, inclusi configurazione imsg launch e rilevamento delle capacità.
• /channels/bluebubbles — URL legacy che reindirizza a questa guida di migrazione.
• Associazione — autenticazione DM e flusso di associazione.
• Instradamento dei canali — come il Gateway sceglie un canale per le risposte in uscita.