iMessage (legacy : imsg)

Avertissement : Pour les nouveaux deploiements iMessage, utilisez BlueBubbles.

L’integration imsg est legacy et pourrait etre supprimee dans une version future.

Statut : integration CLI externe legacy. La gateway lance imsg rpc et communique via JSON-RPC sur stdio (pas de daemon/port separe).

• BlueBubbles (recommande) — Chemin iMessage prefere pour les nouvelles installations.
• Appairage — Les DMs iMessage sont en mode appairage par defaut.
• Reference de configuration — Reference complete des champs iMessage.

Configuration rapide

Mac local (chemin rapide)

  ### Etape 1 : Installer et verifier imsg

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

  ### Etape 2 : Configurer OpenClaw

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

  ### Etape 3 : Demarrer la gateway

openclaw gateway

  ### Etape 4 : Approuver le premier appairage DM (dmPolicy par defaut)

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

    Les demandes d'appairage expirent apres 1 heure.

Mac distant via SSH

OpenClaw necessite uniquement un `cliPath` compatible stdio, vous pouvez donc pointer `cliPath` vers un script wrapper qui se connecte en SSH a un Mac distant et execute `imsg`.

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

Configuration recommandee quand les pieces jointes sont activees :

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "user@gateway-host", // utilise pour les recuperations SCP de pieces jointes
      includeAttachments: true,
      // Optionnel : surcharger les racines de pieces jointes autorisees.
      // Par defaut inclut /Users/*/Library/Messages/Attachments
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
    },
  },
}

Si `remoteHost` n'est pas defini, OpenClaw tente de le detecter automatiquement en analysant le script wrapper SSH.
`remoteHost` doit etre `host` ou `user@host` (pas d'espaces ni d'options SSH).
OpenClaw utilise la verification stricte des cles d'hote pour SCP, donc la cle d'hote du relais doit deja exister dans `~/.ssh/known_hosts`.
Les chemins de pieces jointes sont valides par rapport aux racines autorisees (`attachmentRoots` / `remoteAttachmentRoots`).

Prerequis et permissions (macOS)

• Messages doit etre connecte sur le Mac executant imsg.
• L’acces complet au disque est requis pour le contexte de processus executant OpenClaw/imsg (acces a la DB Messages).
• La permission d’automatisation est requise pour envoyer des messages via Messages.app.

Astuce : Les permissions sont accordees par contexte de processus. Si la gateway s’execute en mode headless (LaunchAgent/SSH), executez une commande interactive ponctuelle dans le meme contexte pour declencher les invites :

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

Controle d’acces et routage

Politique DM

`channels.imessage.dmPolicy` controle les messages directs :

- `pairing` (par defaut)
- `allowlist`
- `open` (necessite que `allowFrom` inclue `"*"`)
- `disabled`

Champ de liste d'autorisation : `channels.imessage.allowFrom`.

Les entrees de liste d'autorisation peuvent etre des handles ou des cibles de chat (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`).

Politique de groupe + mentions

`channels.imessage.groupPolicy` controle la gestion des groupes :

- `allowlist` (par defaut quand configure)
- `open`
- `disabled`

Liste d'autorisation d'expediteurs de groupe : `channels.imessage.groupAllowFrom`.

Repli a l'execution : si `groupAllowFrom` n'est pas defini, les verifications d'expediteur de groupe iMessage se replient sur `allowFrom` quand disponible.
Remarque d'execution : si `channels.imessage` est completement absent, l'execution se replie sur `groupPolicy="allowlist"` et journalise un avertissement (meme si `channels.defaults.groupPolicy` est defini).

Filtrage par mention pour les groupes :

- iMessage n'a pas de metadonnees de mention natives
- la detection de mention utilise des patterns regex (`agents.list[].groupChat.mentionPatterns`, repli `messages.groupChat.mentionPatterns`)
- sans patterns configures, le filtrage par mention ne peut pas etre applique

Les commandes de controle d'expediteurs autorises peuvent contourner le filtrage par mention dans les groupes.

Sessions et reponses deterministes

- Les DMs utilisent le routage direct ; les groupes utilisent le routage de groupe.
- Avec le `session.dmScope=main` par defaut, les DMs iMessage se regroupent dans la session principale de l'agent.
- Les sessions de groupe sont isolees (`agent:<agentId>:imessage:group:<chat_id>`).
- Les reponses routent vers iMessage en utilisant les metadonnees de canal/cible d'origine.

