Signal (signal-cli)

Stato: integrazione CLI esterna. Il Gateway comunica con signal-cli tramite HTTP JSON-RPC + SSE.

Prerequisiti

  • OpenClaw installato sul tuo server (il flusso Linux di seguito e testato su Ubuntu 24).
  • signal-cli disponibile sull’host dove gira il gateway.
  • Un numero di telefono in grado di ricevere un SMS di verifica (per il percorso di registrazione SMS).
  • Accesso browser per il captcha Signal (signalcaptchas.org) durante la registrazione.

Setup rapido (principianti)

  1. Usa un numero Signal separato per il bot (consigliato).
  2. Installa signal-cli (Java necessario se usi la build JVM).
  3. Scegli un percorso di setup:
    • Percorso A (link QR): signal-cli link -n "OpenClaw" e scansiona con Signal.
    • Percorso B (registrazione SMS): registra un numero dedicato con captcha + verifica SMS.
  4. Configura OpenClaw e riavvia il gateway.
  5. Invia un primo DM e approva il pairing (openclaw pairing approve signal <CODE>).

Configurazione minimale:

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

Riferimento campi:

CampoDescrizione
accountNumero di telefono del bot in formato E.164 (+15551234567)
cliPathPercorso a signal-cli (signal-cli se nel PATH)
dmPolicyPolicy di accesso DM (pairing consigliato)
allowFromNumeri di telefono o valori uuid:<id> autorizzati ai DM

Cos’e

  • Canale Signal tramite signal-cli (non libsignal embedded).
  • Routing deterministico: le risposte tornano sempre a Signal.
  • I DM condividono la sessione principale dell’agent; i gruppi sono isolati (agent:<agentId>:signal:group:<groupId>).

Scritture configurazione

Per impostazione predefinita, Signal puo scrivere aggiornamenti di configurazione attivati da /config set|unset (richiede commands.config: true).

Disabilita con:

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

Il modello dei numeri (importante)

  • Il gateway si connette a un dispositivo Signal (l’account signal-cli).
  • Se usi il bot sul tuo account Signal personale, ignorera i tuoi stessi messaggi (protezione anti-loop).
  • Per “scrivo al bot e mi risponde”, usa un numero bot separato.

Percorso di setup A: collegare un account Signal esistente (QR)

  1. Installa signal-cli (build JVM o nativa).
  2. Collega un account bot:
    • signal-cli link -n "OpenClaw" poi scansiona il QR in Signal.
  3. Configura Signal e avvia il gateway.

Esempio:

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

Supporto multi-account: usa channels.signal.accounts con configurazione per account e name opzionale. Vedi gateway/configuration per il pattern condiviso.

Percorso di setup B: registrare un numero bot dedicato (SMS, Linux)

Usa questo percorso quando vuoi un numero bot dedicato invece di collegare un account Signal app esistente.

  1. Procurati un numero che puo ricevere SMS (o verifica vocale per numeri fissi).
    • Usa un numero bot dedicato per evitare conflitti di account/sessione.
  2. Installa signal-cli sull’host del 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

Se usi la build JVM (signal-cli-${VERSION}.tar.gz), installa prima JRE 25+. Mantieni signal-cli aggiornato; upstream segnala che release vecchie possono rompersi con i cambiamenti delle API server Signal.

  1. Registra e verifica il numero:
signal-cli -a +<BOT_PHONE_NUMBER> register

Se il captcha e richiesto:

  1. Apri https://signalcaptchas.org/registration/generate.html.
  2. Completa il captcha, copia il link target signalcaptcha://... da “Open Signal”.
  3. Esegui dallo stesso IP esterno della sessione browser quando possibile.
  4. Esegui la registrazione immediatamente (i token captcha scadono rapidamente):
signal-cli -a +<BOT_PHONE_NUMBER> register --captcha '<SIGNALCAPTCHA_URL>'
signal-cli -a +<BOT_PHONE_NUMBER> verify <VERIFICATION_CODE>
  1. Configura OpenClaw, riavvia il gateway, verifica il canale:
# Se usi il gateway come servizio systemd utente:
systemctl --user restart openclaw-gateway

# Poi verifica:
openclaw doctor
openclaw channels status --probe
  1. Associa il tuo mittente DM:
    • Invia qualsiasi messaggio al numero del bot.
    • Approva il codice sul server: openclaw pairing approve signal <PAIRING_CODE>.
    • Salva il numero del bot come contatto sul tuo telefono per evitare “Contatto sconosciuto”.

