Se provieni da BlueBubbles

Documentation Index

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

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

​

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 una parte mobile in meno: nessun server BlueBubbles separato, nessun endpoint REST da autenticare, nessun cablaggio Webhook. Un singolo binario CLI invece di un 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 file system di chat.db con un fallback a 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 rich, modifica, annullamento dell’invio, risposta in thread, tapback e gestione dei gruppi.
• Le build Linux possono ispezionare una copia di chat.db, ma non possono inviare, osservare il database live del Mac o pilotare 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, editor, processo Node, servizio Gateway o 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 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 vero id chat da imsg chats. L’invio richiede il permesso 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 dell’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. Verifica il bridge tramite OpenClaw:
   openclaw channels status --probe
   
   Vuoi imessage.privateApi.available: true. Se segnala false, risolvi prima quello: vedi Rilevamento delle capacità.
5. Crea uno snapshot della configurazione:
   cp ~/.openclaw/openclaw.json5 ~/.openclaw/openclaw.json5.bak
   

​

Traduzione della configurazione

​

Insidia del registro gruppi

1. Allowlist del mittente / target della 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 gruppi (channels.imessage.groups): controllato da resolveChannelGroupPolicy da inbound-processing.ts:199. Con groupPolicy: "allowlist", questo gate richiede:
   • una voce jolly groups: { "*": { ... } } (imposta allowAll = true), oppure
   • una voce esplicita per chat_id sotto groups.

• Un warn una tantum all’avvio per account quando groupPolicy: "allowlist" è impostato ma channels.imessage.groups è vuoto (nessun jolly "*", nessuna voce per chat_id): emesso prima dell’arrivo di qualsiasi messaggio.
• Un warn una tantum per chat_id la prima volta che uno specifico gruppo viene scartato in 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 per passo

1. Aggiungi un blocco iMessage accanto al blocco BlueBubbles esistente. Mantieni il vecchio blocco solo come fonte da cui copiare finché il nuovo percorso non è verificato:
   {
     channels: {
       bluebubbles: {
         enabled: true,
         // ... existing config ...
       },
       imessage: {
         enabled: false, // turn on after the dry run below
         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. Sonda dry-run: avvia il Gateway e conferma che iMessage risulti integro:
   openclaw gateway
   openclaw channels status
   openclaw channels status --probe   # expect imessage.privateApi.available: true
   
   Poiché imessage.enabled è ancora false, nessun traffico iMessage in ingresso viene ancora instradato, ma --probe esercita il bridge così puoi individuare problemi di permessi/installazione prima del passaggio.
3. Esegui il passaggio. Rimuovi la configurazione BlueBubbles e abilita iMessage con una singola modifica alla configurazione:
   {
     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 usano percorsi di codice diversi: il successo dei DM non prova che i gruppi vengano instradati. Invia all’agente un messaggio in una chat di gruppo associata e conferma che la risposta arrivi. Se il gruppo resta silenzioso (nessuna risposta dell’agente, nessun errore), controlla nel log del Gateway la riga imessage: dropping group message from chat_id=<id> oppure la 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 tuo blocco groups manca 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 in modo nativo in Messages.app. Se una qualsiasi genera “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 iMessage. OpenClaw non userà channels.bluebubbles.

​

Parità delle azioni in sintesi

​

Associazione, sessioni e binding ACP

• Le approvazioni di associazione si trasferiscono 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 cronologia delle vecchie 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

• iMessage — riferimento completo del canale iMessage, inclusi setup di 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.