Mattermost

Configurar o Mattermost

O Hermes Agent se integra ao Mattermost como um bot, o que permite conversar com seu assistente de IA por mensagens diretas ou por canais de equipe. O Mattermost é uma alternativa ao Slack, auto-hospedada e de código aberto — você o roda na sua própria infraestrutura, mantendo controle total dos seus dados. O bot se conecta pela API REST do Mattermost (v4) e por WebSocket para eventos em tempo real, processa as mensagens pelo pipeline do Hermes Agent (incluindo uso de ferramentas, memória e raciocínio) e responde em tempo real. Ele aceita texto, anexos de arquivo, imagens e comandos de barra.

Nenhuma biblioteca externa do Mattermost é necessária — o adaptador usa o aiohttp, que já é uma dependência do Hermes.

Antes da configuração, aqui está a parte que a maioria das pessoas quer saber: como o Hermes se comporta depois de estar na sua instância do Mattermost.

Como o Hermes se comporta

Contexto	Comportamento
Mensagens diretas	O Hermes responde a toda mensagem. Não precisa de @mention. Cada conversa direta tem a própria sessão.
Canais públicos/privados	O Hermes responde quando você faz um @mention. Sem menção, o Hermes ignora a mensagem.
Tópicos	Com MATTERMOST_REPLY_MODE=thread, o Hermes responde num tópico abaixo da sua mensagem. O contexto do tópico fica isolado do canal principal.
Canais compartilhados com várias pessoas	Por padrão, o Hermes isola o histórico de sessão por pessoa dentro do canal. Duas pessoas conversando no mesmo canal não compartilham uma transcrição, a menos que você desligue isso explicitamente.

dica

Se você quer que o Hermes responda em conversas encadeadas (aninhadas abaixo da sua mensagem original), defina MATTERMOST_REPLY_MODE=thread. O padrão é off, que envia mensagens soltas no canal.

Modelo de sessão no Mattermost

Por padrão:

• cada mensagem direta ganha a própria sessão
• cada tópico ganha o próprio espaço de nomes de sessão
• cada pessoa num canal compartilhado ganha a própria sessão dentro daquele canal

Isso é controlado pelo config.yaml:

group_sessions_per_user: true

Defina como false só se você realmente quiser uma conversa compartilhada para o canal inteiro:

group_sessions_per_user: false

Sessões compartilhadas podem ser úteis num canal colaborativo, mas também significam que:

• as pessoas dividem o crescimento do contexto e os custos de token
• a tarefa longa e cheia de ferramentas de uma pessoa pode inflar o contexto de todas as outras
• a execução em andamento de uma pessoa pode interromper o acompanhamento de outra no mesmo canal

Este guia leva você pelo processo completo de configuração — de criar o bot no Mattermost até enviar a primeira mensagem.

Passo 1: Habilitar contas de bot

As contas de bot precisam estar habilitadas no seu servidor Mattermost antes de você conseguir criar uma.

1. Entre no Mattermost como System Admin.
2. Vá em System Console → Integrations → Bot Accounts.
3. Defina Enable Bot Account Creation como true.
4. Clique em Save.

informação

Se você não tem acesso de System Admin, peça ao administrador do seu Mattermost para habilitar as contas de bot e criar uma para você.

Passo 2: Criar uma conta de bot

1. No Mattermost, clique no menu ☰ (canto superior esquerdo) → Integrations → Bot Accounts.
2. Clique em Add Bot Account.
3. Preencha os dados:
   • Username: por exemplo, hermes
   • Display Name: por exemplo, Hermes Agent
   • Description: opcional
   • Role: Member já basta
4. Clique em Create Bot Account.
5. O Mattermost vai mostrar o token do bot. Copie na hora.

O token aparece uma única vez

O token do bot só é mostrado uma vez, quando você cria a conta de bot. Se você perder, vai precisar gerar outro nas configurações da conta de bot. Nunca compartilhe seu token publicamente nem o comite no Git — quem tem esse token tem controle total do bot.

Guarde o token em lugar seguro (num gerenciador de senhas, por exemplo). Você vai precisar dele no Passo 5.

dica

Você também pode usar um token de acesso pessoal em vez de uma conta de bot. Vá em Profile → Security → Personal Access Tokens → Create Token. Isso é útil se você quer que o Hermes publique como o seu próprio usuário, em vez de um usuário de bot separado.

Passo 3: Adicionar o bot aos canais

O bot precisa ser membro de todo canal em que você quer que ele responda:

1. Abra o canal em que você quer o bot.
2. Clique no nome do canal → Add Members.
3. Busque o nome de usuário do seu bot (por exemplo, hermes) e adicione.

Para mensagens diretas, basta abrir uma conversa direta com o bot — ele já vai poder responder.

