iMessage

​

Configuration rapide

brew install steipete/tap/imsg
brew update && brew upgrade imsg
imsg rpc --help
imsg launch
openclaw channels status --probe

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

openclaw gateway

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

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

#!/usr/bin/env bash
exec 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.

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

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

• 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.

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.

​

Configuration

1. Installez (ou mettez à niveau) imsg sur le Mac qui exécute Messages.app :
   brew install steipete/tap/imsg
   brew update && brew upgrade imsg
   imsg --version
   imsg 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.

​

Lorsque SIP reste activé

• 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: { "*": { "requireMention": true } },
    },
  },
}

{
  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

• 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.

• 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>

{
  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" },
    },
  ],
}

​

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 bash
exec 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

{
  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

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

​

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

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.

{
  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

​

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

• 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.

​

Signal visible par l’opérateur

imessage: anciens messages entrants en attente supprimés account=<id> sent=<iso> recovery=<bool> (<N> supprimés depuis le démarrage)

​

Migration

​

Résolution des problèmes

imsg rpc --help
imsg status --json
openclaw channels status --probe

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

launchctl kickstart -k system/com.apple.apsd
launchctl kickstart -k gui/$(id -u)/com.apple.CommCenter
launchctl kickstart -k gui/$(id -u)/com.apple.identityservicesd
launchctl kickstart -k gui/$(id -u)/com.apple.imagent
imsg launch
openclaw gateway restart

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

openclaw channels status --probe --channel imessage

imsg chats --limit 1
imsg 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