Signal

​

Il modello dei numeri (leggere prima questa sezione)

• Il Gateway si connette a un dispositivo Signal: l’account signal-cli.
• L’esecuzione del bot sul proprio account Signal personale fa sì che ignori i propri messaggi (protezione dai loop).
• Per ottenere il comportamento «invio un messaggio al bot e questo risponde», utilizzare un numero separato per il bot.

​

Installazione

openclaw plugins install @openclaw/signal

​

Configurazione rapida

openclaw plugins install @openclaw/signal

openclaw channels add

openclaw gateway call channels.status --params '{"probe":true}'

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

​

Funzionamento

• Instradamento deterministico: le risposte vengono sempre rinviate a Signal.
• I messaggi diretti condividono la sessione principale dell’agente; i gruppi sono isolati (agent:<agentId>:signal:group:<groupId>).
• Per impostazione predefinita, Signal può scrivere gli aggiornamenti della configurazione attivati da /config set|unset (richiede commands.config: true). Disabilitare questa funzione con channels.signal.configWrites: false.

​

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

1. Installare signal-cli (build JVM o nativa) oppure consentire a openclaw channels add di installarlo.
2. Collegare un account del bot: signal-cli link -n "OpenClaw", quindi eseguire la scansione del codice QR in Signal.
3. Configurare Signal e avviare il Gateway.

​

Percorso di configurazione B: registrare un numero dedicato per il bot (SMS, Linux)

1. Procurarsi un numero in grado di ricevere SMS (o la verifica vocale per i numeri di rete fissa). Un numero dedicato al bot evita conflitti tra account o sessioni.
2. Installare 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

3. Registrare e verificare il numero:

signal-cli -a +<BOT_PHONE_NUMBER> register

1. Aprire https://signalcaptchas.org/registration/generate.html.
2. Completare il captcha e copiare la destinazione del collegamento signalcaptcha://... da “Open Signal”.
3. Se possibile, eseguire l’operazione dallo stesso indirizzo IP esterno della sessione del browser (i token captcha scadono rapidamente).
4. Registrare e verificare immediatamente:

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

4. Configurare OpenClaw, riavviare il Gateway e verificare il canale:

# Se il gateway viene eseguito come servizio systemd dell'utente:
systemctl --user restart openclaw-gateway.service

# Quindi verificare:
openclaw doctor
openclaw channels status --probe

5. Associare il mittente dei messaggi diretti:
   • Inviare un messaggio qualsiasi al numero del bot.
   • Approvare sul server: openclaw pairing approve signal <PAIRING_CODE>.
   • Salvare il numero del bot come contatto sul telefono per evitare “Unknown contact”.

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

​

Modalità daemon esterno (httpUrl)

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

​

Modalità container (bbernhard/signal-cli-rest-api)

• Il container deve essere eseguito con MODE=json-rpc per ricevere i messaggi in tempo reale.
• Registrare o collegare l’account Signal all’interno del container prima di connettere 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", // oppure "auto" per il rilevamento automatico
    },
  },
}

• Utilizzare autoStart: false con la modalità container; OpenClaw non deve avviare un daemon nativo quando è selezionato apiMode: "container".
• Utilizzare MODE=json-rpc per la ricezione. MODE=normal può far apparire /v1/about operativo, ma /v1/receive/{account} non eseguirà l’upgrade a WebSocket, pertanto OpenClaw non selezionerà lo streaming di ricezione del container in modalità auto.
• Impostare apiMode: "container" quando httpUrl punta all’API REST bbernhard, "native" quando punta a JSON-RPC/SSE nativo di signal-cli e "auto" quando la distribuzione può variare.
• I download degli allegati in modalità container rispettano gli stessi limiti di byte per i contenuti multimediali della modalità nativa. Le risposte sovradimensionate vengono rifiutate prima di essere memorizzate completamente nel buffer quando il server invia Content-Length, altrimenti durante lo streaming.

​

Controllo degli accessi (messaggi diretti + gruppi)

