Si vous venez de 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.

​

Quand cette migration est pertinente

• Vous exécutez déjà imsg sur le même Mac (ou sur un Mac accessible via SSH) où Messages.app est connecté.
• Vous voulez un composant en moins — pas de serveur BlueBubbles séparé, pas de point de terminaison REST à authentifier, pas de câblage 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 au moyen d’un descripteur 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 le texte normal et les 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 versions Linux peuvent inspecter un chat.db copié, mais ne peuvent pas envoyer de messages, surveiller la base de données Mac en direct ni piloter Messages.app. Pour OpenClaw iMessage, 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 véritable identifiant de discussion provenant de imsg chats. L’envoi nécessite l’autorisation d’automatisation pour Messages.app. Si OpenClaw s’exécute via SSH, exécutez ces commandes avec le même wrapper SSH ou le même contexte utilisateur que celui qu’OpenClaw utilisera.
3. Activez le pont d’API privée lorsque vous avez besoin d’actions avancées :
   imsg launch
   imsg status --json
   
   imsg launch exige que SIP soit désactivé. L’envoi de base, l’historique et la surveillance fonctionnent sans imsg launch ; les actions avancées ne fonctionnent pas.
4. Vérifiez le pont via OpenClaw :
   openclaw channels status --probe
   
   Vous voulez imessage.privateApi.available: true. S’il indique false, corrigez d’abord cela — consultez Détection des capacités.
5. Créez un instantané 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 expéditeur / cible de discussion (channels.imessage.groupAllowFrom) — vérifiée par isAllowedIMessageSender. Correspond aux 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", ce contrôle exige soit :
   • une entrée générique groups: { "*": { ... } } (définit allowAll = true), soit
   • une entrée explicite par chat_id sous groups.

• Un warn de démarrage unique par compte lorsque groupPolicy: "allowlist" est défini mais que channels.imessage.groups est vide (aucun caractère générique "*", aucune entrée par chat_id) — déclenché avant l’arrivée de tout message.
• Un warn unique par chat_id la première fois qu’un groupe spécifique est ignoré à l’exécution, en nommant le chat_id et la clé exacte à ajouter à groups pour l’autoriser.

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

​

Étape par étape

1. Ajoutez un bloc iMessage à côté du bloc BlueBubbles existant. Conservez l’ancien bloc uniquement comme source de copie jusqu’à ce que le nouveau chemin soit vérifié :
   {
     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. Sonde d’essai à blanc — démarrez le Gateway et confirmez qu’iMessage indique un état sain :
   openclaw gateway
   openclaw channels status
   openclaw channels status --probe   # expect imessage.privateApi.available: true
   
   Comme imessage.enabled vaut encore false, aucun trafic iMessage entrant n’est encore routé — mais --probe exerce le pont, ce qui vous permet de détecter les problèmes d’autorisation ou d’installation avant le basculement.
3. Basculez. Supprimez la configuration BlueBubbles et activez iMessage en une seule modification de configuration :
   {
     channels: {
       imessage: { enabled: true /* ... */ },
     },
   }
   
   Redémarrez le Gateway. Le trafic iMessage entrant passe maintenant 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 — la réussite des DM ne prouve pas que les groupes sont routés. Envoyez un message à l’agent dans une conversation de groupe appairée et confirmez que la réponse arrive. Si le groupe devient silencieux (aucune réponse de l’agent, aucune erreur), vérifiez dans le journal du Gateway la présence de imessage: dropping group message from chat_id=<id> ou de la ligne de démarrage imessage: groupPolicy="allowlist" but channels.imessage.groups is empty — toutes deux se déclenchent au niveau de journalisation par défaut. Si l’une ou l’autre apparaît, votre bloc groups est manquant ou vide — consultez « Piège du registre de 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 supprimer 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 à nouveau imsg launch et actualisez channels status --probe.
7. Supprimez le serveur et la configuration BlueBubbles une fois que les DM, groupes et actions iMessage sont vérifiés. OpenClaw n’utilisera pas channels.bluebubbles.

​

Parité des actions en bref

​

Appairage, sessions et liaisons ACP

• Les approbations d’appairage sont conservées par identifiant. 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 qu’utilisait BlueBubbles.
• Les sessions restent limitées par agent + conversation. Les DM se replient dans la session principale de l’agent avec le 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:, identifiant nu) sont identiques.

​

Aucun canal de rollback

​

Connexe

• 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 DM et flux d’appairage.
• Routage des canaux — comment le Gateway choisit un canal pour les réponses sortantes.