Importante: registrare un account numero di telefono con signal-cli puo de-autenticare la sessione principale dell’app Signal per quel numero. Preferisci un numero bot dedicato, o usa la modalita link QR se devi mantenere il tuo setup app telefono esistente.

Riferimenti upstream:

  • README signal-cli: https://github.com/AsamK/signal-cli
  • Flusso captcha: https://github.com/AsamK/signal-cli/wiki/Registration-with-captcha
  • Flusso di collegamento: https://github.com/AsamK/signal-cli/wiki/Linking-other-devices-(Provisioning)

Modalita daemon esterno (httpUrl)

Se vuoi gestire signal-cli autonomamente (avvii JVM lenti, init container o CPU condivise), esegui il daemon separatamente e punta OpenClaw su di esso:

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

Questo salta l’auto-spawn e l’attesa di avvio in OpenClaw. Per avvii lenti con auto-spawning, imposta channels.signal.startupTimeoutMs.

Controllo degli accessi (DM + gruppi)

DM:

  • Predefinito: channels.signal.dmPolicy = "pairing".
  • I mittenti sconosciuti ricevono un codice di pairing; i messaggi sono ignorati fino all’approvazione (i codici scadono dopo 1 ora).
  • Approvazione tramite:
    • openclaw pairing list signal
    • openclaw pairing approve signal <CODE>
  • Il pairing e lo scambio token predefinito per i DM Signal. Dettagli: Pairing
  • I mittenti solo UUID (da sourceUuid) sono salvati come uuid:<id> in channels.signal.allowFrom.

Gruppi:

  • channels.signal.groupPolicy = open | allowlist | disabled.
  • channels.signal.groupAllowFrom controlla chi puo attivare il bot nei gruppi quando allowlist e impostato.
  • channels.signal.groups["<group-id>" | "*"] puo sovrascrivere il comportamento del gruppo con requireMention, tools e toolsBySender.
  • Usa channels.signal.accounts.<id>.groups per sovrascritture per account in configurazioni multi-account.
  • Nota runtime: se channels.signal e completamente assente, il runtime torna a groupPolicy="allowlist" per i controlli di gruppo (anche se channels.defaults.groupPolicy e impostato).

Come funziona (comportamento)

  • signal-cli gira come daemon; il gateway legge gli eventi via SSE.
  • I messaggi in ingresso sono normalizzati nell’envelope condiviso del canale.
  • Le risposte tornano sempre allo stesso numero o gruppo.

Media + limiti

  • Il testo in uscita e segmentato a channels.signal.textChunkLimit (predefinito 4000).
  • Segmentazione opzionale per newline: imposta channels.signal.chunkMode="newline" per dividere sulle righe vuote (confini di paragrafo) prima della segmentazione per lunghezza.
  • Allegati supportati (base64 recuperati da signal-cli).
  • Limite media predefinito: channels.signal.mediaMaxMb (predefinito 8).
  • Usa channels.signal.ignoreAttachments per saltare il download dei media.
  • Il contesto storico di gruppo usa channels.signal.historyLimit (o channels.signal.accounts.*.historyLimit), con fallback su messages.groupChat.historyLimit. Imposta 0 per disabilitare (predefinito 50).

Digitazione + conferme di lettura

  • Indicatori di digitazione: OpenClaw invia segnali di digitazione tramite signal-cli sendTyping e li aggiorna mentre una risposta e in corso.
  • Conferme di lettura: quando channels.signal.sendReadReceipts e true, OpenClaw inoltra le conferme di lettura per i DM consentiti.
  • Signal-cli non espone le conferme di lettura per i gruppi.

Reazioni (strumento message)

  • Usa message action=react con channel=signal.
  • Target: E.164 o UUID del mittente (usa uuid:<id> dall’output del pairing; UUID semplice funziona comunque).
  • messageId e il timestamp Signal per il messaggio a cui stai reagendo.
  • Le reazioni nei gruppi richiedono targetAuthor o targetAuthorUuid.

Esempi:

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

