OpenClaw

Canal BlueBubbles OpenClaw

Messagerie
Moyen

Connectez OpenClaw à iMessage via l'API REST BlueBubbles. Cette intégration transforme votre Mac en passerelle iMessage — installez l'application serveur BlueBubbles, activez l'API Web, et votre assistant IA peut envoyer et recevoir des messages iMessage, des réactions tapback et des pièces jointes multimédias. BlueBubbles est le canal iMessage recommandé, remplaçant l'ancienne approche imsg CLI.

Info rapide
DifficultéMoyen
CatégorieMessagerie
Fonctionnalités prises en charge4 / 6

BlueBubbles Fonctionnalités prises en charge

Messages texte

Pris en charge

Médias et fichiers

Pris en charge

Réactions

Pris en charge

Fils de discussion

Non pris en charge

Messages vocaux

Non pris en charge

Discussion de groupe

Pris en charge

BlueBubbles Prérequis

  • Un Mac sous macOS High Sierra (10.13) ou ultérieur (Ventura 13+ recommandé pour toutes les fonctionnalités ; Tahoe 26 pris en charge avec des limitations)
  • L'application serveur BlueBubbles installée depuis bluebubbles.app
  • L'API Web activée avec un mot de passe défini dans la configuration BlueBubbles
  • OpenClaw Gateway en cours d'exécution et configuré

BlueBubbles Configuration rapide

1

Installer le serveur BlueBubbles sur votre Mac

Téléchargez et installez l'application serveur BlueBubbles depuis bluebubbles.app/install. Lancez l'application, connectez-vous avec votre Apple ID et terminez la configuration initiale. Assurez-vous que iMessage fonctionne correctement sur le Mac.

2

Activer l'API Web

