Migration depuis BlueBubbles

​

Liste de contrôle de la migration

1. Vérifiez directement imsg sur le Mac qui exécute Messages.app (imsg chats, imsg history, imsg send, imsg rpc --help).
2. Copiez les clés de comportement de channels.bluebubbles vers channels.imessage : dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups, includeAttachments, attachmentRoots, mediaMaxMb, textChunkLimit, coalesceSameSenderDms et actions.
3. Supprimez les clés de transport qui n’existent plus : serverUrl, password, les URL de Webhook et la configuration du serveur BlueBubbles.
4. Si le Gateway ne s’exécute pas sur le Mac hébergeant Messages, définissez channels.imessage.cliPath sur un script enveloppe SSH et définissez remoteHost pour la récupération distante des pièces jointes.
5. Activez channels.imessage, redémarrez le Gateway, puis exécutez openclaw channels status --probe --channel imessage.
6. Testez un message privé, un groupe autorisé, les pièces jointes si elles sont activées et chaque action d’API privée que l’agent est censé utiliser.
7. Supprimez le serveur BlueBubbles et l’ancienne configuration channels.bluebubbles après avoir vérifié le parcours iMessage.

​

Fonctionnement d’imsg

• Les lectures sont effectuées dans ~/Library/Messages/chat.db au moyen d’un accès SQLite en lecture seule.
• Les messages entrants en temps réel proviennent de imsg watch / watch.subscribe, qui suit les événements du système de fichiers de chat.db avec un mécanisme de repli par interrogation périodique.
• Les envois utilisent l’automatisation de Messages.app pour les textes et fichiers ordinaires.
• Les actions avancées utilisent imsg launch pour injecter l’assistant imsg dans Messages.app. Cela permet d’utiliser les confirmations de lecture, les indicateurs de saisie, les envois enrichis, la modification, l’annulation d’envoi, les réponses dans un fil, les réactions, les sondages et la gestion des groupes.
• Les versions Linux peuvent examiner une copie de chat.db, mais ne peuvent ni envoyer de messages, ni surveiller la base de données active du Mac, ni piloter Messages.app. Pour utiliser iMessage avec OpenClaw, exécutez imsg sur le Mac connecté ou par l’intermédiaire d’un script enveloppe SSH vers ce Mac.

​

Avant de commencer

1. Installez imsg sur le Mac qui exécute Messages.app :
   brew install steipete/tap/imsg
   brew update && brew upgrade imsg
   imsg --version
   imsg chats --limit 3
   
   Pour la configuration locale habituelle, l’assistant de configuration d’OpenClaw peut proposer une installation ou une mise à jour de imsg avec Homebrew, après confirmation de l’utilisateur, sur le Mac connecté à Messages. Les configurations manuelles et les topologies reposant sur un script enveloppe SSH restent gérées par l’opérateur : répétez la mise à jour Homebrew dans le même contexte utilisateur local ou distant que celui qui exécutera imsg. Si imsg chats échoue avec unable to open database file, ne produit aucune sortie ou affiche authorization denied, accordez l’accès complet au disque au terminal, à l’éditeur, au processus Node, au service Gateway ou au processus parent SSH qui lance imsg, puis rouvrez ce processus parent.
2. Vérifiez les fonctions de lecture, de surveillance, d’envoi et RPC avant de modifier la configuration d’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
   
   Remplacez 42 par un identifiant de discussion réel obtenu avec imsg chats. L’envoi nécessite l’autorisation d’automatisation pour Messages.app. Si OpenClaw doit s’exécuter via SSH, exécutez ces commandes au moyen du même script enveloppe SSH ou dans le même contexte utilisateur qu’OpenClaw. Si les lectures fonctionnent, mais que les envois échouent avec l’erreur AppleEvents -1743, vérifiez si l’autorisation d’automatisation a été attribuée à /usr/libexec/sshd-keygen-wrapper ; voir Échec des envois via le script enveloppe SSH avec AppleEvents -1743.