Configurazione:

  • channels.signal.actions.reactions: abilita/disabilita le azioni di reazione (predefinito true).
  • channels.signal.reactionLevel: off | ack | minimal | extensive.
    • off/ack disabilita le reazioni dell’agent (lo strumento message react restituira errore).
    • minimal/extensive abilita le reazioni dell’agent e imposta il livello di guida.
  • Sovrascritture per account: channels.signal.accounts.<id>.actions.reactions, channels.signal.accounts.<id>.reactionLevel.

Target di consegna (CLI/cron)

  • DM: signal:+15551234567 (o semplice E.164).
  • DM UUID: uuid:<id> (o UUID semplice).
  • Gruppi: signal:group:<groupId>.
  • Username: username:<name> (se supportato dal tuo account Signal).

Risoluzione problemi

Esegui questa scaletta prima:

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

Poi conferma lo stato del pairing DM se necessario:

openclaw pairing list signal

Problemi comuni:

  • Daemon raggiungibile ma nessuna risposta: verifica le impostazioni account/daemon (httpUrl, account) e la modalita di ricezione.
  • DM ignorati: il mittente e in attesa di approvazione pairing.
  • Messaggi di gruppo ignorati: il gating mittente/menzione del gruppo blocca la consegna.
  • Errori di validazione config dopo modifiche: esegui openclaw doctor --fix.
  • Signal assente dalla diagnostica: conferma channels.signal.enabled: true.

Controlli aggiuntivi:

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

Per il flusso di triage: /channels/troubleshooting.

Note di sicurezza

  • signal-cli salva le chiavi dell’account localmente (tipicamente ~/.local/share/signal-cli/data/).
  • Fai un backup dello stato dell’account Signal prima di migrare o ricostruire il server.
  • Mantieni channels.signal.dmPolicy: "pairing" a meno che tu non voglia esplicitamente un accesso DM piu ampio.
  • La verifica SMS e necessaria solo per i flussi di registrazione o recupero, ma perdere il controllo del numero/account puo complicare la ri-registrazione.

Riferimento configurazione (Signal)

Configurazione completa: Configurazione

Opzioni del provider:

  • channels.signal.enabled: abilita/disabilita l’avvio del canale.
  • channels.signal.account: E.164 per l’account bot.
  • channels.signal.cliPath: percorso a signal-cli.
  • channels.signal.httpUrl: URL completo del daemon (sovrascrive host/port).
  • channels.signal.httpHost, channels.signal.httpPort: bind del daemon (predefinito 127.0.0.1:8080).
  • channels.signal.autoStart: auto-spawn del daemon (predefinito true se httpUrl non impostato).
  • channels.signal.startupTimeoutMs: timeout di attesa avvio in ms (limite 120000).
  • channels.signal.receiveMode: on-start | manual.
  • channels.signal.ignoreAttachments: salta il download degli allegati.
  • channels.signal.ignoreStories: ignora le storie dal daemon.
  • channels.signal.sendReadReceipts: inoltra le conferme di lettura.
  • channels.signal.dmPolicy: pairing | allowlist | open | disabled (predefinito: pairing).
  • channels.signal.allowFrom: allowlist DM (E.164 o uuid:<id>). open richiede "*". Signal non ha username; usa ID telefono/UUID.
  • channels.signal.groupPolicy: open | allowlist | disabled (predefinito: allowlist).
  • channels.signal.groupAllowFrom: allowlist mittenti gruppi.
  • channels.signal.groups: sovrascritture per gruppo con chiave ID gruppo Signal (o "*"). Campi supportati: requireMention, tools, toolsBySender.
  • channels.signal.accounts.<id>.groups: versione per account di channels.signal.groups per configurazioni multi-account.
  • channels.signal.historyLimit: massimo messaggi di gruppo da includere come contesto (0 disabilita).
  • channels.signal.dmHistoryLimit: limite storico DM in turni utente. Sovrascritture per utente: channels.signal.dms["<phone_or_uuid>"].historyLimit.
  • channels.signal.textChunkLimit: dimensione segmento in uscita (caratteri).
  • channels.signal.chunkMode: length (predefinito) o newline per dividere sulle righe vuote (confini di paragrafo) prima della segmentazione per lunghezza.
  • channels.signal.mediaMaxMb: limite media in ingresso/uscita (MB).

Opzioni globali correlate:

  • agents.list[].groupChat.mentionPatterns (Signal non supporta menzioni native).
  • messages.groupChat.mentionPatterns (fallback globale).
  • messages.responsePrefix.
arrow_back
Precedente
Nostr
Successivo
Synology Chat
arrow_forward