iMessage (hérité : imsg)

Pour les nouveaux déploiements iMessage, utilisez BlueBubbles.L’intégration imsg est héritée et pourra être supprimée dans une future version.

Statut : intégration CLI externe héritée. Gateway lance imsg rpc et communique via JSON-RPC sur stdio (pas de démon/port séparé).

BlueBubbles (recommandé)

Voie iMessage privilégiée pour les nouvelles installations.

Appairage

Les DM iMessage utilisent par défaut le mode d’appairage.

Référence de configuration

Référence complète des champs iMessage.

Configuration rapide

Mac local (voie rapide)
Mac distant via SSH

Installer et vérifier imsg

brew install steipete/tap/imsg
imsg rpc --help

Configurer OpenClaw

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

Démarrer gateway

openclaw gateway

Approuver le premier appairage de DM (dmPolicy par défaut)

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

Les demandes d’appairage expirent après 1 heure.

OpenClaw exige seulement un cliPath compatible stdio, vous pouvez donc faire pointer cliPath vers un script wrapper qui se connecte en SSH à un Mac distant et exécute imsg.

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

Configuration recommandée lorsque les pièces jointes sont activées :

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "user@gateway-host", // utilisé pour les récupérations de pièces jointes via SCP
      includeAttachments: true,
      // Facultatif : remplacer les racines de pièces jointes autorisées.
      // Par défaut, inclut /Users/*/Library/Messages/Attachments
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
    },
  },
}

Si remoteHost n’est pas défini, OpenClaw tente de le détecter automatiquement en analysant le script wrapper SSH. remoteHost doit être host ou user@host (sans espaces ni options SSH). OpenClaw utilise une vérification stricte de la clé d’hôte pour SCP, la clé d’hôte du relais doit donc déjà exister dans ~/.ssh/known_hosts. Les chemins de pièces jointes sont validés par rapport aux racines autorisées (attachmentRoots / remoteAttachmentRoots).

Exigences et autorisations (macOS)

Messages doit être connecté sur le Mac qui exécute imsg.
Un accès complet au disque est requis pour le contexte de processus qui exécute OpenClaw/imsg (accès à la base de données Messages).
L’autorisation Automation est requise pour envoyer des messages via Messages.app.

Les autorisations sont accordées par contexte de processus. Si gateway s’exécute sans interface (LaunchAgent/SSH), exécutez une commande interactive unique dans ce même contexte pour déclencher les invites :

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

Contrôle d’accès et routage

Politique DM
Politique de groupe + mentions
Sessions et réponses déterministes

channels.imessage.dmPolicy contrôle les messages directs :

pairing (par défaut)
allowlist
open (nécessite que allowFrom inclue "*")
disabled

Champ de liste d’autorisation : channels.imessage.allowFrom.Les entrées de liste d’autorisation peuvent être des handles ou des cibles de chat (chat_id:*, chat_guid:*, chat_identifier:*).

channels.imessage.groupPolicy contrôle la gestion des groupes :

allowlist (par défaut lorsqu’il est configuré)
open
disabled

Liste d’autorisation des expéditeurs de groupe : channels.imessage.groupAllowFrom.Repli du runtime : si groupAllowFrom n’est pas défini, les vérifications d’expéditeur de groupe iMessage retombent sur allowFrom lorsque disponible. Note du runtime : si channels.imessage est totalement absent, le runtime revient à groupPolicy="allowlist" et journalise un avertissement (même si channels.defaults.groupPolicy est défini).Contrôle par mention pour les groupes :

iMessage n’a pas de métadonnées de mention natives
la détection des mentions utilise des motifs regex (agents.list[].groupChat.mentionPatterns, repli messages.groupChat.mentionPatterns)
sans motifs configurés, le contrôle par mention ne peut pas être appliqué

Les commandes de contrôle provenant d’expéditeurs autorisés peuvent contourner le contrôle par mention dans les groupes.

Les DM utilisent le routage direct ; les groupes utilisent le routage de groupe.
Avec la valeur par défaut session.dmScope=main, les DM iMessage se regroupent dans la session principale de l’agent.
Les sessions de groupe sont isolées (agent:<agentId>:imessage:group:<chat_id>).
Les réponses reviennent vers iMessage en utilisant les métadonnées du canal/de la cible d’origine.

Comportement des fils de discussion de type groupe :Certains fils iMessage à plusieurs participants peuvent arriver avec is_group=false. Si ce chat_id est explicitement configuré sous channels.imessage.groups, OpenClaw le traite comme du trafic de groupe (contrôle de groupe + isolation de session de groupe).

Liaisons de conversation ACP

Les anciens chats iMessage peuvent aussi être liés à des sessions ACP. Flux opérateur rapide :

Exécutez /acp spawn codex --bind here dans le DM ou le chat de groupe autorisé.
Les messages suivants dans cette même conversation iMessage sont acheminés vers la session ACP lancé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 bindings[] de niveau supérieur avec type: "acp" et match.channel: "imessage". match.peer.id peut utiliser :

un handle 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

Utilisateur macOS de bot dédié (identité iMessage séparée)

Utilisez un Apple ID et un utilisateur macOS dédiés afin d’isoler le trafic du bot de votre profil Messages personnel.Flux typique :