• Valore predefinito: channels.signal.dmPolicy = "pairing".
• I mittenti sconosciuti ricevono un codice di associazione; i messaggi vengono ignorati finché l’associazione non viene approvata (i codici scadono dopo 1 ora).
• Approvare tramite openclaw pairing list signal e openclaw pairing approve signal <CODE>.
• L’associazione è lo scambio di token predefinito per i messaggi diretti di Signal. Dettagli: Associazione
• I mittenti identificati solo tramite UUID (da sourceUuid) vengono memorizzati come uuid:<id> in channels.signal.allowFrom.

• channels.signal.groupPolicy = open | allowlist | disabled.
• channels.signal.groupAllowFrom determina quali gruppi o mittenti possono attivare le risposte nei gruppi quando è impostato allowlist; le voci possono essere ID gruppo Signal (non elaborati, group:<id> o signal:group:<id>), numeri di telefono dei mittenti, valori uuid:<id> oppure *.
• channels.signal.groups["<group-id>" | "*"] può ignorare il comportamento dei gruppi mediante requireMention, tools e toolsBySender.
• Utilizzare channels.signal.accounts.<id>.groups per le sostituzioni specifiche di ciascun account nelle configurazioni multi-account.
• L’inserimento di un gruppo Signal nell’elenco consentito tramite groupAllowFrom non disabilita automaticamente il requisito delle menzioni. Una voce channels.signal.groups["<group-id>"] configurata in modo specifico elabora ogni messaggio del gruppo, a meno che non sia impostato requireMention=true.
• Con requireMention=true, le @menzioni native di Signal vengono confrontate, tramite i metadati strutturati delle menzioni, con il numero di telefono o accountUuid dell’account del bot. I valori mentionPatterns configurati rimangono un metodo alternativo basato su testo normale.
• Nota sull’esecuzione: se channels.signal è completamente assente, durante l’esecuzione viene usato groupPolicy="allowlist" come alternativa per i controlli dei gruppi (anche se è impostato channels.defaults.groupPolicy).

{
  channels: {
    signal: {
      account: "+15551234567",
      accountUuid: "bot-signal-uuid",
      groupPolicy: "allowlist",
      groupAllowFrom: ["group:<signal-group-id>"],
      historyLimit: 8,
      groups: {
        "<signal-group-id>": { requireMention: true },
      },
    },
  },
  messages: {
    groupChat: {
      mentionPatterns: ["\\bopenclaw\\b"],
    },
  },
}

​

Funzionamento (comportamento)

• Modalità nativa: signal-cli viene eseguito come daemon; il Gateway legge gli eventi tramite SSE.
• Modalità container: il Gateway invia tramite API REST e riceve tramite WebSocket.
• I messaggi in entrata vengono normalizzati nell’envelope condiviso del canale.
• Le risposte vengono sempre instradate allo stesso numero o gruppo.
• Le risposte ai messaggi in entrata includono i metadati di citazione nativi di Signal quando il backend accetta il timestamp e l’autore del messaggio in entrata; se i metadati di citazione sono assenti o vengono rifiutati, OpenClaw invia la risposta come messaggio normale.
• Configurare l’uso delle citazioni native con channels.signal.replyToMode = off | first | all | batched oppure con channels.signal.replyToModeByChatType.direct/group per le sostituzioni specifiche per tipo di chat. I valori a livello di account in channels.signal.accounts.<id> hanno la precedenza.

​

Contenuti multimediali + limiti

• Il testo in uscita viene suddiviso in blocchi secondo channels.signal.textChunkLimit (valore predefinito 4000).
• Suddivisione facoltativa in corrispondenza delle nuove righe: impostare channels.signal.streaming.chunkMode="newline" per suddividere in corrispondenza delle righe vuote (limiti dei paragrafi) prima della suddivisione per lunghezza.
• Gli allegati sono supportati (base64 recuperato da signal-cli).
• Gli allegati delle note vocali usano il nome file signal-cli come ripiego MIME quando contentType è assente, affinché la trascrizione audio possa comunque classificare i memo vocali AAC.
• Limite predefinito per i contenuti multimediali: channels.signal.mediaMaxMb (valore predefinito 8).
• Usare channels.signal.ignoreAttachments per ignorare il download dei contenuti multimediali.
• Il contesto della cronologia dei gruppi usa channels.signal.historyLimit (o channels.signal.accounts.*.historyLimit), con ripiego su messages.groupChat.historyLimit. Impostare 0 per disabilitarlo (valore predefinito 50).

