​

Signal (signal-cli)

​

Pré-requisitos

• OpenClaw instalado no seu servidor (o fluxo Linux abaixo foi testado no Ubuntu 24).
• signal-cli disponível no host onde o gateway é executado.
• Um número de telefone que possa receber um SMS de verificação (para o caminho de registro por SMS).
• Acesso via navegador para o captcha do Signal (signalcaptchas.org) durante o registro.

​

Configuração rápida (iniciante)

1. Use um número Signal separado para o bot (recomendado).
2. Instale signal-cli (Java é necessário se você usar a build JVM).
3. Escolha um caminho de configuração:
   • Caminho A (vinculação por QR): signal-cli link -n "OpenClaw" e escaneie com o Signal.
   • Caminho B (registro por SMS): registre um número dedicado com captcha + verificação por SMS.
4. Configure o OpenClaw e reinicie o gateway.
5. Envie a primeira DM e aprove o pareamento (openclaw pairing approve signal <CODE>).

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

​

O que é

• Canal Signal via signal-cli (não libsignal embutido).
• Roteamento determinístico: as respostas sempre voltam para o Signal.
• DMs compartilham a sessão principal do agente; grupos são isolados (agent:<agentId>:signal:group:<groupId>).

​

Escritas de configuração

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

​

O modelo de número (importante)

• O gateway se conecta a um dispositivo Signal (a conta do signal-cli).
• Se você executar o bot na sua conta pessoal do Signal, ele ignorará suas próprias mensagens (proteção contra loop).
• Para “eu mando mensagem para o bot e ele responde”, use um número de bot separado.

​

Caminho de configuração A: vincular conta Signal existente (QR)

1. Instale signal-cli (build JVM ou nativa).
2. Vincule uma conta de bot:
   • signal-cli link -n "OpenClaw" e depois escaneie o QR no Signal.
3. Configure o Signal e inicie o gateway.

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

​

Caminho de configuração B: registrar número de bot dedicado (SMS, Linux)

1. Obtenha um número que possa receber SMS (ou verificação por voz para linhas fixas).
   • Use um número de bot dedicado para evitar conflitos de conta/sessão.
2. Instale signal-cli no host do 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. Registre e verifique o número:

signal-cli -a +<BOT_PHONE_NUMBER> register

1. Abra https://signalcaptchas.org/registration/generate.html.
2. Conclua o captcha, copie o destino do link signalcaptcha://... em “Open Signal”.
3. Execute a partir do mesmo IP externo da sessão do navegador sempre que possível.
4. Execute o registro novamente imediatamente (tokens de captcha expiram rápido):

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

4. Configure o OpenClaw, reinicie o gateway e verifique o canal:

# Se você executa o gateway como um serviço systemd do usuário:
systemctl --user restart openclaw-gateway.service

# Em seguida, verifique:
openclaw doctor
openclaw channels status --probe

5. Faça o pareamento do remetente de DM:
   • Envie qualquer mensagem para o número do bot.
   • Aprove o código no servidor: openclaw pairing approve signal <PAIRING_CODE>.
   • Salve o número do bot como contato no seu telefone para evitar “Unknown contact”.

• README de signal-cli: https://github.com/AsamK/signal-cli
• Fluxo de captcha: https://github.com/AsamK/signal-cli/wiki/Registration-with-captcha
• Fluxo de vinculação: https://github.com/AsamK/signal-cli/wiki/Linking-other-devices-(Provisioning)

​

Modo de daemon externo (httpUrl)

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

​

Controle de acesso (DMs + grupos)

• Padrão: channels.signal.dmPolicy = "pairing".
• Remetentes desconhecidos recebem um código de pareamento; as mensagens são ignoradas até serem aprovadas (os códigos expiram após 1 hora).
• Aprove via:
  • openclaw pairing list signal
  • openclaw pairing approve signal <CODE>
• Pareamento é a troca de token padrão para DMs do Signal. Detalhes: Pairing
• Remetentes somente com UUID (de sourceUuid) são armazenados como uuid:<id> em channels.signal.allowFrom.

• channels.signal.groupPolicy = open | allowlist | disabled.
• channels.signal.groupAllowFrom controla quem pode acionar em grupos quando allowlist está definido.
• channels.signal.groups["<group-id>" | "*"] pode substituir o comportamento do grupo com requireMention, tools e toolsBySender.
• Use channels.signal.accounts.<id>.groups para substituições por conta em configurações com múltiplas contas.
• Observação de runtime: se channels.signal estiver completamente ausente, o runtime volta para groupPolicy="allowlist" nas verificações de grupo (mesmo que channels.defaults.groupPolicy esteja definido).

​

Como funciona (comportamento)

• signal-cli é executado como um daemon; o gateway lê eventos via SSE.
• Mensagens de entrada são normalizadas no envelope compartilhado de canais.
• As respostas sempre são roteadas de volta para o mesmo número ou grupo.

​

Mídia + limites

• O texto de saída é dividido em blocos por channels.signal.textChunkLimit (padrão 4000).
• Divisão opcional por nova linha: defina channels.signal.chunkMode="newline" para dividir em linhas em branco (limites de parágrafo) antes da divisão por comprimento.
• Anexos compatíveis (base64 buscado de signal-cli).
• Limite padrão de mídia: channels.signal.mediaMaxMb (padrão 8).
• Use channels.signal.ignoreAttachments para ignorar o download de mídia.
• O contexto de histórico de grupo usa channels.signal.historyLimit (ou channels.signal.accounts.*.historyLimit), com fallback para messages.groupChat.historyLimit. Defina 0 para desabilitar (padrão 50).

