Mainstream messaging

Migrer depuis BlueBubbles

Le Plugin imessage fourni accède désormais à la même surface d’API privée que BlueBubbles (react, edit, unsend, reply, sendWithEffect, gestion des groupes, pièces jointes) en pilotant steipete/imsg via JSON-RPC. Si vous exécutez déjà un Mac avec imsg installé, vous pouvez supprimer le serveur BlueBubbles et laisser le Plugin communiquer directement avec Messages.app.

La prise en charge de BlueBubbles a été supprimée. OpenClaw prend en charge iMessage uniquement via imsg. Ce guide sert à migrer les anciennes configurations channels.bluebubbles vers channels.imessage; aucun autre chemin de migration n’est pris en charge.

Liste de contrôle de migration

Utilisez cette liste de contrôle lorsque vous connaissez déjà votre ancienne configuration BlueBubbles et souhaitez le chemin sûr le plus court :

Vérifiez imsg directement sur le Mac qui exécute Messages.app (imsg chats, imsg history, imsg send et imsg rpc --help).
Copiez les clés de comportement de channels.bluebubbles vers channels.imessage : dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups, includeAttachments, attachmentRoots, mediaMaxMb, textChunkLimit, coalesceSameSenderDms et actions.
Supprimez les clés de transport qui n’existent plus : serverUrl, password, les URL de Webhook et la configuration du serveur BlueBubbles.
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 de pièces jointes distantes.
Avec le Gateway arrêté, activez channels.imessage, puis exécutez openclaw channels status --probe --channel imessage.
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 de l’agent.
Supprimez le serveur BlueBubbles et l’ancienne configuration channels.bluebubbles après vérification du chemin iMessage.

Quand cette migration est pertinente

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

Ce que fait imsg

imsg est une CLI macOS locale pour Messages. OpenClaw lance imsg rpc comme processus enfant et communique en JSON-RPC via stdin/stdout. Il n’y a aucun serveur HTTP, URL de Webhook, démon en arrière-plan, agent launchd ni port à exposer.

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 une solution de repli par interrogation.
Les envois utilisent l’automatisation de Messages.app pour les envois normaux de texte et 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, les réponses 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 OpenClaw iMessage, exécutez imsg sur le Mac connecté ou via un wrapper SSH vers ce Mac.

Avant de commencer

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.
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 issu de imsg chats. L’envoi nécessite l’autorisation d’automatisation pour Messages.app. Si OpenClaw doit s’exécuter via SSH, lancez ces commandes via le même wrapper SSH ou le même contexte utilisateur qu’OpenClaw utilisera.
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 non.
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. S’il indique false, corrigez cela d’abord — consultez Détection des capacités. channels status --probe ne sonde que les comptes configurés et activés.

Prenez un instantané de votre configuration :

cp ~/.openclaw/openclaw.json5 ~/.openclaw/openclaw.json5.bak

Traduction de configuration

iMessage et BlueBubbles partagent beaucoup de configuration au niveau du canal. Les clés qui changent concernent surtout le transport (serveur REST vs CLI locale). Les clés de comportement (dmPolicy, groupPolicy, allowFrom, etc.) conservent la même signification.