3. Activez la passerelle vers l’API privée. Elle est fortement recommandée pour iMessage avec OpenClaw, car les réponses, les réactions, les effets, les sondages, les réponses aux pièces jointes et les actions de groupe en dépendent :
   imsg launch
   imsg status --json
   
   imsg launch nécessite que SIP soit désactivé (et, sur les versions modernes de macOS, que la validation des bibliothèques soit assouplie — voir Activation de l’API privée d’imsg). L’envoi de base, l’historique et la surveillance fonctionnent sans imsg launch, mais pas l’ensemble complet des actions iMessage d’OpenClaw.
4. Après avoir activé channels.imessage et démarré le Gateway, vérifiez la passerelle au moyen d’OpenClaw :
   openclaw channels status --probe
   
   Le compte iMessage doit indiquer works ; avec --json, la charge utile de la sonde comprend privateApi.available: true. Si elle indique false, corrigez d’abord ce problème — voir Détection des capacités. La détection nécessite un Gateway accessible (sinon, la CLI se rabat sur une sortie fondée uniquement sur la configuration) et ne vérifie que les comptes configurés et activés.
5. Créez un instantané de votre configuration :
   cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
   

​

Transposition de la configuration

​

Piège du registre de groupes

1. Liste d’autorisation des expéditeurs ou des cibles de discussion (channels.imessage.groupAllowFrom) — correspond à l’identifiant de l’expéditeur ou à la cible de discussion (entrées chat_id:, chat_guid:, chat_identifier:). Lorsque groupAllowFrom n’est pas défini, ce contrôle se rabat sur allowFrom ; un groupAllowFrom: [] explicite désactive ce repli et ignore tous les messages de groupe lorsque groupPolicy: "allowlist".
2. Registre de groupes (channels.imessage.groups) — indexé par le chat_id numérique d’iMessage :
   • Aucun bloc groups (ou bloc vide) : les groupes franchissent ce contrôle tant que le contrôle 1 dispose d’une liste d’autorisation effective et non vide des expéditeurs ; le filtrage des expéditeurs régit l’accès et aucun avertissement de rejet global n’est émis au démarrage.
   • groups contient des entrées, mais aucune entrée "*" : seules les clés chat_id répertoriées sont acceptées. Le fait de répertorier un groupe transforme le registre en liste d’autorisation, même lorsque groupPolicy: "open".
   • groups: { "*": { ... } } : tous les groupes franchissent ce contrôle.

• Une fois par compte au démarrage, lorsque groupPolicy: "allowlist" est défini et que la liste d’autorisation effective des expéditeurs de groupe est vide : imessage: groupPolicy="allowlist" for account "<id>" but no group sender allowlist is configured .... Définissez groupAllowFrom (ou allowFrom) pour autoriser des expéditeurs ; ajouter uniquement groups ne satisfait pas le contrôle des expéditeurs.
• Une fois par chat_id à l’exécution, lorsque le registre rejette un groupe : imessage: dropping group message from chat_id=<id> ... not in channels.imessage.groups allowlist, en indiquant la clé exacte à ajouter.

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

​

Étape par étape

1. Traduisez la configuration. Laissez le nouveau bloc désactivé pendant vos modifications ; le bloc channels.bluebubbles obsolète est ignoré par la version actuelle d’OpenClaw et peut rester à côté comme référence :
   {
     channels: {
       imessage: {
         enabled: false, // passer à true lorsque vous êtes prêt à effectuer la migration
         cliPath: "/opt/homebrew/bin/imsg",
         dmPolicy: "pairing",
         allowFrom: ["+15555550123"], // copier depuis bluebubbles.allowFrom
         groupPolicy: "allowlist",
         groupAllowFrom: [], // copier depuis bluebubbles.groupAllowFrom
         groups: { "*": { requireMention: true } }, // le caractère générique est copié tel quel ; réindexer les entrées propres à chaque conversation par chat_id
         // les actions sont activées par défaut ; définir individuellement les options sur false pour les désactiver
       },
     },
   }
   
