Pular para o conteúdo principal

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

Matrix

O Hermes Agent se integra ao Matrix, o protocolo de mensagens aberto e federado. O Matrix permite que você rode o próprio homeserver ou use um público, como o matrix.org — em qualquer um dos casos, o controle das suas comunicações continua com você. O bot conecta pelo SDK Python mautrix, processa as mensagens pelo pipeline do Hermes Agent (incluindo uso de ferramentas, memória e raciocínio) e responde em tempo real. Ele suporta texto, anexos de arquivo, imagens, áudio, vídeo e, opcionalmente, criptografia de ponta a ponta (E2EE).

O Hermes funciona com qualquer homeserver Matrix — Synapse, Conduit, Dendrite ou matrix.org.

Antes da configuração, a parte que a maioria quer saber: como o Hermes se comporta depois de conectado.

Como o Hermes se comporta​

ContextoComportamento
DMsO Hermes responde a toda mensagem. Não precisa de @menção. Cada DM tem a própria sessão. Defina MATRIX_DM_MENTION_THREADS=true para abrir um tópico quando o bot for @mencionado em uma DM.
SalasPor padrão, o Hermes exige uma @menção para responder. Defina MATRIX_REQUIRE_MENTION=false ou adicione IDs de sala a MATRIX_FREE_RESPONSE_ROOMS para salas de resposta livre. Convites de sala são aceitos automaticamente.
TópicosO Hermes suporta tópicos do Matrix (MSC3440). Se você responde dentro de um tópico, o Hermes mantém o contexto do tópico isolado da linha do tempo principal da sala. Tópicos em que o bot já participou não exigem menção.
Tópicos automáticosPor padrão, o Hermes cria um tópico automaticamente para cada mensagem que responde em uma sala. Isso mantém as conversas isoladas. Defina MATRIX_AUTO_THREAD=false para desligar. Defina MATRIX_DM_AUTO_THREAD=true (padrão false) para criar tópicos automáticos também em DMs — isso é diferente de MATRIX_DM_MENTION_THREADS, que só abre um tópico quando o bot é @mencionado em uma DM.
ComandosO Hermes aceita /comandos normais quando o seu cliente Matrix os envia. Se o seu cliente reserva / para comandos locais, use !comandos; o Hermes normaliza os apelidos !comando conhecidos para /comando.
Controles interativosA aprovação de comandos perigosos e a escolha em /model podem usar reações do Matrix. As reações de aprovação podem ser limitadas a quem pediu a ação.
Raciocínio e atividade de ferramentasO Matrix usa painéis de raciocínio/atividade de ferramentas em tópicos e editáveis quando o progresso do gateway está habilitado, para as atualizações não inundarem a linha do tempo principal da sala.
Salas compartilhadas com vários usuáriosPor padrão, o Hermes isola o histórico de sessão por usuário dentro da sala. Duas pessoas conversando na mesma sala não compartilham uma transcrição, a menos que você desligue isso explicitamente.
dica

O bot entra nas salas automaticamente ao ser convidado. Basta convidar o usuário Matrix do bot para qualquer sala que ele entra e começa a responder.

Matriz de capacidades​

Esta tabela é sustentada pela declaração de capacidades do adaptador Matrix e pela cobertura de testes do Matrix. O E2EE é por modo porque cada implantação escolhe se salas criptografadas ficam desligadas, oportunistas ou obrigatórias.

CapacidadeMatrix
textosim
tópicossim
reaçõessim
aprovaçõessim
seletor de modelosim
painéis de raciocíniosim
imagenssim
múltiplas imagenssim
arquivossim
voz/áudiosim
vídeosim
E2EEdesligado / opcional / obrigatório
diagnósticossim

Modelo de sessão no Matrix​

Por padrão:

  • cada DM tem a própria sessão
  • cada tópico tem o próprio espaço de nomes de sessão
  • cada usuário em uma sala compartilhada tem a própria sessão dentro daquela sala

Isso é controlado pelo config.yaml:

group_sessions_per_user: true

Coloque false só se você realmente quiser uma conversa única e compartilhada para a sala inteira:

group_sessions_per_user: false

Sessões compartilhadas podem ser úteis em uma sala colaborativa, mas também significam que:

  • os usuários compartilham o crescimento do contexto e o custo em tokens
  • uma tarefa longa e cheia de ferramentas de uma pessoa pode inchar o contexto de todo mundo
  • uma execução em andamento de uma pessoa pode interromper o acompanhamento de outra na mesma sala

Configuração de menção e tópicos​

Você configura o comportamento de menção e de tópicos automáticos por variáveis de ambiente ou pelo config.yaml:

matrix:
  require_mention: true           # Exigir @menção em salas (padrão: true)
  allowed_users:                  # Usuários Matrix autorizados a disparar turnos do agente
    - "@alice:matrix.org"
  allowed_rooms:                  # Salas Matrix autorizadas a disparar turnos do agente
    - "!abc123:matrix.org"
  free_response_rooms:            # Salas dispensadas da exigência de menção
    - "!abc123:matrix.org"
  ignore_user_patterns:           # Usuários fantasma de ponte/appservice a ignorar
    - "^@telegram_"
    - "^@whatsapp_"
  process_notices: false          # Ignora m.notice por padrão
  session_scope: room             # auto|room|thread; room é o recomendado para salas de projeto
  auto_thread: true               # Cria tópicos automáticos para as respostas (padrão: true)
  dm_mention_threads: false       # Cria tópico quando @mencionado em DM (padrão: false)
  max_message_length: 16000       # Tamanho do bloco de saída em caracteres (padrão: 16000, máx.: 65535)