​

Indicatori di digitazione + conferme di lettura

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

​

Reazioni allo stato del ciclo di vita

​

Reazioni (strumento messaggi)

• Destinazioni: E.164 o UUID del mittente (usare uuid:<id> dall’output dell’associazione; funziona anche un UUID senza prefisso).
• messageId è il timestamp Signal del messaggio a cui si reagisce.
• Le reazioni di gruppo richiedono targetAuthor o 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: abilita/disabilita le azioni di reazione (valore predefinito true).
• channels.signal.reactionLevel: off | ack | minimal | extensive (valore predefinito minimal).
  • off/ack disabilita le reazioni dell’agente (lo strumento messaggi react restituisce errori).
  • minimal/extensive abilita le reazioni dell’agente e imposta il livello di indicazioni.
• Sostituzioni per account: channels.signal.accounts.<id>.actions.reactions, channels.signal.accounts.<id>.reactionLevel.

​

Reazioni di approvazione

• 👍 approva una volta.
• 👎 rifiuta.
• Usare /approve <id> allow-always quando una richiesta offre un’approvazione persistente.

​

Destinazioni di consegna (CLI/Cron)

• Messaggi diretti: signal:+15551234567 (o E.164 semplice).
• Messaggi diretti tramite UUID: uuid:<id> (o UUID senza prefisso).
• Gruppi: signal:group:<groupId>.
• Nomi utente: username:<name> (se supportati dall’account Signal).

​

Alias

{
  channels: {
    signal: {
      aliases: {
        me: "+15557654321",
        jane: "uuid:123e4567-e89b-12d3-a456-426614174000",
        ops: "group:<groupId>",
      },
      defaultTo: "signal:me",
    },
  },
}

openclaw message send --channel signal --target signal:ops --message "Deployment is complete"

{
  channels: {
    signal: {
      aliases: {
        me: "+15557654321",
      },
      accounts: {
        work: {
          aliases: {
            ops: "group:<workGroupId>",
          },
        },
      },
    },
  },
}

​

Risoluzione dei problemi

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

openclaw pairing list signal

• Daemon raggiungibile ma nessuna risposta: verificare le impostazioni dell’account/daemon (httpUrl, account) e la modalità di ricezione.
• Messaggi diretti ignorati: il mittente è in attesa dell’approvazione dell’associazione.
• Messaggi di gruppo ignorati: i criteri di accesso per mittente/menzione del gruppo bloccano la consegna.
• Errori di convalida della configurazione dopo le modifiche: eseguire openclaw doctor --fix.
• Signal assente dalla diagnostica: verificare 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

​

Note sulla sicurezza

• signal-cli archivia localmente le chiavi dell’account (in genere ~/.local/share/signal-cli/data/).
• Eseguire il backup dello stato dell’account Signal prima di migrare o ricostruire il server.
• Mantenere channels.signal.dmPolicy: "pairing", a meno che non si desideri esplicitamente un accesso più ampio ai messaggi diretti.
• La verifica tramite SMS è necessaria solo per i flussi di registrazione o ripristino, ma la perdita del controllo del numero/account può complicare una nuova registrazione.

​

Riferimento della configurazione (Signal)

