Signal

Signal (signal-cli)

Statut : intégration CLI externe. Gateway communique avec signal-cli via HTTP JSON-RPC + SSE.

Prérequis

OpenClaw installé sur votre serveur (le flux Linux ci-dessous a été testé sur Ubuntu 24).
signal-cli disponible sur l’hôte où la passerelle s’exécute.
Un numéro de téléphone pouvant recevoir un SMS de vérification (pour le chemin d’inscription par SMS).
Accès navigateur pour le captcha Signal (signalcaptchas.org) lors de l’inscription.

Configuration rapide (débutant)

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

Configuration minimale :

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

Référence des champs :

Champ	Description
`account`	Numéro de téléphone du bot au format E.164 (`+15551234567`)
`cliPath`	Chemin vers `signal-cli` (`signal-cli` si sur `PATH`)
`dmPolicy`	Politique d’accès DM (`pairing` recommandé)
`allowFrom`	Numéros de téléphone ou valeurs `uuid:<id>` autorisés à envoyer un DM

Ce que c’est

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

Écritures de configuration

Par défaut, Signal est autorisé à écrire des mises à jour de configuration déclenchées par /config set|unset (nécessite commands.config: true).

Désactiver avec :

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

Le modèle de numéro (important)

La passerelle se connecte à un appareil Signal (le compte signal-cli).
Si vous exécutez le bot sur votre compte personnel Signal, 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 distinct.

Chemin de configuration A : lier un compte Signal existant (QR)

Installez signal-cli (version JVM ou native).
Lier un compte de bot :
- signal-cli link -n "OpenClaw" puis scannez le QR dans Signal.
Configurez Signal et démarrez la passerelle.

Exemple :

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

Prise en charge multi-compte : utilisez channels.signal.accounts avec une configuration par compte et name en option. Voir gateway/configuration pour le modèle partagé.

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

Utilisez cette méthode lorsque vous souhaitez un numéro de bot dédié au lieu de lier un compte d’application Signal existant.

Obtenez un numéro capable de 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.
Installez signal-cli sur l’hôte de la passerelle :

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

Si vous utilisez la version JVM (signal-cli-${VERSION}.tar.gz), installez d’abord JRE 25+. Gardez signal-cli à jour ; les notes en amont indiquent que les anciennes versions peuvent cesser de fonctionner lorsque les API du serveur Signal changent.

Enregistrez et vérifiez le numéro :

signal-cli -a +<BOT_PHONE_NUMBER> register

Si un captcha est requis :

Ouvrez https://signalcaptchas.org/registration/generate.html.
Complétez le captcha, copiez la cible du lien signalcaptcha://... depuis « Ouvrir Signal ».
Exécutez à partir de la même IP externe que la session du navigateur lorsque cela est possible.
Exécutez l’enregistrement à nouveau immédiatement (les jetons de captcha expirent rapidement) :

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

Configurez OpenClaw, redémarrez la passerelle, vérifiez le channel :

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

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

Associez votre expéditeur 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 « Contact inconnu ».

Important : l’enregistrement d’un compte de numéro de téléphone avec signal-cli peut déconnecter la session de l’application principale Signal pour ce numéro. Préférez un numéro de bot dédié, ou utilisez le mode de liaison par QR si vous devez conserver la configuration de votre application de téléphone actuelle.

Références en amont :

README signal-cli : https://github.com/AsamK/signal-cli
Flux Captcha : https://github.com/AsamK/signal-cli/wiki/Registration-with-captcha
Flux de liaison : https://github.com/AsamK/signal-cli/wiki/Linking-other-devices-(Provisioning)

Mode démon externe (httpUrl)

Si vous souhaitez gérer signal-cli vous-même (démarrages à froid JVM lents, initialisation du conteneur ou CPU partagés), exécutez le démon séparément et pointez OpenClaw vers celui-ci :

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

Cela évite le lancement automatique et l’attente de démarrage à l’intérieur de OpenClaw. Pour les démarrages lents lors du lancement automatique, définissez channels.signal.startupTimeoutMs.

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

DMs :

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

Groupes :

channels.signal.groupPolicy = open | allowlist | disabled.
channels.signal.groupAllowFrom contrôle qui peut déclencher dans les groupes lorsque allowlist est défini.
channels.signal.groups["<group-id>" | "*"] peut remplacer le comportement de groupe avec requireMention, tools et toolsBySender.
Utilisez channels.signal.accounts.<id>.groups pour des remplacements par compte dans les configurations multi-comptes.
Remarque d’exécution : si channels.signal est complètement manquant, l’exécution revient à groupPolicy="allowlist" pour les vérifications de groupe (même si channels.defaults.groupPolicy est défini).

Fonctionnement (comportement)