2. Effectuez la migration et lancez une vérification. Définissez channels.imessage.enabled: true, redémarrez le Gateway et vérifiez que le canal est signalé comme opérationnel :
   openclaw gateway restart
   openclaw channels status --probe --channel imessage   # « works » est attendu ; --json affiche privateApi.available: true
   
   La vérification nécessite un Gateway accessible et ne teste que les comptes configurés et activés. Utilisez les commandes imsg directes de la section Avant de commencer pour valider le Mac lui-même.
3. Vérifiez les messages privés. Envoyez un message direct à l’agent et vérifiez que la réponse arrive.
4. Vérifiez les groupes séparément. Les messages privés et les groupes empruntent des chemins de code différents : le bon fonctionnement des messages privés ne prouve pas que le routage des groupes fonctionne. Envoyez un message dans une conversation de groupe autorisée et vérifiez que la réponse arrive. Si le groupe reste silencieux (aucune réponse de l’agent, aucune erreur), recherchez dans le journal du Gateway les deux lignes warn de la section « Piège du registre des groupes » ci-dessus. L’avertissement au démarrage signifie que la liste d’expéditeurs effectivement autorisés est vide ; un avertissement propre à un chat_id signifie qu’un registre groups non vide ne contient pas cette conversation.
5. Vérifiez l’ensemble des actions. Depuis un message privé appairé, demandez à l’agent d’ajouter une réaction, de modifier et d’annuler l’envoi d’un message, d’y répondre, d’envoyer une photo et, dans un groupe, de renommer le groupe ou d’ajouter ou retirer un participant. Chaque action doit apparaître nativement dans Messages.app. Si une action génère l’erreur iMessage <action> requires the imsg private API bridge, exécutez à nouveau imsg launch, puis actualisez l’état avec openclaw channels status --probe.
6. Supprimez le serveur BlueBubbles et le bloc channels.bluebubbles une fois les messages privés, les groupes et les actions iMessage vérifiés. OpenClaw ne lit pas channels.bluebubbles.

​

Comparaison rapide des actions

​

Appairage, sessions et liaisons ACP

• Les listes d’autorisation sont conservées par identifiant. channels.imessage.allowFrom reconnaît les mêmes chaînes +15555550123 / user@example.com qu’utilisait BlueBubbles : copiez-les telles quelles.
• Les approbations du registre d’appairage ne sont pas transférées. Le registre d’appairage est propre à chaque canal et rien ne migre l’ancien registre BlueBubbles. Les expéditeurs qui avaient uniquement été approuvés par appairage doivent s’appairer une nouvelle fois sous iMessage, sauf si vous ajoutez leurs identifiants à allowFrom.
• Les sessions restent limitées à chaque combinaison d’agent et de conversation. Avec la valeur par défaut session.dmScope=main, les messages privés sont regroupés dans la session principale de l’agent ; les sessions de groupe restent isolées par chat_id (agent:<agentId>:imessage:group:<chat_id>). L’ancien historique de conversation associé aux clés de session BlueBubbles n’est pas transféré vers les sessions iMessage.
• Les liaisons ACP qui font référence à match.channel: "bluebubbles" doivent utiliser "imessage". Les formats de match.peer.id (chat_id:, chat_guid:, chat_identifier:, identifiant seul) sont identiques.

​

Aucun canal de retour arrière

​

Voir aussi

• Suppression de BlueBubbles et migration vers iMessage avec imsg — brève annonce et synthèse à l’intention des opérateurs.
• iMessage — référence complète du canal iMessage, notamment la configuration avec imsg launch et la détection des fonctionnalités.
• /channels/bluebubbles — ancienne URL qui redirige vers ce guide de migration.
• Appairage — authentification des messages privés et procédure d’appairage.
• Routage des canaux — méthode employée par le Gateway pour choisir le canal des réponses sortantes.