Signal (signal-cli)

Statut : integration CLI externe. La gateway communique avec signal-cli via HTTP JSON-RPC + SSE.

Prerequis

OpenClaw installe sur votre serveur (le flux Linux ci-dessous teste sur Ubuntu 24).
signal-cli disponible sur l’hote ou la gateway s’execute.
Un numero de telephone pouvant recevoir un SMS de verification (pour le chemin d’inscription SMS).
Acces navigateur pour le captcha Signal (signalcaptchas.org) pendant l’inscription.

Configuration rapide (debutant)

Utilisez un numero Signal separe pour le bot (recommande).
Installez signal-cli (Java requis si vous utilisez le build 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 numero dedie avec captcha + verification SMS.
Configurez OpenClaw et redemarrez la gateway.
Envoyez un premier DM et approuvez l’appairage (openclaw pairing approve signal <CODE>).

Configuration minimale :

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

Reference des champs :

Champ	Description
`account`	Numero de telephone du bot au format E.164 (`+15551234567`)
`cliPath`	Chemin vers `signal-cli` (`signal-cli` s’il est dans le `PATH`)
`dmPolicy`	Politique d’acces DM (`pairing` recommande)
`allowFrom`	Numeros de telephone ou valeurs `uuid:<id>` autorises pour les DMs

Description

Canal Signal via signal-cli (pas libsignal embarque).
Routage deterministe : les reponses retournent toujours a Signal.
Les DMs partagent la session principale de l’agent ; les groupes sont isoles (agent:<agentId>:signal:group:<groupId>).

Ecritures de configuration

Par defaut, Signal est autorise a ecrire des mises a jour de configuration declenchees par /config set|unset (necessite commands.config: true).

Desactivez avec :

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

Le modele de numero (important)

La gateway se connecte a un appareil Signal (le compte signal-cli).
Si vous executez le bot sur votre compte Signal personnel, il ignorera vos propres messages (protection de boucle).
Pour « j’envoie un message au bot et il repond », utilisez un numero de bot separe.

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

Installez signal-cli (build JVM ou natif).
Liez un compte bot :
- signal-cli link -n "OpenClaw" puis scannez le QR dans Signal.
Configurez Signal et demarrez la gateway.

Exemple :

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

Support multi-comptes : utilisez channels.signal.accounts avec la config par compte et un name optionnel. Voir gateway/configuration pour le patron partage.

Chemin de configuration B : inscrire un numero de bot dedie (SMS, Linux)

Utilisez ceci quand vous voulez un numero de bot dedie au lieu de lier un compte Signal existant.

Obtenez un numero pouvant recevoir des SMS (ou verification vocale pour les lignes fixes).
- Utilisez un numero dedie pour eviter les conflits de compte/session.
Installez signal-cli sur l’hote de la 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

Si vous utilisez le build JVM (signal-cli-${VERSION}.tar.gz), installez d’abord JRE 25+. Gardez signal-cli a jour ; l’amont note que les anciennes versions peuvent casser quand les APIs du serveur Signal changent.

Inscrivez et verifiez le numero :

signal-cli -a +<BOT_PHONE_NUMBER> register

Si un captcha est requis :

Ouvrez https://signalcaptchas.org/registration/generate.html.
Completez le captcha, copiez le lien signalcaptcha://... depuis « Ouvrir Signal ».
Executez depuis la meme IP externe que la session navigateur si possible.
Relancez l’inscription immediatement (les jetons captcha expirent rapidement) :

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

Configurez OpenClaw, redemarrez la gateway, verifiez le canal :

# Si vous executez la gateway comme service systemd utilisateur :
systemctl --user restart openclaw-gateway

# Puis verifiez :
openclaw doctor
openclaw channels status --probe

Appairez votre expediteur DM :
- Envoyez n’importe quel message au numero du bot.
- Approuvez le code sur le serveur : openclaw pairing approve signal <PAIRING_CODE>.
- Enregistrez le numero du bot comme contact sur votre telephone pour eviter « Contact inconnu ».

Avertissement : Inscrire un compte numero de telephone avec signal-cli peut desauthentifier la session principale de l’application Signal pour ce numero. Preferez un numero de bot dedie, ou utilisez le mode lien QR si vous devez garder votre configuration d’application telephone existante.

References 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 daemon externe (httpUrl)

Si vous voulez gerer signal-cli vous-meme (demarrages JVM lents, init de conteneur ou CPUs partagees), executez le daemon separement et pointez OpenClaw vers lui :

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

Cela ignore le lancement automatique et l’attente de demarrage dans OpenClaw. Pour les demarrages lents en mode auto-spawn, definissez channels.signal.startupTimeoutMs.

Controle d’acces (DMs + groupes)

DMs :

Par defaut : channels.signal.dmPolicy = "pairing".
Les expediteurs inconnus recoivent un code d’appairage ; les messages sont ignores jusqu’a approbation (les codes expirent apres 1 heure).
Approbation via :
- openclaw pairing list signal
- openclaw pairing approve signal <CODE>
L’appairage est l’echange de jetons par defaut pour les DMs Signal. Details : Appairage
Les expediteurs UUID uniquement (depuis sourceUuid) sont stockes comme uuid:<id> dans channels.signal.allowFrom.

Groupes :

channels.signal.groupPolicy = open | allowlist | disabled.
channels.signal.groupAllowFrom controle qui peut declencher dans les groupes quand allowlist est defini.
channels.signal.groups["<group-id>" | "*"] peut surcharger le comportement de groupe avec requireMention, tools et toolsBySender.
Utilisez channels.signal.accounts.<id>.groups pour les surcharges par compte dans les configurations multi-comptes.
Remarque d’execution : si channels.signal est completement absent, l’execution se replie sur groupPolicy="allowlist" pour les verifications de groupe (meme si channels.defaults.groupPolicy est defini).

Fonctionnement (comportement)

signal-cli s’execute comme daemon ; la gateway lit les evenements via SSE.
Les messages entrants sont normalises dans l’enveloppe de canal partagee.
Les reponses routent toujours vers le meme numero ou groupe.

Medias + limites

Le texte sortant est decoupe a channels.signal.textChunkLimit (par defaut 4000).
Decoupe optionnelle par nouvelle ligne : definissez channels.signal.chunkMode="newline" pour decouper sur les lignes vides (limites de paragraphe) avant la decoupe par longueur.
Pieces jointes prises en charge (base64 recupere depuis signal-cli).
Limite media par defaut : channels.signal.mediaMaxMb (par defaut 8).
Utilisez channels.signal.ignoreAttachments pour ignorer le telechargement de medias.
Le contexte d’historique de groupe utilise channels.signal.historyLimit (ou channels.signal.accounts.*.historyLimit), se repliant sur messages.groupChat.historyLimit. Mettez 0 pour desactiver (par defaut 50).

Saisie + accuses de lecture

Indicateurs de saisie : OpenClaw envoie des signaux de saisie via signal-cli sendTyping et les rafraichit pendant qu’une reponse est en cours.
Accuses de lecture : quand channels.signal.sendReadReceipts est true, OpenClaw transmet les accuses de lecture pour les DMs autorises.
Signal-cli n’expose pas les accuses de lecture pour les groupes.

Reactions (outil message)

Utilisez message action=react avec channel=signal.
Cibles : E.164 de l’expediteur ou UUID (utilisez uuid:<id> depuis la sortie d’appairage ; le UUID brut fonctionne aussi).
messageId est l’horodatage Signal du message auquel vous reagissez.
Les reactions de groupe necessitent 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=✅

Configuration :

channels.signal.actions.reactions : activer/desactiver les actions de reaction (par defaut true).
channels.signal.reactionLevel : off | ack | minimal | extensive.
- off/ack desactive les reactions de l’agent (l’outil message react retournera une erreur).
- minimal/extensive active les reactions de l’agent et definit le niveau d’orientation.
Surcharges par compte : channels.signal.accounts.<id>.actions.reactions, channels.signal.accounts.<id>.reactionLevel.

Cibles de livraison (CLI/cron)

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

Depannage

Executez cette echelle en premier :

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

Puis confirmez l’etat d’appairage DM si necessaire :

openclaw pairing list signal

Echecs courants :

Daemon accessible mais pas de reponses : verifiez les parametres compte/daemon (httpUrl, account) et le mode de reception.
DMs ignores : expediteur en attente d’approbation d’appairage.
Messages de groupe ignores : le filtrage expediteur/mention de groupe bloque la livraison.
Erreurs de validation de configuration apres modifications : executez openclaw doctor --fix.
Signal absent des diagnostics : confirmez channels.signal.enabled: true.

Verifications supplementaires :

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 securite

signal-cli stocke les cles de compte localement (generalement ~/.local/share/signal-cli/data/).
Sauvegardez l’etat du compte Signal avant la migration ou reconstruction du serveur.
Gardez channels.signal.dmPolicy: "pairing" sauf si vous voulez explicitement un acces DM plus large.
La verification SMS n’est necessaire que pour les flux d’inscription ou de recuperation, mais perdre le controle du numero/compte peut compliquer la re-inscription.

Reference de configuration (Signal)

Configuration complete : Configuration

Options du fournisseur :

channels.signal.enabled : activer/desactiver le demarrage du canal.
channels.signal.account : E.164 pour le compte bot.
channels.signal.cliPath : chemin vers signal-cli.
channels.signal.httpUrl : URL complete du daemon (surcharge host/port).
channels.signal.httpHost, channels.signal.httpPort : liaison du daemon (par defaut 127.0.0.1:8080).
channels.signal.autoStart : lancement automatique du daemon (par defaut true si httpUrl non defini).
channels.signal.startupTimeoutMs : delai d’attente de demarrage en ms (plafond 120000).
channels.signal.receiveMode : on-start | manual.
channels.signal.ignoreAttachments : ignorer les telechargements de pieces jointes.
channels.signal.ignoreStories : ignorer les stories du daemon.
channels.signal.sendReadReceipts : transmettre les accuses de lecture.
channels.signal.dmPolicy : pairing | allowlist | open | disabled (par defaut : pairing).
channels.signal.allowFrom : liste d’autorisation DM (E.164 ou uuid:<id>). open necessite "*". Signal n’a pas de noms d’utilisateur ; utilisez les IDs telephone/UUID.
channels.signal.groupPolicy : open | allowlist | disabled (par defaut : allowlist).
channels.signal.groupAllowFrom : liste d’autorisation d’expediteurs de groupe.
channels.signal.groups : surcharges par groupe indexees 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 : max de messages de groupe a inclure comme contexte (0 desactive).
channels.signal.dmHistoryLimit : limite d’historique DM en tours utilisateur. Surcharges par utilisateur : channels.signal.dms["<phone_or_uuid>"].historyLimit.
channels.signal.textChunkLimit : taille de decoupe sortante (caracteres).
channels.signal.chunkMode : length (par defaut) ou newline pour decouper sur les lignes vides (limites de paragraphe) avant la decoupe par longueur.
channels.signal.mediaMaxMb : limite de media entrant/sortant (Mo).

Options globales liees :

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