Agente Hermes no Mattermost — Chat Auto-Hospedado

Se a sua equipe usa o Mattermost, você já conhece o apelo: ele se parece e funciona como o Slack, mas o servidor — e os dados — ficam na sua própria infraestrutura. O Hermes Agent se conecta a ele como um bot, usando a API REST (v4) do Mattermost mais um WebSocket para eventos em tempo real, para que o seu assistente possa responder em DMs e canais de equipe sem que nada saia da sua rede.

Não há biblioteca extra para instalar: o adaptador usa aiohttp, que já vem com o Hermes. Funciona tanto com o Mattermost Team Edition (gratuito) quanto com o Enterprise Edition.

Como o Hermes se Comporta no Mattermost

Onde você fala com ele	O que acontece
DMs	O Hermes responde a todas as mensagens — sem necessidade de `@mention`. Cada DM tem sua própria sessão.
Canais	O Hermes responde quando você o `@menciona`. Sem menção, ele ignora a mensagem.
Threads	Com `MATTERMOST_REPLY_MODE=thread`, as respostas ficam aninhadas sob a sua mensagem e isoladas do canal principal.
Canais compartilhados	O histórico da sessão é isolado por usuário por padrão, então duas pessoas em um mesmo canal não compartilham um transcript.

Esse último comportamento é controlado por group_sessions_per_user no config.yaml:

group_sessions_per_user: true   # cada pessoa mantém seu próprio contexto

Defina como false apenas se você quiser deliberadamente uma conversa compartilhada para o canal inteiro. Uma sessão compartilhada significa que todos dividem o crescimento de contexto e os custos de tokens, e a tarefa longa e cheia de ferramentas de uma pessoa pode inflar ou interromper a execução de outra.

Passo 1: Habilitar Contas de Bot (Lado do Administrador)

As contas de bot precisam estar ativadas no servidor antes que você possa criar uma:

Faça login no Mattermost como System Admin.
Vá em System Console → Integrations → Bot Accounts.
Defina Enable Bot Account Creation como true e clique em Save.

Sem acesso de administrador? Peça ao administrador do Mattermost para habilitar as contas de bot e criar uma para você.

Passo 2: Criar a Conta de Bot

Clique no menu ☰ (canto superior esquerdo) → Integrations → Bot Accounts → Add Bot Account.
Preencha os detalhes: Username como hermes, Display Name como Hermes Agent e um Role — Member é suficiente.
Clique em Create Bot Account e depois copie o token imediatamente — ele é exibido apenas uma vez. Se perdê-lo, você terá que regenerá-lo nas configurações da conta de bot.

⚠️ Nunca compartilhe o token nem o envie para o Git. Qualquer pessoa que o tenha em mãos tem controle total do bot.

Prefere que o agente poste como o seu próprio usuário em vez de um bot separado? Crie um personal access token em Profile → Security → Personal Access Tokens → Create Token.

Passo 3: Convidar o Bot para os Canais

O bot só responde nos canais aos quais pertence:

Abra o canal → clique no nome do canal → Add Members.
Procure pelo username do bot (por exemplo, hermes) e adicione-o.

Para DMs, basta abrir uma mensagem direta com o bot — nenhum convite é necessário.

Passo 4: Encontrar o Seu User ID do Mattermost

O Hermes usa o seu User ID — não o seu username — para decidir quem tem permissão para falar com o bot:

Clique no seu avatar (canto superior esquerdo) → Profile.
A janela mostra o seu User ID: uma string alfanumérica de 26 caracteres, como 3uo8dkh1p7g1mfk49ear5fzs5c. Clique nela para copiar.

Você também pode obtê-lo pela API:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-mattermost-server/api/v4/users/me | jq .id

O seu User ID não é o @username que você vê nas mensagens. Colar o username é o motivo mais comum de um bot ficar em silêncio.

Passo 5: Configurar o Hermes

Execute a configuração guiada e escolha Mattermost quando solicitado — ela pede a URL do servidor, o token do bot e o seu User ID:

hermes gateway setup

