iMessage

Statut : intégration CLI externe native. Le Gateway lance imsg rpc et communique en JSON-RPC sur stdio (sans daemon/port séparé). Les actions avancées nécessitent imsg launch et une sonde d’API privée réussie.

Configuration rapide

brew install steipete/tap/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>

#!/usr/bin/env bashexec ssh -T gateway-host imsg "$@"

{channels: {imessage: {  enabled: true,  cliPath: "~/.openclaw/scripts/imsg-ssh",  remoteHost: "user@gateway-host", // used for SCP attachment fetches  includeAttachments: true,  // Optional: override allowed attachment roots.  // Defaults include /Users/*/Library/Messages/Attachments  attachmentRoots: ["/Users/*/Library/Messages/Attachments"],  remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],},},}

Exigences 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 exécutant OpenClaw/imsg (accès à la base de données Messages).
• L’autorisation Automation est requise pour envoyer des messages via Messages.app.
• Pour les actions avancées (réagir / modifier / annuler l’envoi / réponse en fil / effets / sondages / opérations de groupe), System Integrity Protection doit être désactivé — voir Activation de l’API privée imsg ci-dessous. L’envoi/réception de texte et de médias de base fonctionne sans cela.

Not authorized to send Apple events to Messages. (-1743)

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

Activation de l’API privée imsg

imsg est livré avec deux modes opérationnels :

• Mode de base (par défaut, aucun changement SIP nécessaire) : texte et médias sortants via send, surveillance/historique entrants, liste des conversations. C’est ce que vous obtenez directement après une nouvelle installation brew install steipete/tap/imsg et les autorisations macOS standard ci-dessus.
• Mode API privée : imsg injecte une dylib d’assistance dans Messages.app pour appeler des fonctions internes IMCore. C’est ce qui débloque react, edit, unsend, reply (en 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.

Pour atteindre la surface d’actions avancées documentée sur cette page de canal, vous avez besoin du mode API privée. Le README de imsg est explicite sur l’exigence :

Les fonctionnalités avancées telles que read, typing, launch, l’envoi riche adossé au pont, la mutation de messages et la gestion des conversations sont optionnelles. Elles exigent que SIP soit désactivé et qu’une dylib d’assistance soit injectée dans Messages.app. imsg launch refuse l’injection lorsque SIP est activé.

La technique d’injection de l’assistant utilise la propre dylib de imsg pour atteindre les API privées de Messages. Il n’y a aucun serveur tiers ni runtime BlueBubbles dans le chemin OpenClaw iMessage.

Configuration

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

   brew install steipete/tap/imsgimsg --versionimsg status --json

   La sortie de imsg status --json indique bridge_version, rpc_methods et les selectors par méthode, afin que vous puissiez voir ce que la version actuelle prend en charge avant de démarrer.

2. Désactivez System Integrity Protection et (sur macOS moderne) Library Validation. Injecter une dylib d’assistance non Apple dans Messages.app signé par Apple nécessite que SIP soit désactivé et que la validation de bibliothèque soit assouplie. L’étape SIP en mode Récupération dépend de la version de macOS :

   • macOS 10.13-10.15 (Sierra-Catalina) : désactivez Library Validation via Terminal, redémarrez en mode Récupération, exécutez csrutil disable, redémarrez.
   • macOS 11+ (Big Sur et versions ultérieures), Intel : mode Récupération (ou Récupération Internet), csrutil disable, redémarrez.
   • macOS 11+, Apple Silicon : séquence de démarrage au bouton d’alimentation pour entrer en Récupération ; sur les versions récentes de macOS, maintenez la touche Maj gauche lorsque vous cliquez sur Continuer, puis csrutil disable. Les configurations de machine virtuelle suivent un flux distinct ; prenez donc d’abord un instantané de la VM.

   Sur macOS 11 et versions ultérieures, csrutil disable seul ne suffit généralement pas. Apple applique encore la validation de bibliothèque à 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 avec SIP désactivé. Après avoir désactivé SIP, désactivez aussi la validation de bibliothèque 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 : SIP désactivé plus la commande DisableLibraryValidation ci-dessus suffit à injecter l’assistant de 26.0 à 26.5.x. Aucun boot-arg n’est requis. Le plist est le facteur décisif et l’étape manquante la plus fréquente lorsque l’injection échoue sur Tahoe :

   • Avec le plist : imsg launch injecte et imsg status indique advanced_features: true.
   • Sans le 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 au chargement ; le pont ne devient donc jamais prêt et le lancement expire. Ce délai d’expiration est le symptôme le plus courant sur Tahoe, et le correctif est le plist ci-dessus, pas une mesure plus radicale.

   Cela a été confirmé par un avant/après contrôlé sur macOS 26.5.1 (Apple Silicon) : avec le plist, la dylib est mappée dans Messages.app et le pont démarre ; supprimez le plist et redémarrez, et imsg launch produit l’échec par délai d’expiration ci-dessus, sans que la dylib ne soit mappée.

   Si l’injection par imsg launch ou des selectors spécifiques 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 SIP elle-même a échoué. Si ces réglages sont corrects et que la passerelle ne parvient toujours pas à injecter, collectez imsg status --json ainsi que la sortie de imsg launch et signalez-le au projet imsg au lieu d’affaiblir d’autres contrôles de sécurité à l’échelle du système.

   Suivez le flux en mode de récupération d’Apple pour votre Mac afin de désactiver SIP avant d’exécuter imsg launch.

3. Injecter l’assistant. Avec SIP désactivé et Messages.app connecté :

   imsg launch

   imsg launch refuse d’injecter lorsque SIP est encore activé ; cela sert donc aussi à confirmer que l’étape 2 a bien pris effet.

4. Vérifier la passerelle depuis OpenClaw :

   openclaw channels status --probe

   L’entrée iMessage doit signaler works, et imsg status --json | jq '{rpc_methods, selectors}' doit afficher les capacités exposées par votre build 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 annonce uniquement les actions prises en charge par la sonde mise en cache, tandis qu’un cache vide reste optimiste et effectue une sonde lors du premier envoi.

Si openclaw channels status --probe signale que le canal est works mais que des actions spécifiques lèvent "iMessage <action> requires the imsg private API bridge" au moment de l’envoi, exécutez de nouveau imsg launch — l’assistant peut se détacher (redémarrage de Messages.app, mise à jour de l’OS, etc.) et l’état mis en cache available: true continuera d’annoncer les actions jusqu’à ce que la prochaine sonde l’actualise.

Lorsque vous ne pouvez pas désactiver SIP

Si SIP désactivé 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 annonce toujours l’envoi de texte/médias et la surveillance entrante ; il masque simplement react, edit, unsend, reply, sendWithEffect et les opérations de groupe de la surface d’action (selon la barrière de capacité par méthode).
• Vous pouvez exécuter un Mac non Apple Silicon séparé (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. Voir Utilisateur macOS dédié au bot (identité iMessage séparée) ci-dessous.

Contrôle d’accès et routage

{  channels: {    imessage: {      groupPolicy: "allowlist",      groupAllowFrom: ["+15555550123"],      groups: {        "*": { systemPrompt: "Use British spelling." },        "8421": {          requireMention: true,          systemPrompt: "This is the on-call rotation chat. Keep replies under 3 sentences.",        },        "9907": {          // explicit suppression: the wildcard "Use British spelling." does not apply here          systemPrompt: "",        },      },    },  },}

Liaisons de conversation ACP

Les anciennes discussions iMessage peuvent également être liées à des sessions ACP.

Flux opérateur rapide :

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

Les liaisons persistantes configurées sont prises en charge via des entrées de premier niveau bindings[] avec type: "acp" et match.channel: "imessage".

match.peer.id peut utiliser :

• un identifiant de DM normalisé tel que +15555550123 ou user@example.com
• chat_id:<id> (recommandé pour des 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" },    },  ],}

Voir Agents ACP pour 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 en fragments et cibles de livraison

imsg chats --limit 20

Actions d’API privée

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

{  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).

Désactiver :

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

Fusion des DM à envoi fractionné (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 fractionne 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 en pièces jointes.

Les deux lignes arrivent dans OpenClaw à environ 0,8 à 2,0 s d’intervalle sur la plupart des configurations. Sans fusion, l’agent reçoit seulement la commande au tour 1, répond (souvent « envoyez-moi l’URL »), puis ne voit l’URL qu’au tour 2 — moment où le contexte de commande est déjà perdu. Il s’agit du pipeline d’envoi d’Apple, et non d’un comportement introduit par OpenClaw ou imsg.

channels.imessage.coalesceSameSenderDms inscrit un DM à la mise en mémoire tampon des lignes consécutives d’un 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 ce véritable envoi fractionné et conserve toutes les autres lignes en mémoire tampon comme des tours séparés. Sur les anciennes versions de imsg qui n’émettent aucune métadonnée de bulle, OpenClaw ne peut pas distinguer un envoi fractionné d’envois séparés ; il se rabat donc sur la fusion du lot. Cela préserve le comportement antérieur aux métadonnées au lieu de faire régresser les envois fractionnés Dump <url> en deux tours. Les discussions de groupe continuent d’être distribuées message par message afin de préserver la structure des tours multi-utilisateurs.

{  channels: {    imessage: {      coalesceSameSenderDms: true, // opt in (default: false)    },  },}

{  messages: {    inbound: {      byChannel: {        // 7000 ms covers observed Messages.app URL-preview delays.        imessage: 7000,      },    },  },}

Scénarios et ce que voit l’agent

La colonne « Indicateur activé » montre 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 marquées « Deux tours » / « N tours » se rabattent plutôt sur une fusion héritée (un tour) : OpenClaw ne peut pas distinguer structurellement un envoi fractionné d’envois séparés, il préserve donc la fusion antérieure aux métadonnées. La séparation précise s’active une fois que la version émet les métadonnées de bulle.

Récupération entrante après un redémarrage du pont ou du Gateway

iMessage récupère les messages manqués pendant que le Gateway était arrêté et, en même temps, supprime la vieille « bombe d’arriéré » qu’Apple peut vider après une récupération Push. Le comportement par défaut est toujours activé et repose sur la déduplication entrante.

• Déduplication de rejeu. Chaque message entrant envoyé est enregistré par son GUID Apple dans l’état persistant du Plugin (imessage.inbound-dedupe), revendiqué à l’ingestion et validé après traitement (libéré en cas d’échec transitoire afin de pouvoir réessayer). Tout ce qui a déjà été traité est ignoré au lieu d’être envoyé deux fois. C’est ce qui permet à la récupération de rejouer agressivement sans suivi par message.
• Récupération après indisponibilité. Au démarrage, le moniteur mémorise le dernier rowid chat.db envoyé (un curseur persistant par compte) et le transmet à imsg watch.subscribe comme since_rowid, afin que imsg rejoue les lignes arrivées pendant que le Gateway était arrêté, puis suive le flux en direct. Le rejeu est limité aux lignes les plus récentes et aux messages vieux d’environ 2 heures au maximum, et la déduplication ignore tout ce qui a déjà été traité.
• Barrière d’âge pour l’arriéré obsolète. Les lignes au-dessus de la limite de démarrage sont réellement en direct ; une ligne dont la date d’envoi est plus ancienne d’environ 15 minutes que son arrivée correspond à l’arriéré vidé par Push et est supprimée. Les lignes rejouées (à la limite ou en dessous) utilisent plutôt la fenêtre de récupération plus large, afin qu’un message récemment manqué soit livré tandis que l’historique ancien ne l’est pas.

La récupération fonctionne avec les configurations cliPath locales comme distantes, car le rejeu since_rowid s’exécute sur la même connexion RPC imsg. La différence est la fenêtre : lorsque le Gateway peut lire chat.db (local), il ancre la limite rowid de démarrage, plafonne l’étendue du rejeu et livre les messages manqués vieux de quelques heures au maximum. Avec un cliPath SSH distant, il ne peut pas lire la base de données ; le rejeu n’est donc pas plafonné et chaque ligne utilise la barrière d’âge en direct — il récupère toujours les messages récemment manqués et supprime toujours les anciens arriérés, mais avec la fenêtre en direct plus étroite. Exécutez le Gateway sur le Mac Messages pour bénéficier de la fenêtre de récupération plus large.

Signal visible par l’opérateur

L’arriéré supprimé est journalisé au niveau par défaut, jamais ignoré silencieusement (l’indicateur recovery montre quelle fenêtre s’est appliquée) :

imessage: suppressed stale inbound backlog account=<id> sent=<iso> recovery=<bool> (&lt;N&gt; suppressed since start)

Migration

channels.imessage.catchup.* est obsolète — la récupération après indisponibilité est désormais automatique et ne nécessite aucune configuration pour les nouvelles installations. Les configurations existantes avec catchup.enabled: true restent honorées comme profil de compatibilité pour la fenêtre de rejeu de récupération. Les blocs catchup 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"

Pointeurs de référence de configuration

• Référence de configuration - iMessage
• Configuration du Gateway
• Association

Associé

• Vue d’ensemble des canaux — tous les canaux pris en charge
• Suppression de BlueBubbles et chemin iMessage imsg — annonce et résumé de migration
• Venir de BlueBubbles — tableau de traduction de configuration et bascule étape par étape
• Association — authentification MP et flux d’association
• Groupes — comportement des discussions de groupe et contrôle par mention
• Routage des canaux — routage de session pour les messages
• Sécurité — modèle d’accès et durcissement