signal-cli s’exécute en tant que démon ; la passerelle lit les événements via SSE.
Les messages entrants sont normalisés dans l’enveloppe de channel 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é par morceaux de channels.signal.textChunkLimit (par défaut 4000).
Découpage optionnel par nouvelle ligne : définissez channels.signal.chunkMode="newline" pour diviser sur les lignes vides (limites de paragraphe) avant le découpage par longueur.
Pièces jointes prises en charge (base64 récupéré depuis signal-cli).
Limite de média par défaut : channels.signal.mediaMaxMb (par défaut 8).
Utilisez channels.signal.ignoreAttachments pour ignorer le téléchargement des médias.
Le contexte de l’historique de groupe utilise channels.signal.historyLimit (ou channels.signal.accounts.*.historyLimit), en revenant à messages.groupChat.historyLimit. Définissez 0 pour désactiver (par défaut 50).

Indicateur de frappe + accusés de lecture

Indicateurs de frappe : OpenClaw envoie des signaux de frappe via signal-cli sendTyping et les actualise pendant qu’une réponse est en cours.
Accusés de lecture : quand channels.signal.sendReadReceipts est vrai, OpenClaw transfère les accusés de lecture pour les DMs autorisés.
Signal-cli n’expose pas les accusés de lecture pour les groupes.

Réactions (tool de message)

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

Exemples :

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=✅

Config :

channels.signal.actions.reactions : activer/désactiver les actions de réaction (par défaut vrai).
channels.signal.reactionLevel : off | ack | minimal | extensive.
- off/ack désactive les réactions de l’agent (le tool de message react générera une erreur).
- minimal/extensive active les réactions de l’agent et définit le niveau de guidage.
Remplacements par compte : channels.signal.accounts.<id>.actions.reactions, channels.signal.accounts.<id>.reactionLevel.

Cibles de livraison (CLI/cron)

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

Dépannage

Exécutez d’abord cette procédure :

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

Confirmez ensuite l’état du jumelage DM si nécessaire :

openclaw pairing list signal

Pannes courantes :

Démon accessible mais pas de réponse : vérifiez les paramètres du compte/démon (httpUrl, account) et le mode de réception.
DMs ignorés : l’expéditeur est en attente d’approbation de jumelage.
Messages de groupe ignorés : le filtrage de l’expéditeur/de la mention dans le groupe bloque la livraison.
Erreurs de validation de la configuration après modifications : exécutez openclaw doctor --fix.
Signal manquant dans le diagnostic : confirmez channels.signal.enabled: true.

Vérifications supplémentaires :

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

Pour le flux de triage : /channels/troubleshooting.

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 la migration ou la reconstruction du serveur.
Conservez channels.signal.dmPolicy: "pairing" à moins que vous ne souhaitiez explicitement un accès DM plus large.
La vérification par SMS n’est nécessaire que pour les flux d’enregistrement ou de récupération, mais la perte de contrôle du numéro/compte peut compliquer la ré-inscription.

Référence de configuration (Signal)

Configuration complète : Configuration

Options du fournisseur :

channels.signal.enabled : activer/désactiver le démarrage du channel.
channels.signal.account : E.164 pour le compte 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 : démarrage automatique du démon (vrai par défaut si httpUrl n’est pas défini).
channels.signal.startupTimeoutMs : délai d’attente de démarrage en ms (max 120000).
channels.signal.receiveMode : on-start | manual.
channels.signal.ignoreAttachments : ignorer le téléchargement des pièces jointes.
channels.signal.ignoreStories : ignorer les stories du démon.
channels.signal.sendReadReceipts : transférer les accusés de réception.
channels.signal.dmPolicy : pairing | allowlist | open | disabled (par défaut : appairage).
channels.signal.allowFrom : liste d’autorisation de DM (E.164 ou uuid:<id>). open nécessite "*". Signal n’a pas de noms d’utilisateur ; utilisez les identifiants de téléphone/UUID.
channels.signal.groupPolicy : open | allowlist | disabled (par défaut : liste d’autorisation).
channels.signal.groupAllowFrom : liste d’autorisation des expéditeurs de groupe.
channels.signal.groups : substitutions par groupe indexées par l’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 maximum de messages de groupe à inclure en tant que contexte (0 désactive).
channels.signal.dmHistoryLimit : limite d’historique DM en tours utilisateur. Substitutions par utilisateur : channels.signal.dms["<phone_or_uuid>"].historyLimit.
channels.signal.textChunkLimit : taille des blocs sortants (caractères).
channels.signal.chunkMode : length (par défaut) ou newline pour diviser sur les lignes vides (limites de paragraphe) avant le découpage par longueur.
channels.signal.mediaMaxMb : limite de média entrant/sortant (Mo).

Options globales connexes :

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

Connexes

Aperçu des canaux — tous les canaux pris en charge
Appairage — authentification DM et flux d’appairage
Groupes — comportement de la discussion de groupe et filtrage des mentions
Routage de canal — routage de session pour les messages
Sécurité — modèle d’accès et durcissement