iMessage

État : intégration CLI externe native. Le Gateway lance imsg rpc et communique en JSON-RPC via les flux d’entrée/sortie standard — aucun démon ni port séparé. Le mode API privée est vivement recommandé pour disposer d’un canal iMessage complet ; les réponses, réactions tapback, effets, sondages, réponses aux pièces jointes et actions de groupe nécessitent imsg launch et une vérification réussie de l’API privée.

Pour la configuration locale courante, l’assistant de configuration d’OpenClaw peut proposer, après confirmation de l’utilisateur, d’installer ou de mettre à jour imsg avec Homebrew sur le Mac connecté à Messages. La configuration manuelle et les topologies utilisant un wrapper SSH restent gérées par l’opérateur : installez ou mettez à jour imsg dans le même contexte utilisateur que celui qui exécutera le Gateway ou le wrapper.

Configuration rapide

brew install steipete/tap/imsgbrew update && brew upgrade imsgimsg rpc --helpimsg launchopenclaw channels status --probe

{channels: {imessage: {enabled: true,cliPath: "/usr/local/bin/imsg",dbPath: "/Users/user/Library/Messages/chat.db",},},}

openclaw gateway

openclaw pairing list imessageopenclaw pairing approve imessage <CODE>

ssh messages-mac 'brew install steipete/tap/imsg && brew update && brew upgrade imsg'

#!/usr/bin/env bashexec ssh -T messages-mac imsg "$@"

