Signal

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.

​

Prérequis

• OpenClaw installé sur votre serveur (le flux Linux ci-dessous a été testé sur Ubuntu 24).
• L’un des éléments suivants :
  • signal-cli disponible sur l’hôte (mode natif), ou
  • conteneur Docker bbernhard/signal-cli-rest-api (mode conteneur).
• Un numéro de téléphone pouvant recevoir un SMS de vérification (pour le parcours d’inscription par SMS).
• Accès au navigateur pour le captcha Signal (signalcaptchas.org) pendant l’inscription.

​

Configuration rapide (débutant)

1. Utilisez un numéro Signal séparé pour le bot (recommandé).
2. Installez signal-cli (Java est requis si vous utilisez la version JVM).
3. Choisissez un parcours de configuration :
   • Parcours A (association QR) : signal-cli link -n "OpenClaw" et scannez avec Signal.
   • Parcours B (inscription SMS) : inscrivez un numéro dédié avec captcha + vérification SMS.
4. Configurez OpenClaw et redémarrez le gateway.
5. Envoyez un premier DM et approuvez l’association (openclaw pairing approve signal <CODE>).

{
  channels: {
    signal: {
      enabled: true,
      account: "+15551234567",
      cliPath: "signal-cli",
      dmPolicy: "pairing",
      allowFrom: ["+15557654321"],
    },
  },
}

​

Ce que c’est

• Canal Signal via signal-cli (pas libsignal intégré).
• Routage déterministe : les réponses retournent toujours vers Signal.
• Les DM partagent la session principale de l’agent ; les groupes sont isolés (agent:<agentId>:signal:group:<groupId>).

​

Écritures de configuration

{
  channels: { signal: { configWrites: false } },
}

​

Le modèle de numéro (important)

• Le gateway se connecte à un appareil Signal (le compte signal-cli).
• Si vous exécutez le bot sur votre compte Signal personnel, il ignorera vos propres messages (protection contre les boucles).
• Pour « j’envoie un message au bot et il répond », utilisez un numéro de bot séparé.

​

Parcours de configuration A : associer un compte Signal existant (QR)

1. Installez signal-cli (version JVM ou native).
2. Associez un compte de bot :
   • signal-cli link -n "OpenClaw" puis scannez le QR dans Signal.
3. Configurez Signal et démarrez le gateway.

{
  channels: {
    signal: {
      enabled: true,
      account: "+15551234567",
      cliPath: "signal-cli",
      dmPolicy: "pairing",
      allowFrom: ["+15557654321"],
    },
  },
}

​

Parcours de configuration B : inscrire un numéro de bot dédié (SMS, Linux)

1. Obtenez un numéro pouvant recevoir des SMS (ou une vérification vocale pour les lignes fixes).
   • Utilisez un numéro de bot dédié pour éviter les conflits de compte/session.
2. Installez signal-cli sur l’hôte du gateway :