Ou por variáveis de ambiente:

MATRIX_REQUIRE_MENTION=true
MATRIX_ALLOWED_USERS=@alice:matrix.org
MATRIX_ALLOWED_ROOMS=!abc123:matrix.org
MATRIX_FREE_RESPONSE_ROOMS=!abc123:matrix.org,!def456:matrix.org
MATRIX_IGNORE_USER_PATTERNS='^@telegram_,^@whatsapp_'
MATRIX_PROCESS_NOTICES=false
MATRIX_SESSION_SCOPE=room       # recomendado para contexto estável em salas de projeto
MATRIX_AUTO_THREAD=true
MATRIX_DM_MENTION_THREADS=false
MATRIX_REACTIONS=true          # padrão: true — reações em emoji durante o processamento
MATRIX_ALLOW_ROOM_MENTIONS=false
Desligando as reações

MATRIX_REACTIONS=false desliga as reações em emoji do ciclo de processamento (👀/✅/❌) que o bot publica nas mensagens recebidas. Útil em salas onde eventos de reação são barulhentos ou não são suportados por todos os clientes participantes.

Menções para a sala inteira

O Hermes envia menções estruturadas de usuário Matrix para IDs explícitos, como @alice:example.org. As notificações @room para a sala inteira vêm desligadas por padrão; defina MATRIX_ALLOW_ROOM_MENTIONS=true só em salas onde o bot pode notificar todo mundo.

observação

Se você está atualizando de uma versão que não tinha MATRIX_REQUIRE_MENTION, o bot antes respondia a todas as mensagens nas salas. Para manter esse comportamento, defina MATRIX_REQUIRE_MENTION=false.

Isolamento de salas de projeto​

Se você usa o mesmo bot Matrix em várias salas de projeto, configure sessões estáveis com escopo de sala:

MATRIX_SESSION_SCOPE=room
MATRIX_AUTO_THREAD=false

MATRIX_SESSION_SCOPE aceita:

EscopoComportamento
autoPadrão compatível com versões anteriores. O comportamento atual de MATRIX_AUTO_THREAD controla os tópicos sintéticos.
roomMensagens de sala fora de tópico ficam em uma única sessão estável da sala. Tópicos reais do Matrix continuam usando a raiz do tópico.
threadMensagens de sala fora de tópico sintetizam um tópico/sessão a partir do ID do evento que disparou.

O Hermes agora inclui no prompt do agente o nome da sala Matrix atual, o ID da sala, o tópico, o ID da mensagem e uma nota de fronteira de sala Matrix. O /status também mostra o escopo de sala/sessão Matrix atual, e o /resume não retoma silenciosamente uma sessão nomeada de outra sala Matrix a menos que você use explicitamente /resume --cross-room <nome da sessão>.

MATRIX_SESSION_SCOPE=room controla a faixa de sala/tópico. A configuração group_sessions_per_user continua controlando se os usuários dentro daquela sala compartilham a faixa. Com group_sessions_per_user: true (padrão), Alice e Bob têm sessões separadas no Projeto B. Com group_sessions_per_user: false, a sala tem uma única transcrição compartilhada do Projeto B.

Este guia conduz você por todo o processo de configuração — da criação da conta do bot até o envio da primeira mensagem.

Passo 1: Criar uma conta para o bot​

Você precisa de uma conta de usuário Matrix para o bot. Há várias formas de fazer isso:

Se você roda o próprio homeserver (Synapse, Conduit, Dendrite):

  1. Use a API de administração ou a ferramenta de registro para criar um usuário novo:
# Exemplo com Synapse
register_new_matrix_user -c /etc/synapse/homeserver.yaml http://localhost:8008
  1. Escolha um nome de usuário como hermes — o ID completo será @hermes:seu-servidor.org.

Opção B: Usar o matrix.org ou outro homeserver público​

  1. Acesse o Element Web e crie uma conta nova.
  2. Escolha um nome de usuário para o bot (ex.: hermes-bot).

Opção C: Usar a sua própria conta​

Você também pode rodar o Hermes como o seu próprio usuário. Isso significa que o bot publica como você — útil para assistentes pessoais.

Passo 2: Obter um access token​

O Hermes precisa de um access token para autenticar no homeserver. Você tem duas opções:

O jeito mais confiável de obter um token:

Pelo Element:

  1. Entre no Element com a conta do bot.
  2. Vá em Settings → Help & About.
  3. Role até o fim e expanda Advanced — o access token aparece ali.
  4. Copie na hora.

Pela API:

curl -X POST https://seu-servidor/_matrix/client/v3/login \
  -H "Content-Type: application/json" \
  -d '{
    "type": "m.login.password",
    "user": "@hermes:seu-servidor.org",
    "password": "sua-senha"
  }'

A resposta traz um campo access_token — copie o valor.

Guarde bem o seu access token

O access token dá acesso total à conta Matrix do bot. Nunca compartilhe publicamente nem comite no Git. Se vazar, revogue encerrando todas as sessões daquele usuário.

Opção B: Login com senha​

Em vez de fornecer um access token, você pode dar ao Hermes o ID de usuário e a senha do bot. O Hermes faz login automaticamente na inicialização. É mais simples, mas guarda a senha no seu arquivo .env.

MATRIX_USER_ID=@hermes:seu-servidor.org
MATRIX_PASSWORD=sua-senha

