Venir de BlueBubbles

​

Liste de contrôle de migration

1. Vérifiez imsg directement sur le Mac qui exécute Messages.app (imsg chats, imsg history, imsg send et 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 Messages, définissez channels.imessage.cliPath sur un wrapper SSH et définissez remoteHost pour les récupérations distantes de pièces jointes.
5. Gateway arrêté, activez channels.imessage, puis exécutez openclaw channels status --probe --channel imessage.
6. Testez un DM, un groupe autorisé, les pièces jointes si elles sont activées, et chaque action d’API privée que vous attendez que l’agent utilise.
7. Supprimez le serveur BlueBubbles et l’ancienne configuration channels.bluebubbles une fois le chemin iMessage vérifié.

​

Quand cette migration est pertinente

• Vous exécutez déjà imsg sur le même Mac (ou sur un Mac joignable via SSH) où Messages.app est connecté.
• Vous voulez un composant de moins — pas de serveur BlueBubbles séparé, pas de point de terminaison REST à authentifier, pas de plomberie de webhook. Un seul binaire CLI au lieu d’un serveur + une application cliente + un assistant.
• Vous utilisez une version macOS / imsg prise en charge où la sonde d’API privée indique available: true.

​

Ce que fait imsg

• Les lectures proviennent de ~/Library/Messages/chat.db avec un handle SQLite en lecture seule.
• Les messages entrants en direct proviennent de imsg watch / watch.subscribe, qui suit les événements du système de fichiers de chat.db avec un repli par interrogation.
• Les envois utilisent l’automatisation de Messages.app pour les textes normaux et les envois de fichiers.
• Les actions avancées utilisent imsg launch pour injecter l’assistant imsg dans Messages.app. C’est ce qui débloque les accusés de lecture, les indicateurs de saisie, les envois enrichis, la modification, l’annulation d’envoi, la réponse en fil, les tapbacks et la gestion des groupes.
• Les builds Linux peuvent inspecter un chat.db copié, mais ne peuvent pas envoyer, surveiller la base de données Mac en direct ni piloter Messages.app. Pour iMessage dans OpenClaw, exécutez imsg sur le Mac connecté ou via un wrapper SSH vers ce Mac.

​

Avant de commencer

1. Installez imsg sur le Mac qui exécute Messages.app :
   brew install steipete/tap/imsg
   imsg --version
   imsg chats --limit 3
   
   Si imsg chats échoue avec unable to open database file, une sortie vide ou 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 surfaces de lecture, de surveillance, d’envoi et RPC avant de modifier la configuration 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 vrai id de chat obtenu depuis imsg chats. L’envoi nécessite l’autorisation Automation pour Messages.app. Si OpenClaw s’exécutera via SSH, exécutez ces commandes via le même wrapper SSH ou le même contexte utilisateur qu’OpenClaw utilisera. Si les lectures/sondes fonctionnent mais que les envois échouent avec AppleEvents -1743, vérifiez si Automation a été accordée à /usr/libexec/sshd-keygen-wrapper ; consultez Les envois via wrapper SSH échouent avec AppleEvents -1743.
3. Activez le pont d’API privée lorsque vous avez besoin d’actions avancées :
   imsg launch
   imsg status --json
   
   imsg launch nécessite la désactivation de SIP. L’envoi de base, l’historique et la surveillance fonctionnent sans imsg launch ; les actions avancées ne fonctionnent pas.
4. Après avoir ajouté une configuration channels.imessage activée, vérifiez le pont via OpenClaw :
   openclaw channels status --probe
   
   Vous voulez imessage.privateApi.available: true. Si la valeur indiquée est false, corrigez cela d’abord — consultez Détection des capacités. channels status --probe ne sonde que les comptes configurés et activés.
5. Faites une copie instantanée de votre configuration :
   cp ~/.openclaw/openclaw.json5 ~/.openclaw/openclaw.json5.bak
   

​

Traduction de la configuration

​

Piège du registre de groupes

1. Liste d’autorisation de l’expéditeur / de la cible de chat (channels.imessage.groupAllowFrom) : vérifiée par isAllowedIMessageSender. Met en correspondance les messages entrants par identifiant d’expéditeur, chat_guid, chat_identifier ou chat_id. Même forme que BlueBubbles.
2. Registre de groupes (channels.imessage.groups) : vérifié par resolveChannelGroupPolicy depuis inbound-processing.ts:199. Avec groupPolicy: "allowlist", cette porte exige soit :
   • une entrée joker groups: { "*": { ... } } (définit allowAll = true), soit
   • une entrée explicite par chat_id sous groups.

• Un warn unique au démarrage par compte lorsque groupPolicy: "allowlist" est défini mais que channels.imessage.groups est vide (aucun joker "*", aucune entrée par chat_id) : déclenché avant l’arrivée du moindre message.
• Un warn unique par chat_id la première fois qu’un groupe précis est supprimé à l’exécution, en indiquant le chat_id et la clé exacte à ajouter à groups pour l’autoriser.

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

​

Pas à pas

1. Ajoutez un bloc iMessage à côté du bloc BlueBubbles existant. Gardez-le désactivé tant que le Gateway route encore le trafic 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. Sondez avant que le trafic ne compte — arrêtez le Gateway, activez temporairement le bloc iMessage, puis confirmez qu’iMessage est sain depuis la CLI :
   openclaw gateway stop
   # edit config: channels.imessage.enabled = true
   openclaw channels status --probe --channel imessage   # expect imessage.privateApi.available: true
   
   channels status --probe sonde uniquement les comptes configurés et activés. Ne redémarrez pas le Gateway avec BlueBubbles et iMessage activés tous les deux, sauf si vous voulez intentionnellement que les deux moniteurs de canal s’exécutent. Si vous ne basculez pas immédiatement, remettez channels.imessage.enabled à false avant de redémarrer le Gateway. Utilisez les commandes imsg directes dans Avant de commencer pour valider le Mac avant d’activer le trafic OpenClaw.
3. Basculez. Une fois que le compte iMessage activé est signalé sain, supprimez la configuration BlueBubbles et gardez iMessage activé :
   {
     channels: {
       imessage: { enabled: true /* ... */ },
     },
   }
   
   Redémarrez le Gateway. Le trafic iMessage entrant passe désormais par le Plugin intégré.
4. Vérifiez les DM. Envoyez un message direct à l’agent ; confirmez que la réponse arrive.
5. Vérifiez les groupes séparément. Les DM et les groupes empruntent des chemins de code différents — le succès des DM ne prouve pas que les groupes sont routés. Envoyez un message à l’agent dans une discussion de groupe appairée et confirmez que la réponse arrive. Si le groupe devient silencieux (pas de réponse de l’agent, pas d’erreur), consultez le journal du Gateway pour imessage: dropping group message from chat_id=<id> ou la ligne de démarrage imessage: groupPolicy="allowlist" but channels.imessage.groups is empty — les deux apparaissent au niveau de journalisation par défaut. Si l’une des deux apparaît, votre bloc groups est manquant ou vide — voir « Piège du registre des groupes » ci-dessus.
6. Vérifiez la surface d’action — depuis un DM appairé, demandez à l’agent de réagir, modifier, annuler l’envoi, répondre, envoyer une photo et (dans un groupe) renommer le groupe / ajouter ou retirer un participant. Chaque action doit arriver nativement dans Messages.app. Si l’une d’elles renvoie « iMessage <action> requires the imsg private API bridge », exécutez de nouveau imsg launch et actualisez channels status --probe.
7. Supprimez le serveur et la configuration BlueBubbles une fois les DM, groupes et actions iMessage vérifiés. OpenClaw n’utilisera pas channels.bluebubbles.

​

Parité des actions en un coup d’œil

​

Appairage, sessions et liaisons ACP

• Les approbations d’appairage sont conservées par handle. Vous n’avez pas besoin de réapprouver les expéditeurs connus — channels.imessage.allowFrom reconnaît les mêmes chaînes +15555550123 / user@example.com que BlueBubbles utilisait.
• Les sessions restent limitées par agent + discussion. Les DM se replient dans la session principale de l’agent avec session.dmScope=main par défaut ; les sessions de groupe restent isolées par chat_id. Les clés de session diffèrent (agent:<id>:imessage:group:<chat_id> par rapport à l’équivalent BlueBubbles) — l’ancien historique de conversation sous les clés de session BlueBubbles n’est pas transféré dans les sessions iMessage.
• Les liaisons ACP qui référencent match.channel: "bluebubbles" doivent être mises à jour vers "imessage". Les formes de match.peer.id (chat_id:, chat_guid:, chat_identifier:, handle nu) sont identiques.

​

Aucun canal de retour arrière

​

Liens associés

• Suppression de BlueBubbles et chemin iMessage imsg — annonce courte et résumé pour opérateurs.
• iMessage — référence complète du canal iMessage, y compris la configuration imsg launch et la détection des capacités.
• /channels/bluebubbles — URL héritée qui redirige vers ce guide de migration.
• Appairage — authentification des DM et flux d’appairage.
• Routage des canaux — comment le Gateway choisit un canal pour les réponses sortantes.