iMessage

État : intégration à une CLI externe native. Le Gateway lance imsg rpc et communique en JSON-RPC sur les flux d’entrée/sortie standard — aucun démon ni port distinct. Le mode API privée est fortement recommandé pour disposer d’un canal iMessage complet ; les réponses, les tapbacks, les effets, les sondages, les réponses aux pièces jointes et les actions de groupe nécessitent imsg launch ainsi qu’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", // used for SCP attachment fetches  includeAttachments: true,  // Optional: extra allowed attachment roots (merged with the default  // /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 qui exécute imsg.
• L’accès complet au disque est requis pour le contexte de processus qui exécute OpenClaw/imsg (accès à la base de données de Messages).
• L’autorisation Automatisation est requise pour envoyer des messages via Messages.app.
• Pour les actions avancées (réaction / modification / annulation de 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 d’imsg. L’envoi et la réception de texte et de contenus multimédias de base fonctionnent sans la désactiver.

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 d’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 la protection de l’intégrité du système ne peut pas être désactivée.

• Mode de base (par défaut, aucune modification de la protection de l’intégrité du système requise) : texte et contenus multimédias sortants via send, surveillance et historique entrants, liste des conversations. C’est ce qui est disponible immédiatement avec une nouvelle installation de brew install steipete/tap/imsg et les autorisations macOS standard indiquées ci-dessus.
• Mode API privée : imsg injecte une bibliothèque dynamique auxiliaire dans Messages.app afin d’appeler des fonctions internes IMCore. Cela débloque react, edit, unsend, reply (dans un fil), sendWithEffect, poll et poll-vote (sondages Messages natifs), 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 indique explicitement ce prérequis :

Les fonctionnalités avancées telles que read, typing, launch, l’envoi enrichi fourni par le pont, la modification des messages et la gestion des conversations sont facultatives. Elles nécessitent la désactivation de la protection de l’intégrité du système et l’injection d’une bibliothèque dynamique auxiliaire dans Messages.app. imsg launch refuse de procéder à l’injection lorsque la protection de l’intégrité du système est activée.

La technique d’injection de l’auxiliaire utilise la propre bibliothèque dynamique de imsg pour accéder aux API privées de Messages. Le chemin iMessage d’OpenClaw ne comporte aucun serveur tiers ni environnement d’exécution BlueBubbles.

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 selectors pour chaque méthode, afin que vous puissiez voir ce que la version actuelle prend en charge avant de commencer.

2. Désactivez la protection de l’intégrité du système ainsi que, sur les versions récentes de macOS, la validation des bibliothèques. L’injection d’une dylib auxiliaire non-Apple dans Messages.app, signé par Apple, nécessite de désactiver SIP et d’assouplir la validation des bibliothèques. L’étape de désactivation de 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 : passez en mode de récupération (ou 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 machine virtuelle suivent une procédure distincte ; créez donc d’abord un instantané de la VM.

   Sur macOS 11 et les 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 auxiliaire 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 et redémarrez :

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

   macOS 26 (Tahoe), vérifié sur 26.5.1 : la désactivation de SIP associée à la commande DisableLibraryValidation ci-dessus suffit pour injecter l’auxiliaire sur les versions 26.0 à 26.5.x. Aucun argument de démarrage n’est requis. Le fichier plist est le facteur déterminant 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’auxiliaire ad hoc lors du chargement ; le bridge n’est donc jamais prêt et le lancement expire. Cette expiration est le symptôme le plus fréquemment rencontré sur Tahoe ; la solution consiste à utiliser le fichier plist ci-dessus, et non à prendre des mesures plus radicales.

   Si l’injection de imsg launch ou certaines opérations de selectors commencent à renvoyer false après une mise à niveau de macOS, ce contrôle 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 de désactivation de SIP elle-même a échoué. Si ces réglages sont corrects et que le bridge ne parvient toujours pas à effectuer l’injection, collectez imsg status --json ainsi que la sortie 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’auxiliaire. Avec SIP désactivé et Messages.app connecté :

   imsg launch

   imsg launch refuse d’effectuer l’injection tant que SIP est activé ; cette commande permet donc aussi de confirmer que l’étape 2 a bien été effectuée.

4. Vérifiez le bridge depuis OpenClaw :

   openclaw channels status --probe

   L’entrée iMessage doit indiquer works, et imsg status --json | jq '{rpc_methods, selectors}' doit afficher les fonctionnalités exposées par votre build 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 ; si le cache est vide, il reste optimiste et effectue une sonde lors du premier envoi.

Si openclaw channels status --probe indique que le canal est 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’auxiliaire peut se détacher (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 repasse en mode de base : texte, médias et 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 de la surface d’actions, conformément au contrôle des fonctionnalités propre à chaque méthode.
• Vous pouvez utiliser un autre Mac 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: "Il s’agit de la discussion de rotation des permanences. Limitez les réponses à moins de 3 phrases.",        },        "9907": {          // neutralisation explicite : le caractère générique « Utilisez l’orthographe britannique. » ne s’applique pas ici          systemPrompt: "",        },      },    },  },}

Liaisons de conversations ACP

Les discussions 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 discussion de groupe autorisée.
• Les messages ultérieurs 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 premier niveau 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 commun 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 natives d’iMessage en plus des envois de texte ordinaires.

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

Écriture de la configuration

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

Pour désactiver cette fonctionnalité :

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

Regroupement des messages privés 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 divise l’envoi en deux lignes chat.db distinctes :

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

Sur la plupart des configurations, les deux lignes parviennent à OpenClaw à environ 0.8-2.0 s d’intervalle. 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 provient du pipeline d’envoi d’Apple, et non d’OpenClaw ou de imsg.

channels.imessage.coalesceSameSenderDms active pour un message privé la mise en mémoire tampon des 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 divisé et conserve les autres lignes mises en mémoire tampon sous forme de tours distincts. Sur les anciennes versions de imsg qui n’émettent aucune métadonnée de bulle, OpenClaw ne peut pas distinguer un envoi divisé de plusieurs envois distincts ; il fusionne donc le lot par défaut. Cela préserve le comportement antérieur aux métadonnées au lieu de faire régresser les envois divisés de Dump <url> en deux tours. Les conversations de groupe continuent à distribuer chaque message séparément afin de préserver la structure des tours impliquant plusieurs utilisateurs.

{  channels: {    imessage: {      coalesceSameSenderDms: true, // activation explicite (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 contenu reçu par l’agent

La colonne « Option activée » présente le comportement sur une version de imsg qui émet balloon_bundle_id. Sur les anciennes versions de imsg qui n’émettent aucune métadonnée de bulle, les lignes ci-dessous indiquées comme « Deux tours » / « N tours » reviennent plutôt à une fusion historique (un tour) : OpenClaw ne peut pas distinguer structurellement un envoi divisé de plusieurs envois distincts et préserve donc la fusion antérieure aux métadonnées. La séparation précise s’active dès que la version émet des 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, tout en supprimant l’ancienne « avalanche de messages en attente » qu’Apple peut libérer 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 des réexécutions. 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 supprimé au lieu d’être distribué deux fois. Cela permet à la récupération de réexécuter 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 rowid de chat.db distribué (un curseur persistant par compte) et le transmet à imsg watch.subscribe sous la forme since_rowid, afin qu’imsg réexécute les lignes reçues pendant l’arrêt du Gateway, puis suive les messages en direct. La réexécution est limitée aux 500 lignes les plus récentes et aux messages datant d’au plus ~2 heures ; la déduplication supprime tout élément déjà traité.
• Limite d’âge des 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 messages en attente libérés par Push et est supprimée. Les lignes réexécuté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 réexécution de since_rowid utilise la même connexion RPC imsg. La différence réside dans la fenêtre : lorsque le Gateway peut lire chat.db (en local), il ancre la limite de rowid au démarrage, plafonne la plage de réexécution et distribue les messages manqués datant de quelques heures au maximum. Avec un cliPath distant via SSH, il ne peut pas lire la base de données ; la réexécution n’est donc pas plafonnée et chaque ligne utilise la limite d’âge des messages en direct. Les messages récemment manqués sont tout de même récupérés et les anciens messages en attente sont toujours supprimés, 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

La suppression des messages en attente est consignée au niveau de journalisation par défaut et n’est jamais effectuée silencieusement (l’indicateur recovery précise la fenêtre appliquée) :

imessage: anciens messages entrants en attente supprimés 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 réexécution de récupération. Les blocs de rattrapage désactivés (enabled: false ou absence de enabled: true) sont retirés ; openclaw doctor --fix les supprime.

Résolution des problèmes

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

Voir aussi

• Vue d’ensemble des canaux — tous les canaux pris en charge
• Suppression de BlueBubbles et chemin iMessage avec imsg — annonce et résumé de la migration
• Migration depuis BlueBubbles — tableau de transposition de la configuration et basculement étape par étape
• 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