​

Digitação + confirmações de leitura

• Indicadores de digitação: o OpenClaw envia sinais de digitação via signal-cli sendTyping e os atualiza enquanto uma resposta está em andamento.
• Confirmações de leitura: quando channels.signal.sendReadReceipts é true, o OpenClaw encaminha confirmações de leitura para DMs permitidas.
• Signal-cli não expõe confirmações de leitura para grupos.

​

Reações (ferramenta de mensagem)

• Use message action=react com channel=signal.
• Alvos: remetente E.164 ou UUID (use uuid:<id> da saída de pareamento; UUID sem prefixo também funciona).
• messageId é o timestamp Signal da mensagem à qual você está reagindo.
• Reações em grupo exigem 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: habilita/desabilita ações de reação (padrão true).
• channels.signal.reactionLevel: off | ack | minimal | extensive.
  • off/ack desabilita reações do agente (a ferramenta de mensagem react retornará erro).
  • minimal/extensive habilita reações do agente e define o nível de orientação.
• Substituições por conta: channels.signal.accounts.<id>.actions.reactions, channels.signal.accounts.<id>.reactionLevel.

​

Alvos de entrega (CLI/cron)

• DMs: signal:+15551234567 (ou E.164 simples).
• DMs por UUID: uuid:<id> (ou UUID sem prefixo).
• Grupos: signal:group:<groupId>.
• Nomes de usuário: username:<name> (se compatível com a sua conta Signal).

​

Solução de problemas

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

openclaw pairing list signal

• Daemon acessível, mas sem respostas: verifique as configurações da conta/daemon (httpUrl, account) e o modo de recebimento.
• DMs ignoradas: o remetente está com aprovação de pareamento pendente.
• Mensagens de grupo ignoradas: o controle de remetente/menção do grupo bloqueia a entrega.
• Erros de validação de configuração após edições: execute openclaw doctor --fix.
• Signal ausente do diagnóstico: confirme 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

​

Observações de segurança

• signal-cli armazena chaves de conta localmente (normalmente em ~/.local/share/signal-cli/data/).
• Faça backup do estado da conta Signal antes de migrar ou reconstruir o servidor.
• Mantenha channels.signal.dmPolicy: "pairing" a menos que você queira explicitamente um acesso a DM mais amplo.
• A verificação por SMS só é necessária para fluxos de registro ou recuperação, mas perder o controle do número/conta pode complicar um novo registro.

​

Referência de configuração (Signal)

• channels.signal.enabled: habilitar/desabilitar a inicialização do canal.
• channels.signal.account: E.164 para a conta do bot.
• channels.signal.cliPath: caminho para signal-cli.
• channels.signal.httpUrl: URL completa do daemon (substitui host/porta).
• channels.signal.httpHost, channels.signal.httpPort: bind do daemon (padrão 127.0.0.1:8080).
• channels.signal.autoStart: inicialização automática do daemon (padrão true se httpUrl não estiver definido).
• channels.signal.startupTimeoutMs: tempo limite de espera da inicialização em ms (limite 120000).
• channels.signal.receiveMode: on-start | manual.
• channels.signal.ignoreAttachments: ignorar downloads de anexo.
• channels.signal.ignoreStories: ignorar stories do daemon.
• channels.signal.sendReadReceipts: encaminhar confirmações de leitura.
• channels.signal.dmPolicy: pairing | allowlist | open | disabled (padrão: pairing).
• channels.signal.allowFrom: allowlist de DM (E.164 ou uuid:<id>). open requer "*". O Signal não tem nomes de usuário; use ids de telefone/UUID.
• channels.signal.groupPolicy: open | allowlist | disabled (padrão: allowlist).
• channels.signal.groupAllowFrom: allowlist de remetentes de grupo.
• channels.signal.groups: substituições por grupo, indexadas pelo id do grupo Signal (ou "*"). Campos compatíveis: requireMention, tools, toolsBySender.
• channels.signal.accounts.<id>.groups: versão por conta de channels.signal.groups para configurações com múltiplas contas.
• channels.signal.historyLimit: máximo de mensagens de grupo a incluir como contexto (0 desabilita).
• channels.signal.dmHistoryLimit: limite de histórico de DM em turnos do usuário. Substituições por usuário: channels.signal.dms["<phone_or_uuid>"].historyLimit.
• channels.signal.textChunkLimit: tamanho do bloco de saída (caracteres).
• channels.signal.chunkMode: length (padrão) ou newline para dividir em linhas em branco (limites de parágrafo) antes da divisão por comprimento.
• channels.signal.mediaMaxMb: limite de mídia de entrada/saída (MB).

• agents.list[].groupChat.mentionPatterns (o Signal não oferece suporte a menções nativas).
• messages.groupChat.mentionPatterns (fallback global).
• messages.responsePrefix.

​

Relacionado

• Channels Overview — todos os canais compatíveis
• Pairing — autenticação de DM e fluxo de pareamento
• Groups — comportamento de chat em grupo e controle por menção
• Channel Routing — roteamento de sessão para mensagens
• Security — modelo de acesso e hardening