• channels.signal.enabled: abilita/disabilita l’avvio del canale.
• channels.signal.apiMode: auto | native | container (valore predefinito: auto). Consultare Modalità container.
• channels.signal.account: E.164 per l’account del bot.
• channels.signal.accountUuid: UUID facoltativo dell’account del bot per il rilevamento delle @menzioni native e la protezione dai cicli.
• channels.signal.cliPath: percorso di signal-cli.
• channels.signal.configPath: directory signal-cli --config facoltativa.
• channels.signal.httpUrl: URL completo del daemon (sostituisce host/porta).
• channels.signal.httpHost, channels.signal.httpPort: binding del daemon (valore predefinito 127.0.0.1:8080).
• channels.signal.autoStart: avvio automatico del daemon (valore predefinito true se httpUrl non è impostato).
• channels.signal.startupTimeoutMs: timeout di attesa dell’avvio in ms (min 1000, limite 120000; valore predefinito 30000).
• channels.signal.receiveMode: on-start | manual.
• channels.signal.ignoreAttachments: ignora i download degli allegati.
• channels.signal.ignoreStories: ignora le storie provenienti dal daemon.
• channels.signal.sendReadReceipts: inoltra le conferme di lettura.
• channels.signal.dmPolicy: pairing | allowlist | open | disabled (valore predefinito: associazione).
• channels.signal.allowFrom: elenco consentito per i messaggi diretti (E.164 o uuid:<id>). open richiede "*". Signal non dispone di nomi utente; usare ID telefonici/UUID.
• channels.signal.aliases: alias lato OpenClaw per le destinazioni di consegna di messaggi diretti o di gruppo.
• channels.signal.groupPolicy: open | allowlist | disabled (valore predefinito: elenco consentito).
• channels.signal.groupAllowFrom: elenco consentito per i gruppi; accetta ID di gruppo Signal (non elaborati, group:<id> o signal:group:<id>), numeri E.164 dei mittenti o valori uuid:<id>.
• channels.signal.groups: sostituzioni per gruppo indicizzate in base all’ID del gruppo Signal (o "*"). Campi supportati: requireMention, tools, toolsBySender.
• channels.signal.accounts.<id>.groups: versione per account di channels.signal.groups per configurazioni con più account.
• channels.signal.accounts.<id>.aliases: alias per account, uniti agli alias di primo livello.
• channels.signal.replyToMode: modalità di citazione nativa delle risposte, off | first | all | batched (valore predefinito: all).
• channels.signal.replyToModeByChatType.direct, channels.signal.replyToModeByChatType.group: sostituzioni della citazione nativa delle risposte per tipo di chat.
• channels.signal.accounts.<id>.replyToMode, channels.signal.accounts.<id>.replyToModeByChatType.direct, channels.signal.accounts.<id>.replyToModeByChatType.group: sostituzioni della citazione delle risposte per account.
• channels.signal.historyLimit: numero massimo di messaggi di gruppo da includere come contesto (0 disabilita).
• channels.signal.dmHistoryLimit: limite della cronologia dei messaggi diretti espresso in turni utente. Sostituzioni per utente: channels.signal.dms["<phone_or_uuid>"].historyLimit.
• channels.signal.textChunkLimit: dimensione dei blocchi in uscita espressa in caratteri (valore predefinito 4000).
• channels.signal.streaming.chunkMode: length (valore predefinito) o newline per suddividere in corrispondenza delle righe vuote (limiti dei paragrafi) prima della suddivisione per lunghezza.
• channels.signal.mediaMaxMb: limite dei contenuti multimediali in entrata/uscita in MB (valore predefinito 8).
• channels.signal.reactionLevel: off | ack | minimal | extensive (valore predefinito minimal). Consultare Reazioni.
• channels.signal.reactionNotifications: off | own | all | allowlist (valore predefinito own) - quando l’agente riceve notifiche delle reazioni in entrata di altri utenti.
• channels.signal.reactionAllowlist: mittenti le cui reazioni notificano l’agente quando reactionNotifications: "allowlist".
• channels.signal.streaming.block.enabled, channels.signal.streaming.block.coalesce: controlli dello streaming in modalità a blocchi condivisi tra i canali. Consultare Streaming.

• agents.list[].groupChat.mentionPatterns (fallback in testo normale; le @menzioni native di Signal vengono rilevate dai metadati strutturati quando è configurata l’identità dell’account del bot).
• messages.groupChat.mentionPatterns (fallback globale).
• messages.responsePrefix.

​

Argomenti correlati

• Panoramica dei canali - tutti i canali supportati
• Associazione - autenticazione tramite messaggio diretto e flusso di associazione
• Gruppi - comportamento delle chat di gruppo e controllo tramite menzioni
• Instradamento dei canali - instradamento delle sessioni per i messaggi
• Sicurezza - modello di accesso e rafforzamento della sicurezza