iMessage

​

Configuration rapide

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

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

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

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

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

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

​

Configuration

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

​

Lorsque vous ne pouvez pas désactiver SIP

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

{
  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

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

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

{
  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 en fragments et cibles de livraison

imsg chats --limit 20

​

Actions d’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,
    },
  },
}

​

Écritures de configuration

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

​

Fusion des DM à envoi fractionné (commande + URL dans une même composition)

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.

{
  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

​

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

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

​

Signal visible par l’opérateur

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

​

Migration

​

Dépannage

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"

​

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