Ou configure manualmente em ~/.hermes/.env:

# Obrigatório
MATTERMOST_URL=https://mm.example.com
MATTERMOST_TOKEN=your-bot-token
MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c

# Vários usuários permitidos (separados por vírgula)
# MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c,8fk2jd9s0a7bncm1xqw4tp6r3e

# Opcional: responder em uma thread em vez de mensagens soltas (padrão: desativado)
# MATTERMOST_REPLY_MODE=thread

# Opcional: responder sem um @mention (padrão: true = menção obrigatória)
# MATTERMOST_REQUIRE_MENTION=false

# Opcional: canais onde nenhum @mention é necessário (IDs de canal separados por vírgula)
# MATTERMOST_FREE_RESPONSE_CHANNELS=channel_id_1,channel_id_2

Depois, inicie o gateway:

hermes gateway

O bot se conecta ao seu servidor Mattermost em alguns segundos. Envie uma DM, ou o @mencione em um canal onde ele foi adicionado, para testar.

Passo 6: Opções de Comportamento Opcionais

Configuração	O que ela faz
`MATTERMOST_REPLY_MODE`	`off` (padrão) publica mensagens soltas; `thread` aninha as respostas sob a sua mensagem e mantém canais movimentados organizados.
`MATTERMOST_REQUIRE_MENTION`	`true` por padrão. Defina como `false` para responder a todas as mensagens do canal (DMs sempre funcionam).
`MATTERMOST_FREE_RESPONSE_CHANNELS`	IDs de canal que dispensam a exigência de menção mesmo quando menções são obrigatórias.
`MATTERMOST_HOME_CHANNEL`	Para onde vão as mensagens proativas — saída de cron, lembretes, notificações. Ou digite `/sethome` em um canal.
`mattermost.allowed_channels`	Restringe o bot a uma lista de IDs de canal; mensagens de qualquer outro lugar são descartadas. DMs são isentas.
`mattermost.channel_prompts`	Injeta um system prompt efêmero por canal — aplicado em cada turno, nunca salvo no histórico do transcript.

Quando o bot é @mencionado, a menção é removida da mensagem antes do processamento, então @hermes summarize this thread chega como uma instrução limpa.

Solução de Problemas

Sintoma	Causa provável	Correção
O bot te ignora nos canais	Ele não está no canal, ou o seu User ID não está em `MATTERMOST_ALLOWED_USERS`	Adicione o bot ao canal, verifique o User ID de 26 caracteres, reinicie o gateway
O bot não consegue postar	Token inválido, ou o bot não tem permissão naquele canal	Verifique `MATTERMOST_TOKEN`, confirme que a conta está ativa e é membro do canal
Desconexões constantes	Quedas do WebSocket, reinícios do servidor ou problemas de proxy/firewall	O adaptador se reconecta com backoff exponencial (2s → 60s); para nginx, certifique-se de que os cabeçalhos de upgrade do WebSocket estão configurados
Nada acontece de forma alguma	Gateway não está rodando, ou a URL/token está errada	Verifique a saída do `hermes gateway` e se `MATTERMOST_URL` inclui `https://` sem barra no final

Teste um token diretamente com:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-server/api/v4/users/me

Protegendo o Bot

Sempre defina MATTERMOST_ALLOWED_USERS. Sem isso, o gateway nega todos os usuários por padrão como medida de segurança — e usuários autorizados têm acesso total às capacidades do agente, incluindo uso de ferramentas e acesso ao sistema, então mantenha a lista restrita. Para uma visão mais ampla sobre como reforçar a segurança de uma implantação, consulte as orientações oficiais de segurança.

E Agora?

Depois que o gateway estiver no ar, o Mattermost se comporta como qualquer outro canal do Hermes: slash commands, uploads de arquivos, notas de voz, saída de cron entregue no seu canal home — tudo em infraestrutura que você controla. Se você preferir usar a opção hospedada, a integração com o Slack cobre a rota do Socket Mode; se você roda gateways em várias máquinas, o Hermes Relay conecta todas elas.