BlueBubbles	iMessage groupé	Notes
`channels.bluebubbles.enabled`	`channels.imessage.enabled`	Même sémantique.
`channels.bluebubbles.serverUrl`	(supprimé)	Pas de serveur REST : le plugin lance `imsg rpc` via stdio.
`channels.bluebubbles.password`	(supprimé)	Aucune authentification Webhook nécessaire.
(implicite)	`channels.imessage.cliPath`	Chemin vers `imsg` (par défaut `imsg`) ; utilisez un script wrapper pour SSH.
(implicite)	`channels.imessage.dbPath`	Remplacement facultatif de `chat.db` de Messages.app ; détecté automatiquement s’il est omis.
(implicite)	`channels.imessage.remoteHost`	`host` ou `user@host` : nécessaire uniquement lorsque `cliPath` est un wrapper SSH et que vous voulez récupérer les pièces jointes par SCP.
`channels.bluebubbles.dmPolicy`	`channels.imessage.dmPolicy`	Mêmes valeurs (`pairing` / `allowlist` / `open` / `disabled`).
`channels.bluebubbles.allowFrom`	`channels.imessage.allowFrom`	Les approbations d’appairage sont reprises par identifiant, pas par jeton.
`channels.bluebubbles.groupPolicy`	`channels.imessage.groupPolicy`	Mêmes valeurs (`allowlist` / `open` / `disabled`).
`channels.bluebubbles.groupAllowFrom`	`channels.imessage.groupAllowFrom`	Identique.
`channels.bluebubbles.groups`	`channels.imessage.groups`	*Copiez ceci tel quel, y compris toute entrée générique `groups: { "": { ... } }`.** Les paramètres par groupe `requireMention`, `tools`, `toolsBySender` sont repris. Avec `groupPolicy: "allowlist"`, un bloc `groups` vide ou manquant ignore silencieusement tous les messages de groupe — voir « Piège du registre des groupes » ci-dessous.
`channels.bluebubbles.sendReadReceipts`	`channels.imessage.sendReadReceipts`	Par défaut `true`. Avec le plugin groupé, cela ne se déclenche que lorsque la sonde d’API privée est active.
`channels.bluebubbles.includeAttachments`	`channels.imessage.includeAttachments`	Même forme, toujours désactivé par défaut. Si les pièces jointes circulaient sur BlueBubbles, vous devez le redéfinir explicitement dans le bloc iMessage : il n’est pas repris implicitement, et les photos/médias entrants seront ignorés silencieusement sans ligne de journal `Inbound message` jusqu’à ce que vous le fassiez.
`channels.bluebubbles.attachmentRoots`	`channels.imessage.attachmentRoots`	Racines locales ; mêmes règles de caractères génériques.
(N/A)	`channels.imessage.remoteAttachmentRoots`	Utilisé uniquement lorsque `remoteHost` est défini pour les récupérations SCP.
`channels.bluebubbles.mediaMaxMb`	`channels.imessage.mediaMaxMb`	Par défaut 16 Mo sur iMessage (la valeur par défaut de BlueBubbles était 8 Mo). Définissez-la explicitement si vous voulez conserver la limite plus basse.
`channels.bluebubbles.textChunkLimit`	`channels.imessage.textChunkLimit`	Par défaut 4000 sur les deux.
`channels.bluebubbles.coalesceSameSenderDms`	`channels.imessage.coalesceSameSenderDms`	Même option d’activation. DM uniquement : les discussions de groupe conservent l’envoi instantané message par message sur les deux canaux. Élargit le debounce entrant par défaut à 2500 ms lorsqu’il est activé sans `messages.inbound.byChannel.imessage` explicite. Voir docs iMessage § Coalescing split-send DMs.
`channels.bluebubbles.enrichGroupParticipantsFromContacts`	(N/A)	iMessage lit déjà les noms d’affichage des expéditeurs depuis `chat.db`.
`channels.bluebubbles.actions.*`	`channels.imessage.actions.*`	Options par action : `reactions`, `edit`, `unsend`, `reply`, `sendWithEffect`, `renameGroup`, `setGroupIcon`, `addParticipant`, `removeParticipant`, `leaveGroup`, `sendAttachment`.

Les configurations multi-comptes (channels.bluebubbles.accounts.*) se traduisent une pour une vers channels.imessage.accounts.*.

Piège du registre des groupes

Le plugin iMessage groupé exécute deux contrôles de liste d’autorisation de groupe distincts l’un après l’autre. Les deux doivent réussir pour qu’un message de groupe atteigne l’agent :

Liste d’autorisation de l’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.
Registre des 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.

Si le contrôle 1 réussit mais que le contrôle 2 échoue, le message est ignoré. Le plugin émet deux signaux de niveau warn, ce qui fait que ce n’est plus silencieux au niveau de journalisation par défaut :

Un warn unique au démarrage par compte lorsque groupPolicy: "allowlist" est défini mais que channels.imessage.groups est vide (pas de caractère générique "*", pas d’entrées 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 ignoré à l’exécution, indiquant le chat_id et la clé exacte à ajouter à groups pour l’autoriser.

Les DM continuent de fonctionner, car ils empruntent un chemin de code différent.

C’est le mode d’échec le plus courant lors d’une migration BlueBubbles → iMessage groupé : les opérateurs copient groupAllowFrom et groupPolicy, mais omettent le bloc groups, parce que groups: { "*": { "requireMention": true } } de BlueBubbles ressemble à un paramètre de mention sans rapport. Il est en réalité indispensable au contrôle du registre.

La configuration minimale pour que les messages de groupe continuent de circuler après groupPolicy: "allowlist" :

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

requireMention: true sous * est sans effet néfaste lorsqu’aucun motif de mention n’est configuré : le runtime définit canDetectMention = false et court-circuite l’abandon de mention à inbound-processing.ts:512. Avec des motifs de mention configurés (agents.list[].groupChat.mentionPatterns), cela fonctionne comme prévu.

Si les journaux du Gateway indiquent imessage: dropping group message from chat_id=<id> ou la ligne de démarrage imessage: groupPolicy="allowlist" but channels.imessage.groups is empty, le filtre 2 bloque le message — ajoutez le bloc groups.

Étape par étape

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,
      },
    },
  },
}