VERSION=$(curl -Ls -o /dev/null -w %{url_effective} https://github.com/AsamK/signal-cli/releases/latest | sed -e 's/^.*\/v//')
curl -L -O "https://github.com/AsamK/signal-cli/releases/download/v${VERSION}/signal-cli-${VERSION}-Linux-native.tar.gz"
sudo tar xf "signal-cli-${VERSION}-Linux-native.tar.gz" -C /opt
sudo ln -sf /opt/signal-cli /usr/local/bin/
signal-cli --version

3. Inscrivez et vérifiez le numéro :

signal-cli -a +<BOT_PHONE_NUMBER> register

1. Ouvrez https://signalcaptchas.org/registration/generate.html.
2. Complétez le captcha, copiez la cible du lien signalcaptcha://... depuis « Open Signal ».
3. Exécutez depuis la même IP externe que la session du navigateur lorsque c’est possible.
4. Relancez immédiatement l’inscription (les jetons captcha expirent vite) :

signal-cli -a +<BOT_PHONE_NUMBER> register --captcha '<SIGNALCAPTCHA_URL>'
signal-cli -a +<BOT_PHONE_NUMBER> verify <VERIFICATION_CODE>

4. Configurez OpenClaw, redémarrez le gateway, vérifiez le canal :

# If you run the gateway as a user systemd service:
systemctl --user restart openclaw-gateway.service

# Then verify:
openclaw doctor
openclaw channels status --probe

5. Associez votre expéditeur de DM :
   • Envoyez n’importe quel message au numéro du bot.
   • Approuvez le code sur le serveur : openclaw pairing approve signal <PAIRING_CODE>.
   • Enregistrez le numéro du bot comme contact sur votre téléphone pour éviter « Unknown contact ».

• README de signal-cli : https://github.com/AsamK/signal-cli
• Flux de captcha : https://github.com/AsamK/signal-cli/wiki/Registration-with-captcha
• Flux d’association : https://github.com/AsamK/signal-cli/wiki/Linking-other-devices-(Provisioning)

​

Mode démon externe (httpUrl)

{
  channels: {
    signal: {
      httpUrl: "http://127.0.0.1:8080",
      autoStart: false,
    },
  },
}

​

Mode conteneur (bbernhard/signal-cli-rest-api)

• Le conteneur doit s’exécuter avec MODE=json-rpc pour recevoir les messages en temps réel.
• Inscrivez ou associez votre compte Signal dans le conteneur avant de connecter OpenClaw.

signal-cli:
  image: bbernhard/signal-cli-rest-api:latest
  environment:
    MODE: json-rpc
  ports:
    - "8080:8080"
  volumes:
    - signal-cli-data:/home/.local/share/signal-cli

{
  channels: {
    signal: {
      enabled: true,
      account: "+15551234567",
      httpUrl: "http://signal-cli:8080",
      autoStart: false,
      apiMode: "container", // or "auto" to detect automatically
    },
  },
}

• Utilisez autoStart: false avec le mode conteneur. OpenClaw ne doit pas lancer un démon natif lorsque apiMode: "container" est sélectionné.
• Utilisez MODE=json-rpc pour la réception. MODE=normal peut faire paraître /v1/about sain, mais /v1/receive/{account} ne passe pas en WebSocket ; OpenClaw ne sélectionnera donc pas le streaming de réception du conteneur en mode auto.
• Définissez apiMode: "container" lorsque vous savez que httpUrl pointe vers l’API REST de bbernhard. Définissez apiMode: "native" lorsque vous savez qu’il pointe vers JSON-RPC/SSE natif de signal-cli. Utilisez "auto" lorsque le déploiement peut varier.
• Les téléchargements de pièces jointes du conteneur respectent les mêmes limites d’octets multimédias que le mode natif. Les réponses trop volumineuses sont rejetées avant d’être entièrement mises en mémoire tampon lorsque le serveur envoie Content-Length, et pendant le streaming sinon.

​

Contrôle d’accès (DM + groupes)

• Par défaut : channels.signal.dmPolicy = "pairing".
• Les expéditeurs inconnus reçoivent un code d’association ; les messages sont ignorés jusqu’à approbation (les codes expirent après 1 heure).
• Approuvez via :
  • openclaw pairing list signal
  • openclaw pairing approve signal <CODE>
• L’association est l’échange de jeton par défaut pour les DM Signal. Détails : Association
• Les expéditeurs uniquement UUID (depuis sourceUuid) sont stockés sous forme de uuid:<id> dans channels.signal.allowFrom.

• channels.signal.groupPolicy = open | allowlist | disabled.
• channels.signal.groupAllowFrom contrôle quels groupes ou expéditeurs peuvent déclencher des réponses de groupe lorsque allowlist est défini ; les entrées peuvent être des ID de groupe Signal (bruts, group:<id> ou signal:group:<id>), des numéros de téléphone d’expéditeur, des valeurs uuid:<id> ou *.
• channels.signal.groups["<group-id>" | "*"] peut remplacer le comportement de groupe avec requireMention, tools et toolsBySender.
• Utilisez channels.signal.accounts.<id>.groups pour les remplacements par compte dans les configurations multicomptes.
• L’inscription d’un groupe Signal sur liste d’autorisation via groupAllowFrom ne désactive pas à elle seule le filtrage par mention. Une entrée channels.signal.groups["<group-id>"] configurée spécifiquement traite chaque message de groupe sauf si requireMention=true est défini.
• Note d’exécution : si channels.signal est totalement absent, l’exécution revient à groupPolicy="allowlist" pour les vérifications de groupe (même si channels.defaults.groupPolicy est défini).

​

Fonctionnement (comportement)

• Mode natif : signal-cli s’exécute comme un démon ; le gateway lit les événements via SSE.
• Mode conteneur : le gateway envoie via l’API REST et reçoit via WebSocket.
• Les messages entrants sont normalisés dans l’enveloppe de canal partagée.
• Les réponses sont toujours routées vers le même numéro ou groupe.

​

Médias + limites

• Le texte sortant est découpé selon channels.signal.textChunkLimit (4000 par défaut).
• Découpage facultatif par retours à la ligne : définissez channels.signal.chunkMode="newline" pour découper sur les lignes vides (limites de paragraphes) avant le découpage par longueur.
• Pièces jointes prises en charge (base64 récupéré depuis signal-cli).
• Les pièces jointes de note vocale utilisent le nom de fichier signal-cli comme repli MIME lorsque contentType est absent, afin que la transcription audio puisse encore classer les mémos vocaux AAC.
• Plafond média par défaut : channels.signal.mediaMaxMb (8 par défaut).
• Utilisez channels.signal.ignoreAttachments pour ignorer le téléchargement des médias.
• Le contexte d’historique de groupe utilise channels.signal.historyLimit (ou channels.signal.accounts.*.historyLimit), avec repli sur messages.groupChat.historyLimit. Définissez 0 pour désactiver (50 par défaut).

​

Saisie + accusés de lecture

• Indicateurs de saisie : OpenClaw envoie des signaux de saisie via signal-cli sendTyping et les actualise pendant l’exécution d’une réponse.
• Accusés de lecture : lorsque channels.signal.sendReadReceipts vaut true, OpenClaw transmet les accusés de lecture pour les DM autorisés.
• Signal-cli n’expose pas les accusés de lecture pour les groupes.

​

Réactions (outil de message)

• Utilisez message action=react avec channel=signal.
• Cibles : expéditeur E.164 ou UUID (utilisez uuid:<id> depuis la sortie d’appairage ; l’UUID nu fonctionne aussi).
• messageId est l’horodatage Signal du message auquel vous réagissez.
• Les réactions de groupe nécessitent targetAuthor ou targetAuthorUuid.

message action=react channel=signal target=uuid:123e4567-e89b-12d3-a456-426614174000 messageId=1737630212345 emoji=🔥
message action=react channel=signal target=+15551234567 messageId=1737630212345 emoji=🔥 remove=true
message action=react channel=signal target=signal:group:<groupId> targetAuthor=uuid:<sender-uuid> messageId=1737630212345 emoji=✅

• channels.signal.actions.reactions : active/désactive les actions de réaction (activé par défaut).
• channels.signal.reactionLevel : off | ack | minimal | extensive.
  • off/ack désactive les réactions de l’agent (react de l’outil de message renverra une erreur).
  • minimal/extensive active les réactions de l’agent et définit le niveau de consignes.
• Remplacements par compte : channels.signal.accounts.<id>.actions.reactions, channels.signal.accounts.<id>.reactionLevel.

​

Cibles de livraison (CLI/cron)

• Messages directs : signal:+15551234567 (ou E.164 simple).
• Messages directs UUID : uuid:<id> (ou UUID nu).
• Groupes : signal:group:<groupId>.
• Noms d’utilisateur : username:<name> (si pris en charge par votre compte Signal).

​

Dépannage

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

openclaw pairing list signal

• Démon joignable mais aucune réponse : vérifiez les paramètres du compte/démon (httpUrl, account) et le mode de réception.
• Messages directs ignorés : l’expéditeur est en attente d’approbation d’appairage.
• Messages de groupe ignorés : le filtrage par expéditeur/mention du groupe bloque la livraison.
• Erreurs de validation de configuration après modifications : exécutez openclaw doctor --fix.
• Signal absent des diagnostics : confirmez channels.signal.enabled: true.

openclaw pairing list signal
pgrep -af signal-cli
grep -i "signal" "/tmp/openclaw/openclaw-$(date +%Y-%m-%d).log" | tail -20

​

Notes de sécurité

• signal-cli stocke les clés de compte localement (généralement ~/.local/share/signal-cli/data/).
• Sauvegardez l’état du compte Signal avant une migration ou reconstruction de serveur.
• Conservez channels.signal.dmPolicy: "pairing" sauf si vous souhaitez explicitement un accès plus large aux messages directs.
• La vérification par SMS n’est nécessaire que pour les flux d’inscription ou de récupération, mais perdre le contrôle du numéro/compte peut compliquer une nouvelle inscription.

​

Référence de configuration (Signal)

• channels.signal.enabled : active/désactive le démarrage du canal.
• channels.signal.apiMode : auto | native | container (par défaut : auto). Voir Mode conteneur.
• channels.signal.account : E.164 pour le compte du bot.
• channels.signal.cliPath : chemin vers signal-cli.
• channels.signal.httpUrl : URL complète du démon (remplace l’hôte/le port).
• channels.signal.httpHost, channels.signal.httpPort : liaison du démon (par défaut 127.0.0.1:8080).
• channels.signal.autoStart : lance automatiquement le démon (par défaut activé si httpUrl n’est pas défini).
• channels.signal.startupTimeoutMs : délai d’attente de démarrage en ms (plafond 120000).
• channels.signal.receiveMode : on-start | manual.
• channels.signal.ignoreAttachments : ignore les téléchargements de pièces jointes.
• channels.signal.ignoreStories : ignore les stories du démon.
• channels.signal.sendReadReceipts : transmet les confirmations de lecture.
• channels.signal.dmPolicy : pairing | allowlist | open | disabled (par défaut : pairing).
• channels.signal.allowFrom : liste d’autorisation des messages directs (E.164 ou uuid:<id>). open nécessite "*". Signal n’a pas de noms d’utilisateur ; utilisez les identifiants téléphone/UUID.
• channels.signal.groupPolicy : open | allowlist | disabled (par défaut : allowlist).
• channels.signal.groupAllowFrom : liste d’autorisation de groupe ; accepte les ID de groupe Signal (bruts, group:<id> ou signal:group:<id>), les numéros E.164 des expéditeurs ou les valeurs uuid:<id>.
• channels.signal.groups : remplacements par groupe indexés par ID de groupe Signal (ou "*"). Champs pris en charge : requireMention, tools, toolsBySender.
• channels.signal.accounts.<id>.groups : version par compte de channels.signal.groups pour les configurations multi-comptes.
• channels.signal.historyLimit : nombre maximal de messages de groupe à inclure comme contexte (0 désactive).
• channels.signal.dmHistoryLimit : limite d’historique des messages directs en tours utilisateur. Remplacements par utilisateur : channels.signal.dms["<phone_or_uuid>"].historyLimit.
• channels.signal.textChunkLimit : taille des segments sortants (caractères).
• channels.signal.chunkMode : length (par défaut) ou newline pour découper sur les lignes vides (limites de paragraphes) avant le découpage par longueur.
• channels.signal.mediaMaxMb : plafond des médias entrants/sortants (Mo).

• agents.list[].groupChat.mentionPatterns (Signal ne prend pas en charge les mentions natives).
• messages.groupChat.mentionPatterns (solution de repli globale).
• messages.responsePrefix.

​

Connexe

• Vue d’ensemble des canaux — tous les canaux pris en charge
• Appairage — authentification des messages directs et flux d’appairage
• Groupes — comportement de discussion de groupe et filtrage par mention
• Routage des canaux — routage de session pour les messages
• Sécurité — modèle d’accès et durcissement