iMessage

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

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

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

​

Activation de l’API privée imsg

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

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

​

Quand 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 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: { "*": { "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 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.

• un identifiant de MP normalisé comme +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, segmentation 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,
      },
    },
  },
}

{
  channels: {
    imessage: {
      sendReadReceipts: false,
    },
  },
}

​

Écritures de configuration

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

​

Fusion des MP envoyés séparément (commande + URL dans une seule composition)

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.

{
  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

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

​

Sémantique du curseur et des nouvelles tentatives

{
  "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 <N> failures; advancing cursor past it
imessage catchup: fetched <X> rows across chats, capped to perRunLimit=<Y>

​

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.

​

Dépannage

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

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

openclaw channels status --probe --channel imessage

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