Sondez avant que le trafic ne compte — arrêtez le Gateway, activez temporairement le bloc iMessage et confirmez qu’iMessage est signalé comme 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 ne sonde que les comptes configurés et activés. Ne redémarrez pas le Gateway avec BlueBubbles et iMessage activés en même temps, sauf si vous voulez intentionnellement faire fonctionner les deux moniteurs de canal. 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.
Basculez. Une fois que le compte iMessage activé est signalé comme 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 groupé.
Vérifiez les messages directs. Envoyez un message direct à l’agent ; confirmez que la réponse arrive.
Vérifiez les groupes séparément. Les messages directs et les groupes empruntent des chemins de code différents — la réussite d’un message direct ne prouve pas que les groupes sont routés. Envoyez un message à l’agent dans une conversation de groupe associé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 — les deux se déclenchent au niveau de journalisation par défaut. Si l’une des deux apparaît, votre bloc groups est manquant ou vide — consultez « Piège du registre de groupes » ci-dessus.
Vérifiez la surface d’actions — depuis un message direct associé, 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 génère « iMessage <action> requires the imsg private API bridge », exécutez de nouveau imsg launch et actualisez channels status --probe.
Supprimez le serveur et la configuration BlueBubbles une fois les messages directs, les groupes et les actions iMessage vérifiés. OpenClaw n’utilisera pas channels.bluebubbles.

Parité des actions en un coup d’œil

Action	BlueBubbles hérité	iMessage groupé
Envoyer du texte / repli SMS	✅	✅
Envoyer des médias (photo, vidéo, fichier, voix)	✅	✅
Réponse en fil (`reply_to_guid`)	✅	✅ (ferme #51892)
Tapback (`react`)	✅	✅
Modifier / annuler l’envoi (destinataires macOS 13+)	✅	✅
Envoyer avec effet d’écran	✅	✅ (ferme une partie de #9394)
Texte enrichi gras / italique / souligné / barré	✅	✅ (formatage par séries typées via attributedBody)
Renommer le groupe / définir l’icône du groupe	✅	✅
Ajouter / supprimer un participant, quitter le groupe	✅	✅
Confirmations de lecture et indicateur de saisie	✅	✅ (conditionné par la sonde d’API privée)
Coalescence des messages directs du même expéditeur	✅	✅ (messages directs uniquement ; optionnel via `channels.imessage.coalesceSameSenderDms`)
Rattrapage des messages entrants reçus lorsque le Gateway est arrêté	✅ (relecture Webhook + récupération d’historique)	✅ (optionnel via `channels.imessage.catchup.enabled` ; ferme #78649)

Le rattrapage iMessage est désormais disponible comme fonctionnalité optionnelle dans le Plugin groupé. Au démarrage du Gateway, si channels.imessage.catchup.enabled vaut true, le Gateway exécute un passage chats.list + messages.history par conversation sur le même client JSON-RPC que celui utilisé par imsg watch, rejoue chaque ligne entrante manquée via le chemin de dispatch actif (listes d’autorisation, politique de groupe, anti-rebond, cache d’écho) et persiste un curseur par compte afin que les démarrages suivants reprennent là où ils s’étaient arrêtés. Consultez Rattraper après une indisponibilité du Gateway pour les réglages.

Association, sessions et liaisons ACP

Les approbations d’association 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 que BlueBubbles utilisait.
Les sessions restent limitées par agent + conversation. Les messages directs 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é vers les sessions iMessage.
Les liaisons ACP référençant 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 retour arrière

Il n’existe aucun runtime BlueBubbles pris en charge vers lequel revenir. Si la vérification iMessage échoue, définissez channels.imessage.enabled: false, redémarrez le Gateway, corrigez le blocage imsg, puis réessayez la bascule.

Le cache de réponse se trouve dans ~/.openclaw/state/imessage/reply-cache.jsonl (mode 0600, répertoire parent 0700). Vous pouvez le supprimer sans risque si vous voulez repartir de zéro.

Liens associés

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

# Liste de contrôle de migration

# Quand cette migration est pertinente

# Ce que fait imsg

# Avant de commencer

# Traduction de configuration

# Piège du registre des groupes

# Étape par étape

# Parité des actions en un coup d’œil

# Association, sessions et liaisons ACP

# Aucun canal de retour arrière

# Liens associés

Liste de contrôle de migration

Quand cette migration est pertinente

Ce que fait imsg

Avant de commencer

Traduction de configuration

Piège du registre des groupes

Étape par étape

Parité des actions en un coup d’œil

Association, sessions et liaisons ACP

Aucun canal de retour arrière

Liens associés