iMessage

État : intégration CLI externe native. Le Gateway lance imsg rpc et communique en JSON-RPC sur stdio (pas de démon/port distinct). 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 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 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 en fil / effets / opérations de groupe), la Protection de l’intégrité du système doit être désactivée — 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.

Activation de l’API privée imsg

imsg est fourni avec deux modes de fonctionnement :

• Mode de base (par défaut, aucune modification de SIP requise) : texte et médias sortants via send, surveillance/historique entrants, liste des conversations. C’est ce que vous obtenez immédiatement après un nouveau brew install steipete/tap/imsg plus les autorisations macOS standard ci-dessus.
• Mode API privée : imsg injecte une dylib d’assistance dans Messages.app pour appeler des fonctions IMCore internes. C’est ce qui débloque react, edit, unsend, reply (en fil), sendWithEffect, renameGroup, setGroupIcon, addParticipant, removeParticipant, leaveGroup, ainsi que les indicateurs de saisie et les confirmations de lecture.

Pour accéder à 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 cette 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 accéder aux API privées de Messages. Il n’y a pas de serveur tiers ni d’environnement d’exécution BlueBubbles 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/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 commencer.

2. Désactivez la Protection de l’intégrité du système. Cela dépend de la version de macOS, car l’exigence Apple sous-jacente varie selon l’OS et le matériel :

   • 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 par Internet), csrutil disable, redémarrez.
   • macOS 11+, Apple Silicon : séquence de démarrage avec le bouton d’alimentation pour entrer en mode 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 d’abord un instantané de la VM.
   • macOS 26 / Tahoe : les politiques de validation de bibliothèques et les contrôles d’autorisations privées imagent se sont encore renforcés ; imsg peut nécessiter une version mise à jour pour suivre. Si l’injection de imsg launch ou certains selectors commencent à renvoyer false après une mise à niveau majeure de macOS, consultez les notes de version de imsg avant de supposer que l’étape SIP a réussi.

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

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

   imsg launch

   imsg launch refuse l’injection lorsque SIP est encore activé ; cela sert donc aussi de confirmation que l’étape 2 a été prise en compte.

4. Vérifiez le pont depuis OpenClaw :

   openclaw channels status --probe

   L’entrée iMessage doit indiquer works, et imsg status --json | jq '.selectors' doit afficher retractMessagePart: true ainsi que les sélecteurs de modification / saisie / lecture exposés par votre version de macOS. Le filtrage par méthode du Plugin OpenClaw dans actions.ts n’annonce que les actions dont le sélecteur sous-jacent vaut true ; la surface d’actions que vous voyez dans la liste d’outils de l’agent reflète donc ce que le pont peut réellement faire sur cet hôte.

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

Quand vous ne pouvez pas désactiver SIP

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 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 dans la surface d’actions (selon le filtrage de capacité par méthode).
• Vous pouvez exécuter un Mac non Apple Silicon distinct (ou un Mac bot dédié) avec SIP désactivé pour la charge de travail iMessage, tout en gardant SIP activé sur vos appareils principaux. Voir Utilisateur macOS bot dédié (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 conversations iMessage peuvent également être liées à des sessions ACP.

Flux opérateur rapide :

• Exécutez /acp spawn codex --bind here dans le MP ou la conversation de groupe autorisée.
• Les futurs messages dans cette même conversation iMessage sont routés vers la session ACP lancé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 sont prises en charge via les entrées bindings[] de niveau supérieur avec type: "acp" et match.channel: "imessage".

match.peer.id peut utiliser :

• un identifiant de MP normalisé comme +15555550123 ou [email protected]
• 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" },    },  ],}

Consultez Agents ACP pour le comportement partagé des liaisons ACP.

Modèles de déploiement

{  channels: {    imessage: {      enabled: true,      cliPath: "~/.openclaw/scripts/imsg-ssh",      remoteHost: "[email protected]",      includeAttachments: true,      dbPath: "/Users/bot/Library/Messages/chat.db",    },  },}

#!/usr/bin/env bashexec ssh -T [email protected] imsg "$@"

Médias, segmentation 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 message peut utiliser des actions natives d’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,      },    },  },}

