Pular para o conteúdo principal

Documentação oficial desta página · v0.20.6

Configuração do Signal

O Hermes se conecta ao Signal pelo daemon signal-cli rodando em modo HTTP. O adaptador recebe mensagens em tempo real por SSE (Server-Sent Events) e envia respostas por JSON-RPC.

O Signal é o mensageiro popular mais focado em privacidade — criptografia de ponta a ponta por padrão, protocolo de código aberto, coleta mínima de metadados. Isso o torna ideal para fluxos de agente sensíveis à segurança.

Nenhuma dependência Python nova

O adaptador do Signal usa httpx (que já é dependência central do Hermes) para toda a comunicação. Nenhum pacote Python adicional é necessário. Você só precisa do signal-cli instalado por fora.

Pré-requisitos​

  • signal-cli — cliente Signal em Java (GitHub)
  • Java 17+ — exigido pelo signal-cli
  • Um número de telefone com Signal instalado (para vincular como dispositivo secundário)

Instalar o signal-cli​

# macOS
brew install signal-cli

# Linux (baixe a versão mais recente)
VERSION=$(curl -Ls -o /dev/null -w %{url_effective} \
  https://github.com/AsamK/signal-cli/releases/latest | sed 's/^.*\/v//')
curl -L -O "https://github.com/AsamK/signal-cli/releases/download/v${VERSION}/signal-cli-${VERSION}.tar.gz"
sudo tar xf "signal-cli-${VERSION}.tar.gz" -C /opt
sudo ln -sf "/opt/signal-cli-${VERSION}/bin/signal-cli" /usr/local/bin/
cuidado

O signal-cli não está nos repositórios do apt nem do snap. A instalação Linux acima baixa direto das releases no GitHub.

O signal-cli funciona como dispositivo vinculado — igual ao WhatsApp Web, mas para o Signal. Seu celular continua sendo o dispositivo principal.

# Gera uma URI de vínculo (mostra um QR code ou um link)
signal-cli link -n "HermesAgent"
  1. Abra o Signal no celular
  2. Vá em Ajustes → Dispositivos vinculados
  3. Toque em Vincular novo dispositivo
  4. Escaneie o QR code ou digite a URI

Passo 2: suba o daemon do signal-cli​

# Troque +1234567890 pelo seu número no Signal (formato E.164)
signal-cli --account +1234567890 daemon --http 127.0.0.1:8080
dica

Deixe isso rodando em segundo plano. Você pode usar systemd, tmux, screen ou rodar como serviço.

Confirme que está no ar:

curl http://127.0.0.1:8080/api/v1/check
# Deve responder: {"versions":{"signal-cli":...}}

Passo 3: configure o Hermes​

O jeito mais fácil:

hermes gateway setup

Escolha Signal no menu de plataformas. O assistente vai:

  1. Checar se o signal-cli está instalado
  2. Perguntar a URL HTTP (padrão: http://127.0.0.1:8080)
  3. Testar a conexão com o daemon
  4. Pedir o número de telefone da sua conta
  5. Configurar usuários permitidos e políticas de acesso

Configuração manual​

Acrescente ao ~/.hermes/.env:

# Obrigatório
SIGNAL_HTTP_URL=http://127.0.0.1:8080
SIGNAL_ACCOUNT=+1234567890

# Segurança (recomendado)
SIGNAL_ALLOWED_USERS=+1234567890,+0987654321    # Números E.164 ou UUIDs, separados por vírgula

# Opcional
SIGNAL_GROUP_ALLOWED_USERS=groupId1,groupId2     # Habilita grupos (omita para desabilitar, * para todos)
SIGNAL_HOME_CHANNEL=+1234567890                  # Destino padrão de entrega das tarefas de cron

Depois suba o gateway:

hermes gateway              # Em primeiro plano
hermes gateway install      # Instala como serviço de usuário
sudo hermes gateway install --system   # Só no Linux: serviço de sistema, no boot

Controle de acesso​

Acesso por DM​

O acesso por DM segue o mesmo padrão de todas as outras plataformas do Hermes:

  1. SIGNAL_ALLOWED_USERS definida → só esses usuários podem mandar mensagem
  2. Sem lista de permissão → usuários desconhecidos recebem um código de pareamento por DM (aprove com hermes pairing approve signal CODE)
  3. SIGNAL_ALLOW_ALL_USERS=true → qualquer um pode mandar mensagem (use com cuidado)

Acesso em grupos​

O acesso a grupos é controlado pela variável de ambiente SIGNAL_GROUP_ALLOWED_USERS:

ConfiguraçãoComportamento
Não definida (padrão)Todas as mensagens de grupo são ignoradas. O bot só responde em DMs.
Definida com IDs de grupoSó os grupos listados são monitorados (por exemplo, groupId1,groupId2).
Definida como *O bot responde em qualquer grupo do qual seja membro.

Recursos​

Anexos​

O adaptador suporta enviar e receber mídia nos dois sentidos.

Recebidos (usuário → agente):

  • Imagens — PNG, JPEG, GIF, WebP (detectados automaticamente pelos magic bytes)
  • Áudio — MP3, OGG, WAV, M4A (mensagens de voz transcritas se o Whisper estiver configurado)
  • Documentos — PDF, ZIP e outros tipos de arquivo

Enviados (agente → usuário):

O agente pode mandar arquivos de mídia com tags MEDIA: nas respostas. Os seguintes métodos de entrega são suportados:

  • Imagens — send_multiple_images e send_image_file enviam PNG, JPEG, GIF e WebP como anexos nativos do Signal
  • Voz — send_voice envia arquivos de áudio (OGG, MP3, WAV, M4A, AAC) como anexos
  • Vídeo — send_video envia arquivos MP4
  • Documentos — send_document envia qualquer tipo de arquivo (PDF, ZIP etc.)

Toda mídia enviada passa pela API padrão de anexos do Signal. Diferente de algumas plataformas, o Signal não distingue mensagem de voz de anexo de arquivo no nível do protocolo.

Limite de tamanho de anexo: 100 MB (nos dois sentidos).

aviso

Os servidores do Signal limitam a taxa de upload de anexos. O adaptador usa um escalonador para envio de várias imagens que agrupa as imagens em lotes de 32 e segura os uploads para respeitar a política do servidor do Signal.

Formatação nativa, citações de resposta e reações​

As mensagens do Signal aparecem com formatação nativa em vez de caracteres literais de markdown. O adaptador converte markdown (**negrito**, *itálico*, `código`, ~~riscado~~, ||spoiler||, títulos) em bodyRanges do Signal, então o texto chega estilizado de verdade no cliente de quem recebe, e não com ** / ` visíveis.

Citações de resposta. Quando o Hermes responde a uma mensagem específica, ele publica uma resposta nativa citando a original — o mesmo recurso de interface que os usuários do Signal veem quando usam "Responder". Isso é automático para respostas geradas a partir de uma mensagem recebida.

Reações. O agente pode reagir a mensagens pela API padrão de reações; as reações aparecem no Signal como emojis na mensagem referenciada, e não como texto extra.

Nada disso precisa de configuração adicional — vem ligado por padrão nas versões recentes do signal-cli. Se a sua versão do signal-cli for antiga demais, o Hermes cai para entrega em texto puro e registra um aviso uma única vez.

Mensagens longas​

O Signal limita uma única mensagem a 8.000 caracteres. O Hermes divide respostas maiores em pedaços numerados ((1/3), (2/3), …) automaticamente, em vez de cortá-las. Isso vale para todo caminho de entrega — respostas em conversa ao vivo, entregas de tarefas de cron, hermes send e chamadas send_message via MCP — e a formatação nativa (negrito, itálico, código, spoilers) é preservada entre os pedaços.

Indicadores de digitação​

O bot envia indicadores de digitação enquanto processa mensagens, renovando a cada 8 segundos.

Exibição de progresso das ferramentas​

O Signal não permite editar mensagens já enviadas. Por isso o Hermes suprime os balões de progresso de ferramenta do gateway no Signal, mesmo com /verbose ligado e mesmo salvando um modo diferente de off para a plataforma.

Você ainda vê a atividade das ferramentas na CLI, e as respostas finais no Signal podem trazer a saída normal do assistente. Se você precisa de progresso ao vivo por ferramenta na conversa, use uma plataforma de mensagens que suporte edição de mensagens.

Ocultação de números de telefone​

Todos os números de telefone são ocultados automaticamente nos logs:

  • +15551234567 → +155****4567
  • Isso vale tanto para os logs do gateway do Hermes quanto para o sistema global de ocultação

Mensagem para si (configuração com um número só)​

Se você roda o signal-cli como dispositivo secundário vinculado ao seu próprio número (em vez de um número separado para o bot), dá para conversar com o Hermes pelo recurso "Mensagem para si" do Signal.

Basta mandar uma mensagem para você mesmo pelo celular — o signal-cli capta e o Hermes responde na mesma conversa.

Como funciona:

  • As mensagens de "Mensagem para si" chegam como envelopes syncMessage.sentMessage
  • O adaptador detecta quando elas são endereçadas à própria conta do bot e as processa como mensagens recebidas normais
  • A proteção contra eco (rastreamento de timestamp de envio) evita laços infinitos — as próprias respostas do bot são filtradas automaticamente

Nenhuma configuração extra é necessária. Isso funciona sozinho, desde que SIGNAL_ACCOUNT seja o seu número de telefone.

Monitoramento de saúde​

O adaptador monitora a conexão SSE e reconecta automaticamente se:

  • A conexão cair (com recuo exponencial: 2s → 60s)
  • Nenhuma atividade for detectada por 120 segundos (ele dá um ping no signal-cli para conferir)

Solução de problemas​

ProblemaSolução
"Cannot reach signal-cli" durante a configuraçãoGaranta que o daemon do signal-cli está rodando: signal-cli --account +YOUR_NUMBER daemon --http 127.0.0.1:8080
Mensagens não chegamConfira se SIGNAL_ALLOWED_USERS inclui o número de quem envia, no formato E.164 (com o prefixo +)
"signal-cli not found on PATH"Instale o signal-cli e garanta que ele está no seu PATH, ou use Docker
A conexão cai o tempo todoProcure erros nos logs do signal-cli. Confirme que o Java 17+ está instalado.
Mensagens de grupo ignoradasConfigure SIGNAL_GROUP_ALLOWED_USERS com IDs de grupo específicos, ou * para liberar todos os grupos.
O bot não responde a ninguémConfigure SIGNAL_ALLOWED_USERS, use pareamento por DM ou libere todos os usuários explicitamente pela política do gateway, se quiser um acesso mais amplo.
Mensagens duplicadasGaranta que só uma instância do signal-cli está escutando no seu número

Segurança​

aviso

Configure o controle de acesso sempre. O bot tem acesso ao terminal por padrão. Sem SIGNAL_ALLOWED_USERS ou pareamento por DM, o gateway nega todas as mensagens recebidas por precaução.

  • Números de telefone são ocultados em toda a saída de log
  • Use pareamento por DM ou listas de permissão explícitas para receber novos usuários com segurança
  • Mantenha os grupos desabilitados a menos que você precise mesmo de suporte a grupos, ou libere só os grupos em que confia
  • A criptografia de ponta a ponta do Signal protege o conteúdo das mensagens em trânsito
  • Os dados de sessão do signal-cli em ~/.local/share/signal-cli/ contêm credenciais da conta — proteja como se fossem uma senha

Referência de variáveis de ambiente​

VariávelObrigatóriaPadrãoDescrição
SIGNAL_HTTP_URLSim—Endpoint HTTP do signal-cli
SIGNAL_ACCOUNTSim—Número de telefone do bot (E.164)
SIGNAL_ALLOWED_USERSNão—Números/UUIDs separados por vírgula
SIGNAL_GROUP_ALLOWED_USERSNão—IDs de grupo a monitorar, ou * para todos (omita para desabilitar grupos)
SIGNAL_ALLOW_ALL_USERSNãofalsePermite que qualquer usuário interaja (ignora a lista de permissão)
SIGNAL_HOME_CHANNELNão—Destino padrão de entrega das tarefas de cron