Créez/connectez un utilisateur macOS dédié.
Connectez-vous à Messages avec l’Apple ID du bot dans cet utilisateur.
Installez imsg dans cet utilisateur.
Créez un wrapper SSH afin qu’OpenClaw puisse exécuter imsg dans le contexte de cet utilisateur.
Faites pointer channels.imessage.accounts.<id>.cliPath et .dbPath vers ce profil utilisateur.

La première exécution peut nécessiter des approbations GUI (Automation + accès complet au disque) dans la session de cet utilisateur bot.

Mac distant sur Tailscale (exemple)

Topologie courante :

gateway s’exécute sur Linux/VM
iMessage + imsg s’exécute sur un Mac dans votre tailnet
le wrapper cliPath utilise SSH pour exécuter imsg
remoteHost active les récupérations de pièces jointes via SCP

Exemple :

{
  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 "$@"

Utilisez des clés SSH afin que SSH et SCP soient tous deux non interactifs. Assurez-vous d’abord que la clé d’hôte est approuvée (par exemple ssh bot@mac-mini.tailnet-1234.ts.net) afin que known_hosts soit renseigné.

Modèle multi-comptes

iMessage prend en charge une configuration par compte sous channels.imessage.accounts.Chaque compte peut remplacer des champs tels que cliPath, dbPath, allowFrom, groupPolicy, mediaMaxMb, les paramètres d’historique et les listes d’autorisation des racines de pièces jointes.

Médias, segmentation et cibles de livraison

Pièces jointes et médias

l’ingestion des pièces jointes entrantes est facultative : channels.imessage.includeAttachments
les chemins de pièces jointes distants peuvent être récupérés via SCP lorsque remoteHost est défini
les chemins de pièces jointes doivent correspondre aux racines autorisées :
- channels.imessage.attachmentRoots (local)
- channels.imessage.remoteAttachmentRoots (mode SCP distant)
- motif de racine par défaut : /Users/*/Library/Messages/Attachments
SCP utilise une vérification stricte de la clé d’hôte (StrictHostKeyChecking=yes)
la taille des médias sortants utilise channels.imessage.mediaMaxMb (16 MB par défaut)

Segmentation sortante

limite de segmentation du texte : channels.imessage.textChunkLimit (4000 par défaut)
mode de segmentation : channels.imessage.chunkMode
- length (par défaut)
- newline (segmentation en privilégiant les paragraphes)

Formats d’adressage

Cibles explicites recommandées :

chat_id:123 (recommandé pour un routage stable)
chat_guid:...
chat_identifier:...

Les cibles handle sont également prises en charge :

imessage:+1555...
sms:+1555...
user@example.com

imsg chats --limit 20

É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,
    },
  },
}

Dépannage

imsg introuvable ou RPC non pris en charge

Validez le binaire et la prise en charge RPC :

imsg rpc --help
openclaw channels status --probe

Si la sonde indique que RPC n’est pas pris en charge, mettez imsg à jour.

Les DM sont ignorés

Vérifiez :

channels.imessage.dmPolicy
channels.imessage.allowFrom
les approbations d’appairage (openclaw pairing list imessage)

Les messages de groupe sont ignorés

Vérifiez :

channels.imessage.groupPolicy
channels.imessage.groupAllowFrom
le comportement de liste d’autorisation de channels.imessage.groups
la configuration des motifs de mention (agents.list[].groupChat.mentionPatterns)

Les pièces jointes distantes échouent

Vérifiez :

channels.imessage.remoteHost
channels.imessage.remoteAttachmentRoots
l’authentification par clé SSH/SCP depuis l’hôte gateway
la présence de la clé d’hôte dans ~/.ssh/known_hosts sur l’hôte gateway
la lisibilité du chemin distant sur le Mac exécutant Messages

Les invites d’autorisation macOS ont été manquées

Réexécutez dans un terminal GUI interactif dans le même contexte utilisateur/session et approuvez les invites :

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

Confirmez qu’Accès complet au disque + Automation sont accordés pour le contexte de processus qui exécute OpenClaw/imsg.

Pointeurs de référence de configuration

Liens associés

Vue d’ensemble des canaux — tous les canaux pris en charge
Appairage — authentification DM et flux d’appairage
Groupes — comportement des chats 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

Overview

Messaging platforms

Configuration

iMessage

iMessage (hérité : imsg)

BlueBubbles (recommandé)

Appairage

Référence de configuration

Configuration rapide

Exigences et autorisations (macOS)

Contrôle d’accès et routage

Liaisons de conversation ACP

Modèles de déploiement

Médias, segmentation et cibles de livraison

Écritures de configuration

Dépannage

Pointeurs de référence de configuration

Liens associés

Overview

Messaging platforms

Configuration

​iMessage (hérité : imsg)

BlueBubbles (recommandé)

Appairage

Référence de configuration

​Configuration rapide

​Exigences et autorisations (macOS)

​Contrôle d’accès et routage

​Liaisons de conversation ACP

​Modèles de déploiement

​Médias, segmentation et cibles de livraison

​Écritures de configuration

​Dépannage

​Pointeurs de référence de configuration

​Liens associés

iMessage (hérité : imsg)

Configuration rapide

Exigences et autorisations (macOS)

Contrôle d’accès et routage

Liaisons de conversation ACP

Modèles de déploiement

Médias, segmentation et cibles de livraison

Écritures de configuration

Dépannage

Pointeurs de référence de configuration

Liens associés