{  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 MP envoyés séparément (commande + URL dans une seule composition)

Lorsqu’un utilisateur saisit ensemble une commande et une URL — par exemple Dump https://example.com/article — l’app 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 des images d’aperçu OG comme pièces jointes.

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

channels.imessage.coalesceSameSenderDms permet à un DM de fusionner des lignes consécutives du même expéditeur en un seul tour d’agent. Les discussions de groupe continuent à ê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: {        // 2500 ms works for most setups; raise to 4000 ms if your Mac is        // slow or under memory pressure (observed gap can stretch past 2 s        // then).        imessage: 2500,      },    },  },}

Scénarios et ce que l’agent voit

Rattraper après une interruption du Gateway

Lorsque le Gateway est hors ligne (plantage, redémarrage, mise en veille du Mac, machine éteinte), imsg watch reprend depuis l’état actuel de chat.db une fois que le Gateway redémarre — tout ce qui est arrivé pendant l’intervalle n’est, par défaut, jamais vu. Le rattrapage rejoue ces messages au démarrage suivant afin que l’agent ne manque pas silencieusement le trafic entrant.

Le rattrapage est désactivé par défaut. Activez-le par canal :

channels: {  imessage: {    catchup: {      enabled: true,             // master switch (default: false)      maxAgeMinutes: 120,        // skip rows older than now - 2h (default: 120, clamp 1..720)      perRunLimit: 50,           // max rows replayed per startup (default: 50, clamp 1..500)      firstRunLookbackMinutes: 30, // first run with no cursor: look back 30 min (default: 30)      maxFailureRetries: 10,     // give up on a wedged guid after 10 dispatch failures (default: 10)    },  },}

Fonctionnement

Un passage par démarrage de monitorIMessageProvider, séquencé comme suit : imsg launch prêt → watch.subscribe → performIMessageCatchup → boucle de distribution en direct. Le rattrapage lui-même utilise chats.list + messages.history par discussion avec le même client JSON-RPC que celui utilisé par imsg watch. Tout ce qui arrive pendant le passage de rattrapage passe normalement par la distribution en direct ; le cache de déduplication entrante existant absorbe tout chevauchement avec les lignes rejouées.

Chaque ligne rejouée est injectée dans le chemin de distribution en direct (evaluateIMessageInbound + dispatchInboundMessage), de sorte que les listes d’autorisation, la politique de groupe, l’anti-rebond, le cache d’écho et les accusés de lecture se comportent de façon identique pour les messages rejoués et les messages en direct.

Sémantique du curseur et des nouvelles tentatives

Le rattrapage conserve un curseur par compte à <openclawStateDir>/imessage/catchup/<account>__<hash>.json (le répertoire d’état OpenClaw vaut par défaut ~/.openclaw, surchargeable avec OPENCLAW_STATE_DIR) :

{  "lastSeenMs": 1717900800000,  "lastSeenRowid": 482910,  "updatedAt": 1717900801234,  "failureRetries": { "<guid>": 1 }}

• Le curseur avance à chaque distribution réussie et reste en place lorsque la distribution d’une ligne lève une exception — le démarrage suivant réessaie la même ligne depuis le curseur conservé.
• Après maxFailureRetries exceptions consécutives pour le même guid, le rattrapage journalise un warn et force l’avancement du curseur au-delà du message bloqué afin que les démarrages suivants puissent progresser.
• Les GUID déjà abandonnés sont ignorés dès qu’ils sont vus (aucune tentative de distribution) lors des exécutions ultérieures et comptés sous skippedGivenUp dans le résumé d’exécution.

Signaux visibles par l’opérateur

imessage catchup: replayed=N skippedFromMe=… skippedGivenUp=… failed=… givenUp=… fetchedCount=…imessage catchup: giving up on guid=<guid> after &lt;N&gt; failures; advancing cursor past itimessage catchup: fetched &lt;X&gt; rows across chats, capped to perRunLimit=&lt;Y&gt;

Une ligne WARN ... capped to perRunLimit signifie qu’un seul démarrage n’a pas vidé tout l’arriéré. Augmentez perRunLimit (max 500) si vos interruptions dépassent régulièrement le passage par défaut de 50 lignes.

Quand le laisser désactivé

• Le Gateway fonctionne en continu avec redémarrage automatique par watchdog et les interruptions durent toujours moins de quelques secondes — la valeur par défaut désactivée convient.
• Le volume de DM est faible et les messages manqués ne changeraient pas le comportement de l’agent — la fenêtre initiale firstRunLookbackMinutes peut distribuer un ancien contexte surprenant lors de la première activation.

Lorsque vous activez le rattrapage, le premier démarrage sans curseur ne remonte que sur firstRunLookbackMinutes (30 min par défaut), pas sur toute la fenêtre maxAgeMinutes — cela évite de rejouer un long historique de messages antérieurs à l’activation.

Dépannage

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

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

openclaw channels status --probe --channel imessage

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

Repères de référence de configuration

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

Connexe

• Vue d’ensemble des canaux — tous les canaux pris en charge
• Suppression de BlueBubbles et chemin iMessage via imsg — annonce et résumé de migration
• Migration depuis BlueBubbles — table de traduction de configuration et bascule étape par étape
• Appairage — authentification DM et flux d’appairage
• Groupes — comportement des discussions de groupe et filtrage par mention
• Routage des canaux — routage de session pour les messages
• Sécurité — modèle d’accès et renforcement