Passo 4: Descobrir seu User ID do Mattermost

O Hermes Agent usa o seu User ID do Mattermost para controlar quem pode interagir com o bot. Para descobrir:

1. Clique no seu avatar (canto superior esquerdo) → Profile.
2. Seu User ID aparece na janela de perfil — clique nele para copiar.

Seu User ID é uma sequência alfanumérica de 26 caracteres, como 3uo8dkh1p7g1mfk49ear5fzs5c.

aviso

Seu User ID não é o seu nome de usuário. O nome de usuário é o que aparece depois do @ (por exemplo, @alice). O User ID é um identificador alfanumérico longo que o Mattermost usa internamente.

Alternativa: você também pode obter seu User ID pela API:

curl -H "Authorization: Bearer SEU_TOKEN" \
  https://seu-servidor-mattermost/api/v4/users/me | jq .id

dica

Para obter um Channel ID: clique no nome do canal → View Info. O Channel ID aparece no painel de informações. Você vai precisar dele se quiser definir um canal padrão manualmente.

Passo 5: Configurar o Hermes Agent

Opção A: configuração interativa (recomendada)

Rode o comando de configuração guiada:

hermes gateway setup

Escolha Mattermost quando for perguntado, depois cole a URL do servidor, o token do bot e o user ID conforme pedido.

Opção B: configuração manual

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

# Obrigatório
MATTERMOST_URL=https://mm.exemplo.com
MATTERMOST_TOKEN=***
MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c

# Várias pessoas autorizadas (separadas por vírgula)
# MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c,8fk2jd9s0a7bncm1xqw4tp6r3e

# Opcional: modo de resposta (thread ou off, padrão: off)
# MATTERMOST_REPLY_MODE=thread

# Opcional: responder sem @mention (padrão: true = exige menção)
# MATTERMOST_REQUIRE_MENTION=false

# Opcional: canais em que o bot responde sem @mention (IDs de canal separados por vírgula)
# MATTERMOST_FREE_RESPONSE_CHANNELS=channel_id_1,channel_id_2

Ajustes opcionais de comportamento no ~/.hermes/config.yaml:

group_sessions_per_user: true

• group_sessions_per_user: true mantém o contexto de cada participante isolado dentro de canais compartilhados e tópicos

Iniciar o gateway

Depois de configurar, inicie o gateway do Mattermost:

hermes gateway

O bot deve se conectar ao seu servidor Mattermost em poucos segundos. Mande uma mensagem para ele — uma direta ou num canal em que ele foi adicionado — para testar.

dica

Você pode rodar o hermes gateway em segundo plano ou como um serviço do systemd para uma operação permanente. Veja a documentação de implantação para os detalhes.

Canal padrão

Você pode designar um "canal padrão" onde o bot envia mensagens por iniciativa própria (como saída de tarefas de cron, lembretes e notificações). Há duas formas de definir:

Pelo comando de barra

Digite /sethome em qualquer canal do Mattermost onde o bot esteja presente. Aquele canal se torna o canal padrão.

Configuração manual

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

MATTERMOST_HOME_CHANNEL=abc123def456ghi789jkl012mn

Troque o ID pelo ID real do canal (clique no nome do canal → View Info → copie o ID).

Modo de resposta

O ajuste MATTERMOST_REPLY_MODE controla como o Hermes publica as respostas:

Modo	Comportamento
off (padrão)	O Hermes publica mensagens soltas no canal, como uma pessoa comum.
thread	O Hermes responde num tópico abaixo da sua mensagem original. Mantém os canais limpos quando há muita troca de ida e volta.

Defina no seu ~/.hermes/.env:

MATTERMOST_REPLY_MODE=thread

Comportamento de menção

Por padrão, o bot só responde nos canais quando recebe um @mentioned. Você pode mudar isso:

Variável	Padrão	Descrição
MATTERMOST_REQUIRE_MENTION	true	Defina como false para responder a todas as mensagens dos canais (as mensagens diretas sempre funcionam).
MATTERMOST_FREE_RESPONSE_CHANNELS	(nenhum)	IDs de canal separados por vírgula em que o bot responde sem @mention, mesmo quando require_mention está em true.

Para descobrir um ID de canal no Mattermost: abra o canal, clique no cabeçalho com o nome do canal e procure o ID na URL ou nos detalhes do canal.

Quando o bot recebe um @mentioned, a menção é retirada automaticamente da mensagem antes do processamento.

Lista de canais permitidos (allowed_channels)

Restrinja o bot a um conjunto fixo de canais do Mattermost. Quando definida, o bot responde apenas em canais cujo ID aparece na lista — mensagens de qualquer outro canal são ignoradas em silêncio, mesmo que o bot receba um @mentioned.