Passo 3: Descobrir o seu Matrix User ID​

O Hermes Agent usa o seu Matrix User ID para controlar quem pode interagir com o bot. Os Matrix User IDs seguem o formato @usuario:servidor.

Para descobrir o seu:

  1. Abra o Element (ou o cliente Matrix de sua preferência).
  2. Clique no seu avatar → Settings.
  3. O seu User ID aparece no topo do perfil (ex.: @alice:matrix.org).
dica

Matrix User IDs sempre começam com @ e contêm um : seguido do nome do servidor. Por exemplo: @alice:matrix.org, @bob:seu-servidor.com.

Passo 4: Configurar o Hermes Agent​

Rode o comando de configuração guiada:

hermes gateway setup

Escolha Matrix quando for perguntado e informe a URL do homeserver, o access token (ou ID de usuário + senha) e os IDs de usuário autorizados.

Opção B: Configuração manual​

Adicione o seguinte ao seu arquivo ~/.hermes/.env:

Usando access token:

# Obrigatório
MATRIX_HOMESERVER=https://matrix.example.org
MATRIX_ACCESS_TOKEN=***

# Opcional: ID de usuário (detectado pelo token se omitido)
# MATRIX_USER_ID=@hermes:matrix.example.org

# Segurança: restrinja quem pode interagir com o bot
MATRIX_ALLOWED_USERS=@alice:matrix.example.org

# Opcional: restrinja quais salas podem acionar o bot
MATRIX_ALLOWED_ROOMS=!abc123:matrix.example.org

# Vários usuários autorizados (separados por vírgula)
# MATRIX_ALLOWED_USERS=@alice:matrix.example.org,@bob:matrix.example.org

Usando login com senha:

# Obrigatório
MATRIX_HOMESERVER=https://matrix.example.org
MATRIX_USER_ID=@hermes:matrix.example.org
MATRIX_PASSWORD=***

# Segurança
MATRIX_ALLOWED_USERS=@alice:matrix.example.org

Endurecendo uma implantação privada​

Em implantações Matrix privadas, configure as duas listas de permissão: de usuário e de sala. Se MATRIX_ALLOWED_USERS não estiver definida, qualquer remetente que alcance o bot em uma sala em que ele está pode disparar um turno do agente. Se MATRIX_ALLOWED_ROOMS não estiver definida, qualquer sala em que o bot entrar pode disparar um turno do agente. Uma implantação trancada deve definir as duas:

MATRIX_ALLOWED_USERS=@alice:matrix.example.org,@bob:matrix.example.org
MATRIX_ALLOWED_ROOMS=!ops:matrix.example.org,!dmroom:matrix.example.org

Implantações com pontes e appservices precisam de proteção extra contra laços. O Hermes sempre ignora os próprios eventos, usuários no estilo appservice do Matrix cujo localpart começa com _, IDs de evento duplicados, eventos antigos de inicialização, eventos de substituição por edição e eventos m.notice, por padrão. Adicione padrões de fantasmas de ponte específicos da sua implantação quando a sua ponte usar outra convenção de nomes:

MATRIX_IGNORE_USER_PATTERNS='^@telegram_,^@slack_,^@whatsapp_'

Só habilite notices quando um fluxo humano confiável realmente enviar m.notice:

MATRIX_PROCESS_NOTICES=true

As notificações de saída para a sala inteira vêm desligadas por padrão. Mantenha MATRIX_ALLOW_ROOM_MENTIONS=false a menos que o bot esteja explicitamente autorizado a acordar a sala toda com @room.

Diagnósticos e payloads de depuração ocultam access tokens do Matrix, chaves de recuperação, identificadores de dispositivo e corpos de mensagem. O download de mídia é limitado a URIs de conteúdo mxc:// do Matrix e é recusado quando ultrapassa MATRIX_MAX_MEDIA_BYTES. Trate salas federadas e homeservers desconhecidos como entrada não confiável: mantenha as listas de salas enxutas, prefira DMs ou salas privadas para trabalho pesado em ferramentas e evite autorizar fantasmas de ponte ou fantoches de appservice como usuários permitidos.

Configurações opcionais de comportamento em ~/.hermes/config.yaml:

group_sessions_per_user: true
  • group_sessions_per_user: true mantém o contexto de cada participante isolado dentro de salas compartilhadas

Iniciar o gateway​

Com tudo configurado, inicie o gateway do Matrix:

hermes gateway

O bot deve conectar ao seu homeserver e começar a sincronizar em poucos segundos. Mande uma mensagem — por DM ou em uma sala em que ele entrou — para testar.

dica

Você pode rodar hermes gateway em segundo plano ou como serviço systemd para operação contínua. Veja a documentação de implantação para os detalhes.

Criptografia de ponta a ponta (E2EE)​

O Hermes suporta a criptografia de ponta a ponta do Matrix, então você pode conversar com o seu bot em salas criptografadas.

Requisitos​

O E2EE exige a biblioteca mautrix com os extras de criptografia e a biblioteca C libolm:

# Instale o mautrix com suporte a E2EE
pip install 'mautrix[encryption]'

# Ou instale com os extras do hermes
cd ~/.hermes/hermes-agent && uv pip install -e ".[matrix]"

Você também precisa do libolm instalado no sistema:

# Debian/Ubuntu
sudo apt install libolm-dev

# macOS
brew install libolm

# Fedora
sudo dnf install libolm-devel

Habilitar o E2EE​