{channels: {imessage: {  enabled: true,  cliPath: "~/.openclaw/scripts/imsg-ssh",  remoteHost: "user@gateway-host", // utilisé pour récupérer les pièces jointes via SCP  includeAttachments: true,  // Facultatif : racines de pièces jointes autorisées supplémentaires (fusionnées avec la valeur par défaut  // /Users/*/Library/Messages/Attachments).  attachmentRoots: ["/Users/*/Library/Messages/Attachments"],  remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],},},}

Prérequis et autorisations (macOS)

• Messages doit être connecté sur le Mac exécutant imsg.
• L’accès complet au disque est requis pour le contexte de processus exécutant OpenClaw/imsg (accès à la base de données de Messages).
• L’autorisation d’automatisation est requise pour envoyer des messages via Messages.app.
• Pour les actions avancées (réagir / modifier / annuler l’envoi / réponse dans un fil / effets / sondages / opérations de groupe), la protection de l’intégrité du système doit être désactivée — consultez Activation de l’API privée de imsg. L’envoi et la réception de texte et de contenus multimédias de base fonctionnent sans cela.

Non autorisé à envoyer des événements Apple à Messages. (-1743)

kTCCServiceAppleEvents | /usr/libexec/sshd-keygen-wrapper | auth_value=0 | com.apple.MobileSMS

Activation de l’API privée de imsg

imsg propose deux modes de fonctionnement. Pour OpenClaw, le mode API privée est la configuration recommandée, car il fournit au canal les actions iMessage natives attendues par les utilisateurs. Le mode de base reste utile pour les installations à faible risque, la vérification initiale ou les hôtes sur lesquels SIP ne peut pas être désactivé.

• Mode de base (par défaut, aucune modification de SIP nécessaire) : texte et contenus multimédias sortants via send, surveillance/historique des messages entrants, liste des conversations. C’est ce que fournit directement une nouvelle installation avec brew install steipete/tap/imsg, associée aux autorisations macOS standard indiquées ci-dessus.
• Mode API privée : imsg injecte une dylib auxiliaire dans Messages.app afin d’appeler des fonctions internes de IMCore. Cela active react, edit, unsend, reply (dans un fil), sendWithEffect, poll et poll-vote (sondages natifs de Messages), renameGroup, setGroupIcon, addParticipant, removeParticipant, leaveGroup, ainsi que les indicateurs de saisie et les accusés de lecture.

La surface d’actions recommandée sur cette page nécessite le mode API privée. Le README de imsg énonce explicitement ce prérequis :

Les fonctionnalités avancées telles que read, typing, launch, l’envoi enrichi reposant sur le pont, la modification des messages et la gestion des conversations sont facultatives. Elles nécessitent la désactivation de SIP et l’injection d’une dylib auxiliaire dans Messages.app. imsg launch refuse d’effectuer l’injection lorsque SIP est activé.

La technique d’injection du composant auxiliaire utilise la propre dylib de imsg pour accéder aux API privées de Messages. Aucun serveur tiers ni environnement d’exécution BlueBubbles n’intervient dans le chemin iMessage d’OpenClaw.

Configuration

1. Installez (ou mettez à niveau) imsg sur le Mac qui exécute Messages.app :

   brew install steipete/tap/imsgbrew update && brew upgrade imsgimsg --versionimsg status --json

   La sortie de imsg status --json indique bridge_version, rpc_methods et les selectors propres à chaque méthode, afin que vous puissiez vérifier les fonctionnalités prises en charge par la version actuelle avant de commencer.

2. Désactivez la protection de l’intégrité du système et, sur les versions modernes de macOS, la validation des bibliothèques. L’injection d’une dylib auxiliaire non signée par Apple dans l’application Messages.app signée par Apple nécessite la désactivation de SIP et l’assouplissement de la validation des bibliothèques. L’étape relative à SIP en mode de récupération dépend de la version de macOS :

   • macOS 10.13-10.15 (Sierra-Catalina) : désactivez la validation des bibliothèques via Terminal, redémarrez en mode de récupération, exécutez csrutil disable, puis redémarrez.
   • macOS 11+ (Big Sur et versions ultérieures), Intel : accédez au mode de récupération (ou à la récupération par Internet), exécutez csrutil disable, puis redémarrez.
   • macOS 11+, Apple Silicon : utilisez la séquence de démarrage avec le bouton d’alimentation pour accéder au mode de récupération ; sur les versions récentes de macOS, maintenez la touche Left Shift enfoncée lorsque vous cliquez sur Continue, puis exécutez csrutil disable. Les configurations de machines virtuelles suivent une procédure distincte ; créez donc d’abord un instantané de la machine virtuelle.

   Sur macOS 11 et versions ultérieures, csrutil disable seul ne suffit généralement pas. Apple applique toujours la validation des bibliothèques à Messages.app en tant que binaire de plateforme ; un assistant signé ad hoc est donc rejeté (Library Validation failed: ... platform binary, but mapped file is not) même lorsque SIP est désactivé. Après avoir désactivé SIP, désactivez également la validation des bibliothèques, puis redémarrez :

   sudo defaults write /Library/Preferences/com.apple.security.libraryvalidation.plist DisableLibraryValidation -bool true

   macOS 26 (Tahoe), vérifié sur la version 26.5.1 : la désactivation de SIP ainsi que la commande DisableLibraryValidation ci-dessus suffisent pour injecter l’assistant sur les versions 26.0 à 26.5.x. Aucun argument de démarrage n’est requis. Le fichier plist est le facteur décisif et l’étape manquante la plus courante lorsque l’injection échoue sur Tahoe :

   • Avec le fichier plist : imsg launch effectue l’injection et imsg status indique advanced_features: true.
   • Sans le fichier plist (même avec SIP désactivé) : imsg launch échoue avec Failed to launch: Timeout waiting for Messages.app to initialize. AMFI rejette l’assistant ad hoc lors du chargement ; le pont n’est donc jamais prêt et le lancement expire. Cette expiration est le symptôme que la plupart des utilisateurs rencontrent sur Tahoe ; la solution est le fichier plist ci-dessus, et non une mesure plus radicale.

   Si l’injection par imsg launch ou certains selectors commencent à renvoyer false après une mise à niveau de macOS, cette barrière en est généralement la cause. Vérifiez l’état de SIP et de la validation des bibliothèques avant de supposer que l’étape relative à SIP a elle-même échoué. Si ces réglages sont corrects et que le pont ne parvient toujours pas à effectuer l’injection, recueillez la sortie de imsg status --json ainsi que celle de imsg launch, puis signalez le problème au projet imsg au lieu d’affaiblir d’autres contrôles de sécurité à l’échelle du système.

3. Injectez l’assistant. Avec SIP désactivé et une session ouverte dans Messages.app :

   imsg launch

   imsg launch refuse d’effectuer l’injection lorsque SIP est encore activé ; cela confirme donc également que l’étape 2 a bien été appliquée.

4. Vérifiez le pont depuis OpenClaw :

   openclaw channels status --probe

   L’entrée iMessage doit indiquer works, et imsg status --json | jq '{rpc_methods, selectors}' doit afficher les capacités exposées par votre version de macOS. La création de sondages nécessite selectors.pollPayloadMessage ; le vote nécessite à la fois selectors.pollVoteMessage et la méthode RPC poll.vote. Le plugin OpenClaw n’annonce que les actions prises en charge par la sonde mise en cache, tandis qu’un cache vide reste optimiste et exécute une sonde lors du premier envoi.

Si openclaw channels status --probe indique que le canal works, mais que certaines actions génèrent l’erreur « iMessage <action> requires the imsg private API bridge » lors de l’envoi, exécutez à nouveau imsg launch : l’assistant peut se déconnecter (redémarrage de Messages.app, mise à jour du système d’exploitation, etc.) et l’état available: true mis en cache continuera d’annoncer les actions jusqu’à ce que la prochaine sonde l’actualise.

Lorsque SIP reste activé

Si la désactivation de SIP n’est pas acceptable pour votre modèle de menace :

• imsg revient au mode de base : texte + médias + réception uniquement.
• Le plugin OpenClaw continue d’annoncer l’envoi de texte et de médias ainsi que la surveillance des messages entrants ; il masque react, edit, unsend, reply, sendWithEffect et les opérations de groupe dans la surface d’actions (selon la barrière de capacités propre à chaque méthode).
• Vous pouvez utiliser un Mac distinct sans Apple Silicon (ou un Mac dédié au bot) avec SIP désactivé pour la charge de travail iMessage, tout en conservant SIP activé sur vos appareils principaux. Consultez la section Utilisateur macOS dédié au bot (identité iMessage distincte) ci-dessous.

Contrôle d’accès et routage

{  channels: {    imessage: {      groupPolicy: "allowlist",      groupAllowFrom: ["+15555550123"],

      groups: {

        "*": { systemPrompt: "Utilisez l’orthographe britannique." },

        "8421": {

          requireMention: true,

          systemPrompt: "Ceci est la discussion de rotation d’astreinte. Limitez les réponses à moins de 3 phrases.",

        },        "9907": {

          // suppression explicite : le caractère générique « Use British spelling. » ne s’applique pas ici

          systemPrompt: "",        },

      },    },  },}

Liaisons de conversations ACP

Les conversations iMessage peuvent être liées à des sessions ACP.

Procédure rapide pour l’opérateur :

• Exécutez /acp spawn codex --bind here dans le message privé ou la conversation de groupe autorisée.
• Les messages suivants de cette même conversation iMessage sont acheminés vers la session ACP créée.
• /new et /reset réinitialisent sur place la même session ACP liée.
• /acp close ferme la session ACP et supprime la liaison.

Les liaisons persistantes configurées utilisent des entrées bindings[] de niveau supérieur avec type: "acp" et match.channel: "imessage".

match.peer.id peut utiliser :

• un identifiant de message privé normalisé tel que +15555550123 ou user@example.com
• chat_id:<id> (recommandé pour les liaisons de groupe stables)
• chat_guid:<guid>
• chat_identifier:<identifier>

Exemple :

{  agents: {    list: [      {        id: "codex",        runtime: {          type: "acp",          acp: { agent: "codex", backend: "acpx", mode: "persistent" },        },      },    ],  },  bindings: [    {      type: "acp",      agentId: "codex",      match: {        channel: "imessage",        accountId: "default",        peer: { kind: "group", id: "chat_id:123" },      },      acp: { label: "codex-group" },    },  ],}

Consultez Agents ACP pour connaître le comportement partagé des liaisons ACP.

Modèles de déploiement

{  channels: {    imessage: {      enabled: true,      cliPath: "~/.openclaw/scripts/imsg-ssh",      remoteHost: "bot@mac-mini.tailnet-1234.ts.net",      includeAttachments: true,      dbPath: "/Users/bot/Library/Messages/chat.db",    },  },}

#!/usr/bin/env bashexec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"

Médias, découpage et cibles de livraison

imsg chats --limit 20

Actions de l’API privée

Lorsque imsg launch est en cours d’exécution et que openclaw channels status --probe indique privateApi.available: true, l’outil de messagerie peut utiliser des actions iMessage natives en plus des envois de texte normaux.

Toutes les actions sont activées par défaut ; utilisez channels.imessage.actions pour désactiver des actions individuellement :

{  channels: {    imessage: {      actions: {        reactions: true,        edit: true,        unsend: true,        reply: true,        sendWithEffect: true,        sendAttachment: true,        renameGroup: true,        setGroupIcon: true,        addParticipant: true,        removeParticipant: true,        leaveGroup: true,        polls: true,      },    },  },}

{  channels: {    imessage: {      sendReadReceipts: false,    },  },}

Écritures de configuration

iMessage autorise par défaut les écritures de configuration initiées par le canal (pour /config set|unset lorsque commands.config: true).

Pour les désactiver :

{  channels: {    imessage: {      configWrites: false,    },  },}

Regroupement des messages directs envoyés séparément (commande + URL dans une même composition)

Lorsqu’un utilisateur saisit ensemble une commande et une URL — par exemple Dump https://example.com/article — l’application Messages d’Apple scinde l’envoi en deux lignes chat.db distinctes :

1. Un message texte ("Dump").
2. Une bulle d’aperçu d’URL ("https://...") avec des images d’aperçu OG comme pièces jointes.

Les deux lignes arrivent dans OpenClaw à environ 0.8-2.0 s d’intervalle dans la plupart des configurations. Sans regroupement, l’agent reçoit uniquement la commande au tour 1 (et répond souvent « envoyez-moi l’URL ») avant que l’URL n’arrive au tour 2. Cela relève du pipeline d’envoi d’Apple, et non d’un comportement introduit par OpenClaw ou imsg.

channels.imessage.coalesceSameSenderDms permet à un message privé de mettre en mémoire tampon les lignes consécutives provenant du même expéditeur. Lorsque imsg expose le marqueur structurel d’aperçu d’URL balloon_bundle_id: "com.apple.messages.URLBalloonProvider" sur l’une des lignes sources, OpenClaw fusionne uniquement cet envoi réellement scindé et conserve toutes les autres lignes mises en mémoire tampon sous forme de tours distincts. Sur les anciennes versions d’imsg qui n’émettent aucune métadonnée de bulle, OpenClaw ne peut pas distinguer un envoi scindé d’envois séparés ; il revient donc à la fusion du lot. Cela préserve le comportement antérieur aux métadonnées au lieu de faire régresser les envois scindés Dump <url> en deux tours. Les discussions de groupe continuent à être distribuées message par message afin de préserver la structure des tours entre plusieurs utilisateurs.

{  channels: {    imessage: {      coalesceSameSenderDms: true, // activer explicitement (valeur par défaut : false)    },  },}

{  messages: {    inbound: {      byChannel: {        // 7000 ms couvrent les délais d’aperçu d’URL observés dans Messages.app.        imessage: 7000,      },    },  },}

Scénarios et données reçues par l’agent

La colonne « Option activée » présente le comportement sur une version d’imsg qui émet balloon_bundle_id. Sur les anciennes versions d’imsg qui n’émettent aucune métadonnée de bulle, les lignes ci-dessous marquées « Deux tours » ou « N tours » reviennent plutôt à la fusion historique (un seul tour) : OpenClaw ne peut pas distinguer structurellement un envoi scindé d’envois séparés ; il préserve donc la fusion antérieure aux métadonnées. La séparation précise s’active dès que la version émet les métadonnées de bulle.

Récupération des messages entrants après le redémarrage d’un pont ou du Gateway

iMessage récupère les messages manqués pendant l’arrêt du Gateway et supprime en même temps l’ancienne « avalanche de messages en attente » qu’Apple peut envoyer après une récupération Push. Le comportement par défaut est toujours actif et repose sur la déduplication des messages entrants.

• Déduplication de la relecture. Chaque message entrant distribué est enregistré à l’aide de son GUID Apple dans l’état persistant du Plugin (imessage.inbound-dedupe), réservé lors de l’ingestion et validé après le traitement (puis libéré en cas d’échec temporaire afin de permettre une nouvelle tentative). Tout élément déjà traité est ignoré au lieu d’être distribué deux fois. Cela permet à la récupération de relire les messages de manière intensive sans suivi individuel.
• Récupération après une interruption. Au démarrage, le moniteur mémorise le dernier identifiant de ligne chat.db distribué (un curseur persistant par compte) et le transmet à imsg watch.subscribe sous la forme since_rowid, afin qu’imsg relise les lignes reçues pendant l’arrêt du Gateway, puis suive les nouvelles lignes en direct. La relecture est limitée aux 500 lignes les plus récentes et aux messages datant d’au plus ~2 heures, tandis que la déduplication élimine tout élément déjà traité.
• Barrière d’âge pour les anciens messages en attente. Les lignes situées au-dessus de la limite de démarrage sont réellement reçues en direct ; toute ligne dont la date d’envoi précède son arrivée de plus de ~15 minutes appartient aux anciens messages en attente vidés par Push et est supprimée. Les lignes relues (situées au niveau ou en dessous de la limite) utilisent plutôt la fenêtre de récupération élargie, afin qu’un message récemment manqué soit distribué sans inclure l’historique ancien.

La récupération fonctionne avec les configurations cliPath locales et distantes, car la relecture since_rowid utilise la même connexion RPC imsg. La différence concerne la fenêtre : lorsque le Gateway peut lire chat.db (en local), il ancre la limite d’identifiant de ligne au démarrage, plafonne la plage de relecture et distribue les messages manqués datant d’au plus quelques heures. Avec un cliPath SSH distant, il ne peut pas lire la base de données ; la relecture n’est donc pas plafonnée et chaque ligne utilise la barrière d’âge des messages en direct. Il récupère toujours les messages récemment manqués et supprime toujours les anciens messages en attente, mais avec la fenêtre plus étroite des messages en direct. Exécutez le Gateway sur le Mac hébergeant Messages pour bénéficier de la fenêtre de récupération élargie.

Signal visible par l’opérateur

Les anciens messages en attente supprimés sont consignés au niveau par défaut et ne sont jamais ignorés silencieusement (l’indicateur recovery précise la fenêtre appliquée) :

imessage: ancien lot entrant supprimé account=<id> sent=<iso> recovery=<bool> (&lt;N&gt; supprimés depuis le démarrage)

Migration

channels.imessage.catchup.* est obsolète — la récupération après une interruption est automatique et ne nécessite aucune configuration pour les nouvelles installations. Les configurations existantes avec catchup.enabled: true restent prises en charge comme profil de compatibilité pour la fenêtre de relecture de récupération. Les blocs de rattrapage désactivés (enabled: false ou sans enabled: true) sont retirés ; openclaw doctor --fix les supprime.

Dépannage

imsg rpc --helpimsg status --jsonopenclaw channels status --probe

imsg chats --limit 10 --jsonimsg watch --chat-id <chat-id> --jsonsqlite3 ~/Library/Messages/chat.db \"select datetime(max(date)/1000000000 + 978307200, 'unixepoch', 'localtime'), max(ROWID) from message;"

launchctl kickstart -k system/com.apple.apsdlaunchctl kickstart -k gui/$(id -u)/com.apple.CommCenterlaunchctl kickstart -k gui/$(id -u)/com.apple.identityservicesdlaunchctl kickstart -k gui/$(id -u)/com.apple.imagentimsg launchopenclaw gateway restart

#!/usr/bin/env bashexec ssh -T messages-mac imsg "$@"

openclaw channels status --probe --channel imessage

imsg chats --limit 1imsg send <handle> "test"

Liens vers la référence de configuration

• Référence de configuration — iMessage
• Configuration du Gateway
• Appairage

Pages connexes

• Vue d’ensemble des canaux — tous les canaux pris en charge
• Suppression de BlueBubbles et parcours iMessage avec imsg — annonce et résumé de la migration
• Migration depuis BlueBubbles — tableau de correspondance de la configuration et procédure de basculement détaillée
• Appairage — authentification des messages privés et processus d’appairage
• Groupes — comportement des discussions de groupe et filtrage par mention
• Routage des canaux — routage des sessions pour les messages
• Sécurité — modèle d’accès et renforcement de la sécurité