As mensagens diretas ficam de fora desse filtro, então pessoas autorizadas sempre conseguem alcançar o bot numa conversa direta.

mattermost:
  allowed_channels:
    - "abc123def456ghi789jkl012mno"   # #ops
    - "xyz987uvw654rst321opq098nml"   # #resposta-a-incidentes

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

MATTERMOST_ALLOWED_CHANNELS="abc123def456ghi789jkl012mno,xyz987uvw654rst321opq098nml"

Comportamento:

• Vazia / não definida → nenhuma restrição (totalmente compatível com o comportamento anterior).
• Não vazia → o ID do canal precisa estar na lista, ou a mensagem é descartada antes de qualquer outra trava (exigência de menção, MATTERMOST_FREE_RESPONSE_CHANNELS, etc.).
• Descubra o ID de um canal pela interface do Mattermost → cabeçalho do canal → "View Info", ou leia da URL do canal.

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

Solução de problemas

O bot não responde às mensagens

Causa: o bot não é membro do canal, ou o MATTERMOST_ALLOWED_USERS não inclui o seu User ID.

Correção: adicione o bot ao canal (nome do canal → Add Members → busque o bot). Confirme que seu User ID está em MATTERMOST_ALLOWED_USERS. Reinicie o gateway.

Erros 403 Forbidden

Causa: o token do bot é inválido, ou o bot não tem permissão para publicar no canal.

Correção: verifique se o MATTERMOST_TOKEN do seu arquivo .env está correto. Confirme que a conta de bot não foi desativada. Verifique se o bot foi adicionado ao canal. Se estiver usando um token de acesso pessoal, garanta que sua conta tem as permissões necessárias.

O WebSocket cai / laços de reconexão

Causa: instabilidade de rede, reinícios do servidor Mattermost, ou problemas de firewall/proxy com conexões WebSocket.

Correção: o adaptador reconecta automaticamente com recuo exponencial (2s → 60s). Confira a configuração de WebSocket do seu servidor — proxies reversos (nginx, Apache) precisam dos cabeçalhos de upgrade de WebSocket configurados. Confirme que nenhum firewall está bloqueando conexões WebSocket no seu servidor Mattermost.

No nginx, garanta que sua configuração inclua:

location /api/v4/websocket {
    proxy_pass http://mattermost-backend;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 600s;
}

"Failed to authenticate" ao iniciar

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

Correção: confirme que o MATTERMOST_URL aponta para o seu servidor Mattermost (inclua o https://, sem barra no fim). Verifique se o MATTERMOST_TOKEN é válido — teste com o curl:

curl -H "Authorization: Bearer SEU_TOKEN" \
  https://seu-servidor/api/v4/users/me

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

O bot está offline

Causa: o gateway do Hermes não está rodando, ou não conseguiu se conectar.

Correção: verifique se o hermes gateway está rodando. Olhe a saída do terminal em busca de mensagens de erro. Problemas comuns: URL errada, token expirado, servidor Mattermost inalcançável.

"User not allowed" / o bot ignora você

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

Correção: acrescente seu User ID ao MATTERMOST_ALLOWED_USERS em ~/.hermes/.env e reinicie o gateway. Lembre: o User ID é uma sequência alfanumérica de 26 caracteres, não o seu @username.

Prompts por canal

Atribua prompts de sistema efêmeros a canais específicos do Mattermost. O prompt é injetado em tempo de execução em cada turno — nunca é gravado no histórico da transcrição — então as mudanças valem imediatamente.

mattermost:
  channel_prompts:
    "channel_id_abc123": |
      Você é um assistente de pesquisa. Foque em fontes acadêmicas,
      citações e síntese concisa.
    "channel_id_def456": |
      Modo de revisão de código. Seja preciso sobre casos de borda e
      implicações de desempenho.

As chaves são IDs de canal do Mattermost (encontre-os na URL do canal ou pela API). Todas as mensagens do canal correspondente recebem o prompt injetado como uma instrução de sistema efêmera.

Segurança

aviso

Defina sempre o MATTERMOST_ALLOWED_USERS para restringir quem pode interagir com o bot. Sem isso, o gateway nega todas as pessoas por padrão, como medida de segurança. Só acrescente User IDs de gente em quem você confia — pessoas autorizadas têm acesso total às capacidades do agente, incluindo uso de ferramentas e acesso ao sistema.

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

Notas

• Amigável para auto-hospedagem: funciona com qualquer instância auto-hospedada do Mattermost. Não é preciso conta nem assinatura do Mattermost Cloud.
• Sem dependências extras: o adaptador usa o aiohttp para HTTP e WebSocket, que já vem com o Hermes Agent.
• Compatível com a Team Edition: funciona tanto com a Mattermost Team Edition (gratuita) quanto com a Enterprise Edition.

---