Dans les paramètres du serveur BlueBubbles, activez l'API Web/REST et définissez un mot de passe fort. Notez l'URL du serveur (par ex. http://localhost:1234) — vous en aurez besoin pour la configuration OpenClaw.

3

Ajouter la configuration du canal BlueBubbles

Exécutez 'openclaw onboard' et sélectionnez BlueBubbles, ou ajoutez manuellement la configuration du canal dans ~/.openclaw/openclaw.json avec votre serverUrl et password. Configurez le webhookPath si nécessaire.

4

Configurer le webhook et tester

Pointez les webhooks BlueBubbles vers votre Gateway : https://your-gateway-host:3000/bluebubbles-webhook?password=<password>. Démarrez le Gateway et envoyez un iMessage de test pour vérifier la connexion. Si vous utilisez la politique pairing, approuvez l'expéditeur via 'openclaw pairing approve bluebubbles <code>'.

BlueBubbles Exemple de configuration

config.json
{
  "channels": {
    "bluebubbles": {
      "enabled": true,
      "serverUrl": "http://localhost:1234",
      "password": "YOUR_BLUEBUBBLES_PASSWORD",
      "webhookPath": "/bluebubbles-webhook",
      "dmPolicy": "pairing"
    }
  }
}

BlueBubbles Documentation Détaillée

Aperçu de l'architecture

OpenClaw se connecte à iMessage via l'application serveur BlueBubbles fonctionnant sur un Mac. BlueBubbles expose une API REST que le Gateway utilise pour envoyer des messages, des réactions et gérer les conversations. Les messages entrants sont livrés via des webhooks — BlueBubbles pousse les événements de nouveaux messages vers le point de terminaison webhook du Gateway. Le flux d'architecture est : iMessage arrive sur le Mac → Serveur BlueBubbles → Webhook push vers le Gateway → OpenClaw traite avec l'IA → Appel API REST vers BlueBubbles → iMessage livré. Cette approche nécessite un Mac constamment en ligne (physique ou VM), car iMessage est un service exclusif Apple. Le Mac sert de pont entre l'écosystème de messagerie Apple et votre assistant OpenClaw.
Un Mac Mini dédié ou une VM macOS est idéal pour exécuter BlueBubbles comme passerelle iMessage permanente.
BlueBubbles prend en charge l'API privée pour les fonctionnalités avancées comme les réactions tapback, l'édition de messages et la suppression — assurez-vous de l'activer dans les paramètres BlueBubbles.

Configuration du serveur BlueBubbles

La configuration de BlueBubbles nécessite l'installation de l'application serveur sur votre Mac : 1. Téléchargez BlueBubbles depuis bluebubbles.app/install et lancez l'application. 2. Connectez-vous avec votre Apple ID et vérifiez que iMessage fonctionne sur le Mac. 3. Activez l'API Web/REST dans les paramètres BlueBubbles. 4. Définissez un mot de passe API fort — ce mot de passe authentifie toutes les requêtes API et les livraisons webhook. 5. Notez l'URL du serveur affichée dans l'application (par défaut : http://localhost:1234). 6. Optionnel : activez l'API privée pour les fonctionnalités avancées (réactions, édition, suppression). Le serveur doit rester en fonctionnement pour que le pont iMessage fonctionne. Configurez BlueBubbles pour démarrer automatiquement au démarrage pour plus de fiabilité.
webhook URL
# Format d'URL webhook pour votre Gateway
https://your-gateway-host:3000/bluebubbles-webhook?password=YOUR_PASSWORD
Gardez votre mot de passe API BlueBubbles en sécurité. Si le serveur est exposé sur le réseau, activez HTTPS sur BlueBubbles et utilisez des règles de pare-feu pour restreindre l'accès. Les proxys inverses sur le même hôte contournent l'authentification par mot de passe — ajoutez une authentification au niveau du proxy et configurez gateway.trustedProxies.

Politiques de DM

Les politiques de DM (Message Direct) contrôlent qui peut interagir avec votre assistant IA via iMessage. OpenClaw prend en charge quatre politiques : • pairing (par défaut) — Les expéditeurs inconnus reçoivent un code d'appairage à durée limitée (expire après 1 heure). Approuvez ou refusez via 'openclaw pairing approve bluebubbles <CODE>'. Une fois approuvé, ils peuvent discuter librement. • allowlist — Seuls les numéros de téléphone et adresses e-mail listés dans allowFrom peuvent envoyer des messages. Les autres sont silencieusement ignorés. Format E.164 supporté pour les numéros. • open — Toute personne qui envoie un message obtient une réponse. À utiliser avec prudence. • disabled — Le traitement des DM est complètement désactivé.
openclaw.json
{
  "channels": {
    "bluebubbles": {
      "dmPolicy": "allowlist",
      "allowFrom": ["+15551234567", "user@example.com"]
    }
  }
}
Le champ allowFrom accepte les numéros de téléphone (format E.164, ex : +15551234567) et les adresses e-mail pour le routage iMessage.

Gestion des discussions de groupe

OpenClaw prend en charge les discussions de groupe iMessage via BlueBubbles avec un contrôle d'accès flexible : • groupPolicy contrôle qui peut déclencher le bot dans les discussions de groupe : - open — Tous les membres du groupe peuvent interagir - allowlist — Seules les adresses de groupAllowFrom peuvent déclencher - disabled (par défaut) — Les messages de groupe sont ignorés • Détection de mention — Quand requireMention est true (par défaut pour les groupes), le bot ne répond que lorsqu'il est mentionné. Les modèles de mention sont configurés dans agents.list[].groupChat.mentionPatterns. • Configuration par groupe — Utilisez l'objet groups pour définir des règles requireMention différentes pour des discussions spécifiques.
openclaw.json
{
  "channels": {
    "bluebubbles": {
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["+15551234567"],
      "groups": {
        "iMessage;+;chat123456": {
          "requireMention": false
        }
      }
    }
  }
}

Actions et effets iMessage

BlueBubbles expose un riche ensemble d'actions natives iMessage via l'API privée. Chaque action peut être activée/désactivée individuellement : • reactions — Envoyer et recevoir des réactions tapback (cœur, pouce levé, pouce baissé, rire, emphase, question) • edit — Modifier les messages envoyés (macOS 13+ requis ; actuellement cassé sur macOS Tahoe) • unsend — Supprimer les messages envoyés (macOS 13+) • reply — Threading de messages par GUID • sendWithEffect — Envoyer des messages avec des effets de bulle (slam, fort, doux, encre invisible, etc.) • sendAttachment — Envoyer des fichiers multimédias et des mémos vocaux (format MP3/CAF pour la voix ; BlueBubbles gère la conversion MP3→CAF) Actions de gestion de groupe : • renameGroup — Renommer les discussions de groupe • setGroupIcon — Définir les photos de groupe (instable sur macOS Tahoe) • addParticipant / removeParticipant / leaveGroup — Gérer les membres du groupe
openclaw.json
{
  "channels": {
    "bluebubbles": {
      "actions": {
        "reactions": true,
        "edit": true,
        "unsend": true,
        "reply": true,
        "sendWithEffect": true,
        "sendAttachment": true
      }
    }
  }
}
Sur macOS Tahoe (26), l'action edit est actuellement cassée en raison de changements dans l'API privée, et setGroupIcon n'est pas fiable (l'API retourne un succès mais l'icône ne se synchronise pas). Si vous utilisez Tahoe, désactivez ces actions manuellement.

Livraison et découpage des messages

OpenClaw offre une livraison configurable par blocs pour les longues réponses IA : • textChunkLimit — Caractères maximum par bloc de message (par défaut : 4000). iMessage n'a pas de limite stricte, mais les messages trop longs peuvent ne pas s'afficher correctement sur tous les appareils. • chunkMode — Contrôle la méthode de découpage du texte : - length (par défaut) — Découpage strict à textChunkLimit caractères - newline — Découpage aux limites de paragraphe pour une lecture plus naturelle • blockStreaming — Quand true, les réponses sont envoyées par blocs pendant la génération, sans attendre la réponse complète. Les accusés de lecture sont envoyés par défaut pour maintenir un flux de conversation naturel. Les indicateurs de saisie sont automatiquement envoyés avant et pendant la génération des réponses IA.
openclaw.json
{
  "channels": {
    "bluebubbles": {
      "textChunkLimit": 4000,
      "chunkMode": "newline",
      "blockStreaming": false,
      "sendReadReceipts": true
    }
  }
}

Médias et pièces jointes

BlueBubbles prend en charge l'envoi et la réception de médias via iMessage : • Les pièces jointes entrantes sont automatiquement téléchargées et mises en cache par le Gateway. La taille maximale des fichiers entrants est contrôlée par mediaMaxMb (par défaut : 8 Mo). • Les mémos vocaux peuvent être envoyés via l'action sendAttachment avec asVoice: true. BlueBubbles convertit automatiquement MP3 en CAF pour une lecture native des mémos vocaux iMessage. • Les médias sortants sont envoyés via l'action sendAttachment avec les paramètres buffer, filename et un type mime optionnel.
Pour les mémos vocaux, utilisez le format MP3 ou CAF. BlueBubbles convertira automatiquement MP3 en CAF pour une lecture native iMessage.
Ajustez mediaMaxMb si vous devez gérer des pièces jointes plus volumineuses — la valeur par défaut de 8 Mo couvre la plupart des photos et courtes vidéos.

Gestion des ID de message

BlueBubbles utilise deux types d'identifiants de message : • ID courts — Jetons temporaires en mémoire (comme 1, 2, 3). Rapides mais éphémères. Expirent au redémarrage du Gateway ou lors de l'éviction du cache. • ID complets — Identifiants de fournisseur persistants (MessageSidFull, ReplyToIdFull). Survivent aux redémarrages et sont stables pour les références à long terme. Les deux formats sont acceptés dans les paramètres d'action (messageId, replyTo, etc.). Pour les automatisations durables qui doivent référencer des messages entre les redémarrages, utilisez toujours les ID complets.
Utilisez les ID de message complets pour toute automatisation devant survivre aux redémarrages du Gateway. Les ID courts sont pratiques pour l'utilisation interactive mais deviennent invalides après un redémarrage.

Adressage et routage

BlueBubbles prend en charge plusieurs formats d'adressage pour la livraison des messages. Ordre de routage préféré par stabilité : 1. chat_guid — Format le plus stable : chat_guid:iMessage;-;+15555550123 2. chat_id — Identifiant numérique de chat : chat_id:123 3. chat_identifier — Chaîne d'identifiant de chat 4. Adresses directes — Numéro de téléphone (+15555550123) ou e-mail (user@example.com) Lors de l'envoi à une adresse directe sans chat existant, BlueBubbles crée automatiquement un nouveau DM via POST /api/v1/chat/new (nécessite l'API privée).
Utilisez le format chat_guid dans les automatisations pour le routage de messages le plus fiable.

Sécurité et authentification webhook

BlueBubbles authentifie les livraisons webhook avec le mot de passe configuré. Le Gateway vérifie que le paramètre de mot de passe (via query string ou en-tête) correspond à la configuration channels.bluebubbles.password. Considérations de sécurité : • Les requêtes localhost sont automatiquement approuvées et contournent la vérification du mot de passe. • Les proxys inverses sur le même hôte contournent également la vérification — si vous utilisez un proxy inverse sur la même machine, ajoutez une authentification au niveau du proxy et configurez gateway.trustedProxies. • Activez HTTPS sur le serveur BlueBubbles pour chiffrer les communications. • Utilisez des règles de pare-feu pour restreindre l'accès externe au port API BlueBubbles. Pour les déploiements en production, utilisez toujours HTTPS et assurez-vous que le point de terminaison webhook n'est pas publiquement accessible sans authentification.
Les proxys inverses sur le même hôte contournent l'authentification par mot de passe BlueBubbles. Lors de l'utilisation d'un proxy inverse, configurez toujours l'authentification au niveau du proxy et définissez gateway.trustedProxies.

Maintien en vie de Messages.app (Headless/VM)

Si vous exécutez BlueBubbles sur un Mac headless ou une VM, Messages.app peut passer en mode veille et cesser de traiter les messages. La solution est de configurer un LaunchAgent qui exécute un AppleScript toutes les 5 minutes pour toucher l'interface de script de Messages. Ce script de maintien en vie ignore en toute sécurité les erreurs transitoires et ne vole pas le focus des autres applications. Il est essentiel pour le fonctionnement fiable sans surveillance du pont iMessage. Configurez un plist macOS LaunchAgent pour exécuter régulièrement l'AppleScript afin de maintenir la réactivité de Messages.app.
Ceci n'est nécessaire que pour les environnements headless/VM. Si votre Mac a une session de bureau active avec Messages.app visible, le maintien en vie n'est pas nécessaire.
Utilisez launchctl pour gérer le LaunchAgent — chargez-le au démarrage pour un fonctionnement entièrement sans surveillance.

BlueBubbles Référence de Configuration

enabled
Type: booleanDefault: false

Activer ou désactiver le canal BlueBubbles

serverUrl
Type: stringDefault: ""

URL de base de l'API REST BlueBubbles (ex : http://localhost:1234)

password
Type: stringDefault: ""

Mot de passe API BlueBubbles pour l'authentification

webhookPath
Type: stringDefault: "/bluebubbles-webhook"

Chemin du point de terminaison webhook pour la réception des messages

dmPolicy
Type: stringDefault: "pairing"

Contrôle qui peut envoyer des DM au bot. Options : pairing, allowlist, open, disabled

allowFrom
Type: string[]Default: []

Numéros de téléphone et e-mails autorisés à envoyer des messages (format E.164 pour les téléphones)

groupPolicy
Type: stringDefault: "allowlist"

Politique de discussion de groupe. Options : open, allowlist, disabled

groupAllowFrom
Type: string[]Default: []

Adresses d'expéditeurs autorisés à déclencher le bot dans les discussions de groupe

sendReadReceipts
Type: booleanDefault: true

Envoyer une confirmation de lecture lors du traitement des messages

blockStreaming
Type: booleanDefault: false

Activer le streaming de réponse par blocs au lieu d'attendre la réponse complète

textChunkLimit
Type: numberDefault: 4000

Nombre maximum de caractères par bloc de message texte sortant

chunkMode
Type: stringDefault: "length"

Mode de découpage du texte. Options : length (par taille), newline (par paragraphe)

mediaMaxMb
Type: numberDefault: 8

Taille maximale des pièces jointes entrantes en mégaoctets

historyLimit
Type: numberDefault: -

Nombre maximum de messages de groupe inclus comme contexte IA (0 pour désactiver)

dmHistoryLimit
Type: numberDefault: -

Limite d'historique de conversation DM pour le contexte IA

actions.reactions
Type: booleanDefault: true

Activer les réactions tapback (nécessite l'API privée)

actions.edit
Type: booleanDefault: true

Activer l'édition de messages (nécessite macOS 13+ ; cassé sur Tahoe)

actions.unsend
Type: booleanDefault: true

Activer la suppression de messages (nécessite macOS 13+)

actions.reply
Type: booleanDefault: true

Activer le threading de messages par GUID

actions.sendWithEffect
Type: booleanDefault: true

Activer les effets de bulle iMessage (slam, fort, doux, etc.)

actions.sendAttachment
Type: booleanDefault: true

Activer la livraison de médias et de mémos vocaux

BlueBubbles Questions Fréquentes

BlueBubbles Dépannage

Le webhook ne reçoit pas de messages

L'URL webhook dans BlueBubbles ne correspond pas au point de terminaison du Gateway, ou le paramètre de mot de passe est incorrect.

Vérifiez que l'URL webhook est définie sur https://your-gateway-host:3000/bluebubbles-webhook?password=YOUR_PASSWORD. Vérifiez que channels.bluebubbles.webhookPath correspond au chemin dans l'URL. Examinez les logs du Gateway pour les tentatives webhook entrantes.
Le Gateway se connecte mais les actions échouent (réactions, édition, suppression)

L'API privée BlueBubbles n'est pas activée, ou la version du serveur ne prend pas en charge les points de terminaison API requis.

Activez l'API privée dans les paramètres du serveur BlueBubbles. Mettez à jour BlueBubbles vers la dernière version. Si des actions spécifiques échouent sur macOS Tahoe, désactivez-les individuellement : channels.bluebubbles.actions.edit=false.
Messages.app cesse de répondre sur un Mac headless

Messages.app passe en mode veille sur les configurations headless/VM et arrête le traitement de l'interface de script.

Configurez le LaunchAgent de maintien en vie AppleScript pour toucher l'interface de script de Messages toutes les 5 minutes. Assurez-vous que le LaunchAgent est chargé via launchctl et s'exécute au démarrage.
Les messages du bot ne sont pas des iMessages (bulles vertes)

Le numéro de téléphone ou l'e-mail du destinataire n'est pas enregistré avec iMessage, ou l'Apple ID sur le Mac a iMessage désactivé.

Vérifiez que iMessage est activé dans les préférences de Messages.app sur le Mac. Vérifiez que le destinataire utilise un appareil Apple avec iMessage activé. Les bulles vertes indiquent un repli SMS, que BlueBubbles peut ne pas supporter selon la configuration.
L'action d'édition échoue sur macOS Tahoe

Problème connu — macOS Tahoe (26) a cassé le point de terminaison de l'API privée pour l'édition de messages.

Désactivez l'action d'édition : définissez channels.bluebubbles.actions.edit sur false. C'est une limitation connue de BlueBubbles sur Tahoe. Surveillez les versions de BlueBubbles pour un correctif.
Voir la documentation complèteRetour à tous les canaux

Canaux associés

WhatsApp

Medium

OpenClaw connexion via QR code avec le protocole Baileys

Guide de configuration

Telegram

Easy

OpenClaw integration Bot API via le framework grammY

Guide de configuration

Discord

Easy

OpenClaw integration Bot Token avec discord.js

Guide de configuration