Adicione ao seu ~/.hermes/.env:

MATRIX_E2EE_MODE=required

MATRIX_E2EE_MODE aceita:

ModoComportamento
offNão inicializa o E2EE do Matrix.
optionalTenta E2EE quando as dependências existem, mas mantém as salas não criptografadas funcionando se a criptografia não inicializar.
requiredFalha de forma fechada se as dependências de E2EE ou a configuração de criptografia não estiverem disponíveis.

O modo optional pode cair para operação sem E2EE quando a configuração de criptografia não está disponível. O modo required falha de forma fechada em vez de rebaixar silenciosamente.

Por compatibilidade com versões anteriores, MATRIX_ENCRYPTION=true ainda habilita o comportamento de E2EE obrigatório.

Com o E2EE habilitado, o Hermes:

  • Guarda as chaves de criptografia em ~/.hermes/platforms/matrix/store/ (instalações antigas: ~/.hermes/matrix/store/)
  • Envia as chaves de dispositivo na primeira conexão
  • Descriptografa as mensagens recebidas e criptografa as enviadas automaticamente
  • Entra automaticamente em salas criptografadas quando convidado

Ferramentas e controles do Matrix​

Em conversas no Matrix, o Hermes expõe ao agente ferramentas específicas do Matrix:

  • matrix_send_reaction
  • matrix_redact_message
  • matrix_create_room
  • matrix_invite_user
  • matrix_fetch_history
  • matrix_set_presence

Essas ferramentas têm escopo de contexto Matrix e não ficam disponíveis em conjuntos de ferramentas fora do Matrix. As ferramentas de administração vêm desligadas por padrão: a redação exige MATRIX_TOOLS_ALLOW_REDACTION=true, os convites exigem MATRIX_TOOLS_ALLOW_INVITES=true e a criação de salas exige MATRIX_TOOLS_ALLOW_ROOM_CREATE=true. Criar salas públicas exige também MATRIX_ALLOW_PUBLIC_ROOMS=true. Se MATRIX_ALLOWED_ROOMS estiver definida, as ferramentas do Matrix só podem mirar essas salas.

Os controles por reação usam:

  • ✅ aprovar uma vez
  • ♾️ aprovar sempre
  • ❌ negar
  • reações numéricas para as opções de /model

Defina MATRIX_APPROVAL_REQUIRE_SENDER=false se você quiser mesmo que qualquer usuário Matrix autorizado na sala possa operar um prompt de aprovação/seleção de modelo. O padrão é vincular ao solicitante quando o Hermes sabe quem pediu a ação.

Limites de mídia​

O Hermes envia e baixa imagens, arquivos, áudio e vídeo do Matrix pelas APIs de mídia do Matrix. Várias imagens geradas são enviadas como um único lote lógico ordenado, preservando legendas e o contexto do tópico ao longo do lote.

Por padrão, mídia do Matrix acima de 100 MB é recusada antes do upload/download. Para mudar:

MATRIX_MAX_MEDIA_BYTES=104857600

A mídia recebida precisa usar URIs de conteúdo mxc:// do Matrix. O Hermes recusa URLs de mídia HTTP(S) arbitrárias em eventos Matrix para não transformar uma sala federada em um baixador irrestrito.

Se a sua conta Matrix tem cross-signing habilitado (o padrão no Element), defina a chave de recuperação para o bot poder autoassinar o próprio dispositivo na inicialização. Sem isso, outros clientes Matrix podem se recusar a compartilhar sessões de criptografia com o bot após uma rotação de chaves de dispositivo.

MATRIX_RECOVERY_KEY=EsT... sua chave de recuperação aqui

Onde encontrar: no Element, vá em Settings → Security & Privacy → Encryption → sua chave de recuperação (também chamada de "Security Key"). É a chave que pediram para você guardar quando configurou o cross-signing pela primeira vez.

A cada inicialização, se MATRIX_RECOVERY_KEY estiver definida, o Hermes importa as chaves de cross-signing do armazenamento seguro de segredos do homeserver e assina o dispositivo atual. A operação é idempotente e pode ficar habilitada em definitivo sem problema.

Se o Hermes criar uma nova chave de recuperação do Matrix, ele nunca registra a chave em texto puro nos logs. Defina MATRIX_RECOVERY_KEY_OUTPUT_FILE=/caminho/seguro/matrix-recovery-key.txt antes de iniciar para gravar uma chave gerada uma única vez com modo de arquivo 0600; o arquivo não é sobrescrito se já existir.

Apagar o armazenamento de criptografia

Se você apagar ~/.hermes/platforms/matrix/store/crypto.db, o bot perde a identidade de criptografia. Só reiniciar com o mesmo device ID não recupera tudo — o homeserver ainda guarda chaves de uso único assinadas com a chave de identidade antiga, e os pares não conseguem estabelecer novas sessões Olm.

O Hermes detecta essa condição na inicialização e se recusa a habilitar o E2EE, registrando: device XXXX has stale one-time keys on the server signed with a previous identity key.

Recuperação mais fácil: gere um novo access token (que vem com um device ID novo, sem histórico de chaves obsoletas). Veja a seção "Atualizando de uma versão anterior com E2EE" abaixo. É o caminho mais confiável e não exige mexer no banco do homeserver.