Comportement de fil de type groupe :

Certains fils iMessage multi-participants peuvent arriver avec `is_group=false`.
Si ce `chat_id` est explicitement configure sous `channels.imessage.groups`, OpenClaw le traite comme du trafic de groupe (filtrage de groupe + isolation de session de groupe).

Patrons de deploiement

Utilisez un Apple ID et un utilisateur macOS dedies pour que le trafic bot soit isole de votre profil Messages personnel.

Flux typique :

1. Creez/connectez un utilisateur macOS dedie.
2. Connectez-vous a Messages avec l'Apple ID du bot dans cet utilisateur.
3. Installez `imsg` dans cet utilisateur.
4. Creez un wrapper SSH pour qu'OpenClaw puisse executer `imsg` dans le contexte de cet utilisateur.
5. Pointez `channels.imessage.accounts.<id>.cliPath` et `.dbPath` vers le profil de cet utilisateur.

Le premier lancement peut necessiter des approbations GUI (Automatisation + Acces complet au disque) dans la session de cet utilisateur bot.

Topologie courante :

- la gateway s'execute sur Linux/VM
- iMessage + `imsg` s'execute sur un Mac dans votre tailnet
- le wrapper `cliPath` utilise SSH pour executer `imsg`
- `remoteHost` active les recuperations SCP de pieces jointes

Exemple :

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

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

Utilisez des cles SSH pour que SSH et SCP soient non-interactifs.
Assurez-vous que la cle d'hote est approuvee d'abord (par exemple `ssh [email protected]`) pour que `known_hosts` soit rempli.

iMessage supporte la configuration par compte sous `channels.imessage.accounts`.

Chaque compte peut surcharger des champs comme `cliPath`, `dbPath`, `allowFrom`, `groupPolicy`, `mediaMaxMb`, parametres d'historique et listes de racines de pieces jointes.

Medias, decoupe et cibles de livraison

- l'ingestion des pieces jointes entrantes est optionnelle : `channels.imessage.includeAttachments`
- les chemins de pieces jointes distants peuvent etre recuperes via SCP quand `remoteHost` est defini
- les chemins de pieces jointes doivent correspondre aux racines autorisees :
  - `channels.imessage.attachmentRoots` (local)
  - `channels.imessage.remoteAttachmentRoots` (mode SCP distant)
  - patron de racine par defaut : `/Users/*/Library/Messages/Attachments`
- SCP utilise la verification stricte des cles d'hote (`StrictHostKeyChecking=yes`)
- la taille media sortante utilise `channels.imessage.mediaMaxMb` (par defaut 16 Mo)

- limite de decoupe texte : `channels.imessage.textChunkLimit` (par defaut 4000)
- mode de decoupe : `channels.imessage.chunkMode`
  - `length` (par defaut)
  - `newline` (decoupe prioritaire par paragraphe)

Cibles explicites preferees :

- `chat_id:123` (recommande pour un routage stable)
- `chat_guid:...`
- `chat_identifier:...`

Les cibles par handle sont aussi prises en charge :

- `imessage:+1555...`
- `sms:+1555...`
- `[email protected]`

imsg chats --limit 20

Ecritures de configuration

iMessage autorise les ecritures de configuration initiees par le canal par defaut (pour /config set|unset quand commands.config: true).

Desactivez :

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

Depannage

Validez le binaire et le support RPC :

imsg rpc --help
openclaw channels status --probe

Si la sonde rapporte que RPC n'est pas supporte, mettez a jour `imsg`.

Verifiez :

- `channels.imessage.dmPolicy`
- `channels.imessage.allowFrom`
- les approbations d'appairage (`openclaw pairing list imessage`)

Verifiez :

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

Verifiez :

- `channels.imessage.remoteHost`
- `channels.imessage.remoteAttachmentRoots`
- l'authentification par cle SSH/SCP depuis l'hote de la gateway
- la cle d'hote existe dans `~/.ssh/known_hosts` sur l'hote de la gateway
- la lisibilite du chemin distant sur le Mac executant Messages

Relancez dans un terminal GUI interactif dans le meme contexte utilisateur/session et approuvez les invites :

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

Confirmez que l'Acces complet au disque + l'Automatisation sont accordes pour le contexte de processus qui execute OpenClaw/`imsg`.

Pointeurs de reference de configuration

• Reference de configuration - iMessage
• Configuration de la gateway
• Appairage
• BlueBubbles