Recuperação manual (avançado — mantém o mesmo device ID):

  1. Pare o Synapse e apague o dispositivo antigo do banco de dados:

    sudo systemctl stop matrix-synapse
    sudo sqlite3 /var/lib/matrix-synapse/homeserver.db "
      DELETE FROM e2e_device_keys_json WHERE device_id = 'DEVICE_ID' AND user_id = '@hermes:seu-servidor';
      DELETE FROM e2e_one_time_keys_json WHERE device_id = 'DEVICE_ID' AND user_id = '@hermes:seu-servidor';
      DELETE FROM e2e_fallback_keys_json WHERE device_id = 'DEVICE_ID' AND user_id = '@hermes:seu-servidor';
      DELETE FROM devices WHERE device_id = 'DEVICE_ID' AND user_id = '@hermes:seu-servidor';
    "
    sudo systemctl start matrix-synapse

    Ou pela API de administração do Synapse (note o ID de usuário codificado para URL):

    curl -X DELETE -H "Authorization: Bearer ADMIN_TOKEN" \
      'https://seu-servidor/_synapse/admin/v2/users/%40hermes%3Aseu-servidor/devices/DEVICE_ID'

    Atenção: apagar um dispositivo pela API de administração pode invalidar também o access token associado. Talvez você precise gerar um token novo depois.

  2. Apague o armazenamento de criptografia local e reinicie o Hermes:

    rm -f ~/.hermes/platforms/matrix/store/crypto.db*
    # reinicie o hermes

Outros clientes Matrix (Element, matrix-commander) podem manter em cache as chaves de dispositivo antigas. Depois da recuperação, digite /discardsession no Element para forçar uma nova sessão de criptografia com o bot.

informação

Se o mautrix[encryption] não estiver instalado ou faltar o libolm, o bot cai automaticamente para um cliente comum (sem criptografia). Você verá um aviso nos logs.

Sala principal​

Você pode designar uma "sala principal" onde o bot envia mensagens proativas (como saída de jobs de cron, lembretes e notificações). Há duas formas de definir:

Pelo comando de barra​

Digite /sethome em qualquer sala Matrix onde o bot esteja presente. Aquela sala vira a sala principal. Se o seu cliente Matrix intercepta comandos de barra, digite !sethome.

Configuração manual​

Adicione isto ao seu ~/.hermes/.env:

MATRIX_HOME_ROOM=!abc123def456:matrix.example.org

Lista de salas permitidas (allowed_rooms)​

Restringe o bot a um conjunto fixo de salas Matrix. Quando definida, o bot só responde em salas cujo ID está na lista — mensagens de qualquer outra sala são ignoradas em silêncio, mesmo que o bot seja mencionado.

DMs (salas de conversa direta) ficam de fora desse filtro, então usuários autorizados sempre conseguem falar com o bot a sós.

matrix:
  allowed_rooms:
    - "!abc123def456:matrix.example.org"
    - "!opsroom789:matrix.example.org"

Ou por variável de ambiente (separada por vírgula):

MATRIX_ALLOWED_ROOMS="!abc123def456:matrix.example.org,!opsroom789:matrix.example.org"

Comportamento:

  • Vazia / não definida → sem restrição (padrão).
  • Não vazia → o ID da sala precisa estar na lista. A checagem roda antes de qualquer outra barreira (exigência de menção, lista de remetentes etc.).
  • Use o ID interno da sala (!abc...:servidor), não o alias (#sala:servidor). Você encontra o ID interno de uma sala no Element em Sala → Settings → Advanced.

Veja também: divisão de comandos de barra entre admin e usuário.

dica

Para achar o ID de uma sala: no Element, vá na sala → Settings → Advanced → o Internal room ID aparece ali (começa com !).

Comandos no Matrix​

O Hermes suporta no Matrix os mesmos comandos de gateway que suporta nas outras plataformas de mensagens, incluindo /commands, /model, /stop, /queue, /steer, /goal, /subgoal, /background, /bg, /btw, /tasks e /yolo.

Alguns clientes Matrix reservam a / inicial para comandos locais do cliente e podem não enviar comandos de barra desconhecidos para a sala. Nesse caso, use ! como apelido seguro no Matrix:

!commands
!model
!model gpt-5.5 --provider openrouter
!queue continue com a próxima tarefa
!stop

O Hermes só normaliza !comando quando o comando é conhecido pelo gateway, é um comando registrado por plugin ou é um comando de skill instalada. Exclamações comuns como !importante continuam sendo mensagens normais de chat.

Solução de problemas​

O bot não responde às mensagens​

Causa: o bot não entrou na sala, MATRIX_ALLOWED_USERS não inclui o seu User ID, MATRIX_ALLOWED_ROOMS não inclui a sala, ou uma mensagem de sala não mencionou o bot.

Solução: convide o bot para a sala — ele entra sozinho ao ser convidado. Confira se o seu User ID está em MATRIX_ALLOWED_USERS (use o formato completo @usuario:servidor) e se o ID da sala está em MATRIX_ALLOWED_ROOMS, caso essa lista esteja configurada. Em salas, mencione o bot ou adicione a sala a MATRIX_FREE_RESPONSE_ROOMS. Reinicie o gateway.

O bot entra nas salas mas descarta toda mensagem em silêncio (relógio adiantado)​

Causa: o relógio do sistema da máquina está adiantado em relação ao tempo real. O adaptador Matrix aplica um filtro de tolerância de 5 segundos na inicialização (event_ts < startup_ts - 5) para ignorar eventos reenviados pelo sync inicial. Com o relógio adiantado, todo evento recebido parece "mais antigo que a inicialização" e é descartado antes de chegar ao handler de mensagens — o bot parece conectado, mas nunca responde. Veja #12614.

Sintoma: o log do gateway mostra Matrix: dropped N live events as 'too old' more than 30s after startup.

Solução: sincronize o relógio da máquina por NTP e reinicie o bot:

# Debian/Ubuntu
sudo timedatectl set-ntp true
timedatectl status   # confirme "System clock synchronized: yes"

# macOS
sudo sntp -sS time.apple.com

"Failed to authenticate" / "whoami failed" na inicialização​

Causa: o access token ou a URL do homeserver está incorreto.

Solução: confirme que MATRIX_HOMESERVER aponta para o seu homeserver (com https://, sem barra no fim). Verifique se MATRIX_ACCESS_TOKEN é válido — teste com curl:

curl -H "Authorization: Bearer SEU_TOKEN" \
  https://seu-servidor/_matrix/client/v3/account/whoami

Se isso devolver as informações do seu usuário, o token é válido. Se devolver erro, gere um token novo.

Erro "mautrix not installed"​

Causa: o pacote Python mautrix não está instalado.

Solução: instale:

pip install 'mautrix[encryption]'

Ou com os extras do Hermes:

cd ~/.hermes/hermes-agent && uv pip install -e ".[matrix]"

Erros de criptografia / "could not decrypt event"​

Causa: chaves de criptografia faltando, libolm não instalado ou o dispositivo do bot não é confiável.

Solução:

  1. Confirme que o libolm está instalado no sistema (veja a seção de E2EE acima).
  2. Garanta que MATRIX_ENCRYPTION=true está definido no seu .env.
  3. No seu cliente Matrix (Element), vá ao perfil do bot -> Sessions -> verifique/confie no dispositivo do bot.
  4. Se o bot acabou de entrar em uma sala criptografada, ele só consegue descriptografar mensagens enviadas depois da entrada. Mensagens anteriores ficam inacessíveis.

Atualizando de uma versão anterior com E2EE​

dica

Se você também apagou o crypto.db na mão, veja o aviso "Apagar o armazenamento de criptografia" na seção de E2EE acima — há passos adicionais para limpar as chaves de uso único obsoletas do homeserver.

Se você usava o Hermes com MATRIX_ENCRYPTION=true e está atualizando para uma versão que usa o novo armazenamento de criptografia em SQLite, a identidade de criptografia do bot mudou. O seu cliente Matrix (Element) pode manter em cache as chaves de dispositivo antigas e se recusar a compartilhar sessões de criptografia com o bot.

Sintomas: o bot conecta e mostra "E2EE enabled" nos logs, mas todas as mensagens aparecem como "could not decrypt event" e o bot nunca responde.

O que está acontecendo: o estado de criptografia antigo (do backend anterior baseado em matrix-nio ou em serialização do mautrix) é incompatível com o novo armazenamento SQLite. O bot cria uma identidade de criptografia nova, mas o seu cliente Matrix ainda tem as chaves antigas em cache e não compartilha a sessão de criptografia da sala com um dispositivo cujas chaves mudaram. Isso é um recurso de segurança do Matrix -- os clientes tratam mudança de chave de identidade no mesmo dispositivo como algo suspeito.

Solução (migração única):

  1. Gere um novo access token para obter um device ID novo. O jeito mais simples:

    curl -X POST https://seu-servidor/_matrix/client/v3/login \
      -H "Content-Type: application/json" \
      -d '{
        "type": "m.login.password",
        "identifier": {"type": "m.id.user", "user": "@hermes:seu-servidor.org"},
        "password": "***",
        "initial_device_display_name": "Hermes Agent"
      }'

    Copie o novo access_token e atualize MATRIX_ACCESS_TOKEN no ~/.hermes/.env.

  2. Apague o estado de criptografia antigo:

    rm -f ~/.hermes/platforms/matrix/store/crypto.db
    rm -f ~/.hermes/platforms/matrix/store/crypto_store.*

  3. Defina a sua chave de recuperação (se você usa cross-signing — a maioria dos usuários do Element usa). Adicione ao ~/.hermes/.env:

    MATRIX_RECOVERY_KEY=EsT... sua chave de recuperação aqui

    Isso permite que o bot se autoassine com as chaves de cross-signing na inicialização, então o Element confia no dispositivo novo na hora. Sem isso, o Element pode ver o dispositivo novo como não verificado e se recusar a compartilhar sessões de criptografia. Encontre a sua chave de recuperação no Element em Settings → Security & Privacy → Encryption.

  4. Force o seu cliente Matrix a rodar a sessão de criptografia. No Element, abra a sala de DM com o bot e digite /discardsession. Isso força o Element a criar uma sessão de criptografia nova e compartilhá-la com o novo dispositivo do bot.

  5. Reinicie o gateway:

    hermes gateway run

    Se MATRIX_RECOVERY_KEY estiver definida, você deve ver Matrix: cross-signing verified via recovery key nos logs.

  6. Mande uma mensagem nova. O bot deve descriptografar e responder normalmente.

observação

Depois da migração, as mensagens enviadas antes da atualização não podem ser descriptografadas -- as chaves antigas se foram. Isso afeta só a transição; as mensagens novas funcionam normalmente.

dica

Instalações novas não são afetadas. Essa migração só é necessária se você tinha um E2EE funcionando em uma versão anterior do Hermes e está atualizando.

Por que um novo access token? Cada access token do Matrix está vinculado a um device ID específico. Reusar o mesmo device ID com chaves de criptografia novas faz outros clientes Matrix desconfiarem do dispositivo (eles veem a mudança de chaves de identidade como uma possível brecha de segurança). Um access token novo vem com um device ID novo, sem histórico de chaves obsoletas, então os outros clientes confiam nele de imediato.

Modo proxy (E2EE no macOS)​

O E2EE do Matrix exige o libolm, que não compila no macOS ARM64 (Apple Silicon). O extra hermes-agent[matrix] está restrito ao Linux. Se você está no macOS, o modo proxy permite rodar o E2EE em um contêiner Docker numa VM Linux enquanto o agente de verdade roda nativamente no macOS, com acesso completo aos seus arquivos locais, memória e skills.

Como funciona​

macOS (host):
  └─ hermes gateway
       ├─ adaptador api_server ← escuta em 0.0.0.0:8642
       ├─ AIAgent ← fonte única da verdade
       ├─ Sessões, memória, skills
       └─ Acesso a arquivos locais (Obsidian, projetos etc.)

VM Linux (Docker):
  └─ hermes gateway (modo proxy)
       ├─ adaptador Matrix ← descriptografia/criptografia E2EE
       └─ encaminhamento HTTP → macOS:8642/v1/chat/completions
           (sem chaves de API de LLM, sem agente, sem inferência)

O contêiner Docker cuida só do protocolo Matrix + E2EE. Quando chega uma mensagem, ele a descriptografa e encaminha o texto ao host por uma requisição HTTP comum. O host roda o agente, chama as ferramentas, gera a resposta e a devolve em streaming. O contêiner criptografa e envia a resposta ao Matrix. Todas as sessões são unificadas — CLI, Matrix, Telegram e qualquer outra plataforma compartilham a mesma memória e o mesmo histórico de conversa.

Passo 1: Configurar o host (macOS)​

Habilite o servidor de API para o host aceitar as requisições vindas do contêiner Docker.

Adicione ao ~/.hermes/.env:

API_SERVER_ENABLED=true
API_SERVER_KEY=sua-chave-secreta-aqui
API_SERVER_HOST=0.0.0.0
  • API_SERVER_HOST=0.0.0.0 faz o bind em todas as interfaces para o contêiner Docker alcançar o host.
  • API_SERVER_KEY é obrigatória para bind fora do loopback. Escolha uma string aleatória forte.
  • O servidor de API roda na porta 8642 por padrão (mude com API_SERVER_PORT se precisar).

Inicie o gateway:

hermes gateway

Você deve ver o servidor de API subir junto com as outras plataformas que você configurou. Confirme que ele está acessível a partir da VM:

# A partir da VM Linux
curl http://<ip-do-mac>:8642/health

Passo 2: Configurar o contêiner Docker (VM Linux)​

O contêiner precisa das credenciais do Matrix e da URL do proxy. Ele NÃO precisa de chaves de API de LLM.

docker-compose.yml:

services:
  hermes-matrix:
    build: .
    environment:
      # Credenciais do Matrix
      MATRIX_HOMESERVER: "https://matrix.example.org"
      MATRIX_ACCESS_TOKEN: "syt_..."
      MATRIX_ALLOWED_USERS: "@voce:matrix.example.org"
      MATRIX_ENCRYPTION: "true"
      MATRIX_DEVICE_ID: "HERMES_BOT"

      # Modo proxy — encaminha para o agente no host
      GATEWAY_PROXY_URL: "http://192.168.1.100:8642"
      GATEWAY_PROXY_KEY: "sua-chave-secreta-aqui"
    volumes:
      - ./matrix-store:/root/.hermes/platforms/matrix/store

Dockerfile:

FROM python:3.11-slim

RUN apt-get update && apt-get install -y libolm-dev && rm -rf /var/lib/apt/lists/*
RUN cd ~/.hermes/hermes-agent && uv pip install -e ".[matrix]"

CMD ["hermes", "gateway"]

É esse o contêiner inteiro. Nenhuma chave de API do OpenRouter, da Anthropic ou de qualquer provedor de inferência.

Passo 3: Iniciar os dois​

  1. Primeiro inicie o gateway do host:

    hermes gateway

  2. Depois inicie o contêiner Docker:

    docker compose up -d

  3. Mande uma mensagem em uma sala Matrix criptografada. O contêiner descriptografa, encaminha ao host e devolve a resposta em streaming.

Referência de configuração​

O modo proxy é configurado no lado do contêiner (o gateway magro):

ConfiguraçãoDescrição
GATEWAY_PROXY_URLURL do servidor de API remoto do Hermes (ex.: http://192.168.1.100:8642)
GATEWAY_PROXY_KEYToken bearer de autenticação (precisa bater com API_SERVER_KEY no host)
gateway.proxy_urlO mesmo que GATEWAY_PROXY_URL, mas no config.yaml

O lado do host precisa de:

ConfiguraçãoDescrição
API_SERVER_ENABLEDDefina como true
API_SERVER_KEYToken bearer (compartilhado com o contêiner)
API_SERVER_HOSTDefina como 0.0.0.0 para acesso pela rede
API_SERVER_PORTNúmero da porta (padrão: 8642)

Funciona com qualquer plataforma​

O modo proxy não se limita ao Matrix. Qualquer adaptador de plataforma pode usá-lo — defina GATEWAY_PROXY_URL em qualquer instância de gateway e ela encaminha para o agente remoto em vez de rodar um localmente. Isso é útil em qualquer implantação em que o adaptador de plataforma precisa rodar em um ambiente diferente do agente (isolamento de rede, exigências de E2EE, restrição de recursos).

dica

A continuidade da sessão é mantida pelo cabeçalho X-Hermes-Session-Id. O servidor de API do host rastreia as sessões por esse ID, então as conversas persistem entre mensagens exatamente como aconteceria com um agente local.

observação

Limitações (v1): as mensagens de progresso de ferramentas do agente remoto não são repassadas — o usuário vê apenas a resposta final em streaming, não as chamadas individuais de ferramenta. Os pedidos de aprovação de comandos perigosos são tratados no lado do host, não repassados ao usuário do Matrix. Isso pode ser resolvido em atualizações futuras.

O bot conecta e envia, mas ignora as mensagens recebidas​

Causa: os handlers de evento do Matrix só disparam quando os payloads de sync passam pela maquinaria handle_sync() do mautrix. Um poll cru de client.sync() que nunca chama handle_sync() pode deixar o adaptador conectado (o envio funciona) enquanto as mensagens recebidas nunca chegam a _on_room_message.

Solução: o Hermes usa um laço de sync explícito que chama client.handle_sync() tanto no sync inicial quanto em cada resposta de sync incremental. Isso corresponde ao diagnóstico da issue upstream #7914 e do PR fechado #37807, mas mantém as tarefas de manutenção em segundo plano do próprio Hermes (rastreio de salas em que ele entrou, tratamento de convites, compartilhamento de chaves E2EE) em vez de delegar todo o ciclo de vida ao client.start(). Se as mensagens recebidas ainda falharem depois de reiniciar o gateway, confirme que os handlers estão registrados antes do primeiro sync e procure sync event dispatch error nos logs.

Problemas de sync / o bot fica para trás​

Causa: execuções longas de ferramentas podem atrasar o laço de sync, ou o homeserver está lento.

Solução: o laço de sync tenta de novo automaticamente a cada 5 segundos em caso de erro. Procure avisos relacionados a sync nos logs do Hermes. Se o bot ficar para trás com frequência, garanta que o seu homeserver tenha recursos suficientes.

O bot está offline​

Causa: o gateway do Hermes não está rodando ou falhou ao conectar.

Solução: confirme que o hermes gateway está rodando. Olhe a saída no terminal em busca de mensagens de erro. Problemas comuns: URL do homeserver errada, access token expirado, homeserver inacessível.

"User not allowed" / o bot ignora você​

Causa: o seu User ID não está em MATRIX_ALLOWED_USERS.

Solução: adicione o seu User ID a MATRIX_ALLOWED_USERS no ~/.hermes/.env e reinicie o gateway. Use o formato completo @usuario:servidor.

O bot ignora uma sala inteira​

Causa: MATRIX_ALLOWED_ROOMS está definida e o ID da sala atual não está na lista, ou a sala exige menção e a mensagem não mencionou o bot.

Solução: adicione o ID da sala a MATRIX_ALLOWED_ROOMS, ou remova a lista de salas se essa for uma implantação pessoal. Para achar o ID de uma sala no Element, abra as configurações da sala e veja em Advanced.

Mensagens de ponte entram em laço ou ecoam​

Causa: um fantoche de ponte/appservice está devolvendo a saída do bot como uma nova mensagem de usuário, ou a ponte usa IDs de usuário fantasma fora do padrão.

Solução: mantenha os fantasmas de ponte fora de MATRIX_ALLOWED_USERS, adicione uma entrada correspondente em MATRIX_IGNORE_USER_PATTERNS e deixe MATRIX_PROCESS_NOTICES=false, a menos que os notices façam parte de um fluxo confiável.

Segurança​

aviso

Sempre defina MATRIX_ALLOWED_USERS e, em implantações compartilhadas ou privadas, MATRIX_ALLOWED_ROOMS. Sem elas, qualquer pessoa que consiga mandar mensagem para o bot em uma sala em que ele está pode acionar o agente. Autorize apenas pessoas e salas em que você confia — usuários autorizados têm acesso total às capacidades do agente, incluindo uso de ferramentas e acesso ao sistema.

Para mais informações sobre como proteger a sua implantação do Hermes Agent, veja o Guia de segurança.

Observações​

  • Qualquer homeserver: funciona com Synapse, Conduit, Dendrite, matrix.org ou qualquer homeserver Matrix que siga a especificação. Não exige software específico de homeserver.
  • Federação: se você está em um homeserver federado, o bot consegue se comunicar com usuários de outros servidores — basta adicionar os IDs completos @usuario:servidor deles a MATRIX_ALLOWED_USERS.
  • Entrada automática: o bot aceita convites de sala e entra sozinho. Ele começa a responder logo depois de entrar.
  • Suporte a mídia: o Hermes envia e recebe imagens, áudio, vídeo e anexos de arquivo. A mídia é enviada ao seu homeserver pela API de repositório de conteúdo do Matrix.
  • Mensagens de voz nativas (MSC3245): o adaptador Matrix marca automaticamente as mensagens de voz enviadas com a flag org.matrix.msc3245.voice. Isso faz com que respostas em TTS e áudios de voz apareçam como bolhas de voz nativas no Element e em outros clientes compatíveis com MSC3245, em vez de anexos genéricos de áudio. Mensagens de voz recebidas com a flag MSC3245 também são identificadas corretamente e encaminhadas para a transcrição de fala em texto. Não precisa configurar nada — funciona sozinho.