Como configurar o Hermes Agent no Slack (Socket Mode)

Por que ter o Hermes Agent dentro do Slack

Se a sua equipa já vive no Slack, é lá que o seu agente de IA também deve viver. Abas do navegador e dashboards isolados perdem o contexto que canais, threads e mensagens diretas oferecem de graça: quem está a perguntar, sobre o que se estava a falar há cinco minutos e onde a resposta deve aterrar.

O Hermes Agent traz suporte de primeira classe para o Slack via Socket Mode, então o runtime pode estar no seu portátil, num VPS de 5 dólares ou atrás do firewall corporativo e ainda assim trocar mensagens em tempo real. Não é preciso expor um webhook público, montar um proxy reverso nem abrir uma porta de entrada. O agente conecta para fora ao Slack, mantém um WebSocket aberto e entrega cada mensagem e cada resposta por esse mesmo canal.

Este guia percorre a configuração completa de ponta a ponta: criar a app do Slack a partir do manifesto incluído, gerar os dois tokens, ligar o canal home e a allowlist, arrancar o gateway e as falhas típicas que mordem na primeira tentativa.

O que precisa antes de começar

Uma instalação limpa do Slack precisa de cinco peças no lugar:

Um workspace onde tenha permissão para instalar apps. A maior parte dos workspaces exige que um admin aprove a instalação por padrão - confira Settings & administration → Workspace settings → Permissions se não for admin.
Uma instalação do Hermes Agent a correr. O guia do Hermes Agent em Docker cobre a forma mais limpa de subir uma; se estiver no Windows, o setup com WSL2 é o equivalente.
Uma chave de API de um provedor de modelos. Anthropic, OpenAI, OpenRouter e qualquer endpoint compatível com OpenAI funcionam. O runtime usa-a para responder de facto às mensagens.
O seu Slack user ID numérico para a allowlist (mais abaixo).
Cerca de 15 minutos para a primeira instalação. Os redeployments seguintes demoram menos de um minuto.

Passo 1 - Gerar o manifesto da app do Slack

As apps do Slack definem-se num manifesto YAML que declara permissões, subscrições de eventos, slash commands e Socket Mode de uma só vez. O Hermes inclui um manifesto pensado para o seu handler nativo do Slack, então não tem de montar a lista de scopes à mão:

hermes slack manifest --write ./hermes-slack-manifest.yaml

Abra https://api.slack.com/apps, clique em Create New App, escolha From an app manifest, selecione o seu workspace e cole o conteúdo do hermes-slack-manifest.yaml. O Slack mostra exatamente o que vai ser criado. Confirme.

O manifesto ativa o Socket Mode, declara cada evento que o Hermes assina (app_mention, message.im, message.channels, message.groups, message.mpim), regista os slash commands embutidos e pede os scopes de bot que o runtime usa de facto:

app_mentions:read - ouvir quando alguém menciona o bot num canal.
chat:write - enviar respostas e abrir threads.
im:history, im:read, im:write - conversas por mensagem direta.
channels:history, groups:history, mpim:history - ler contexto em canais públicos, canais privados e grupos onde o bot for convidado.
users:read - resolver IDs de utilizador em nomes legíveis para a UI da allowlist e para os logs de auditoria.
commands - registar a superfície do slash command /hermes.

Editar o manifesto após a instalação não tem problema. Adicionar scopes depois da instalação é a operação que mais falhas silenciosas provoca - veja a secção de troubleshooting mais à frente.

Passo 2 - Gerar o bot token e o app-level token

O Slack emite dois tokens distintos para uma app em Socket Mode, e o Hermes precisa dos dois:

Bot token (xoxb-…)

Nas definições da app, vá a OAuth & Permissions → Install to Workspace. Aprove os scopes do manifesto. O Slack emite um token xoxb-…. Copie-o.

App-level token (xapp-…)

Vá a Basic Information → App-Level Tokens → Generate Token and Scopes. Dê-lhe um nome (por exemplo, hermes-socket), adicione o scope connections:write e clique em Generate. O Slack emite um token xapp-…. Copie-o.

Os dois tokens fazem coisas diferentes. O bot token autentica as chamadas à API do Slack (enviar uma mensagem, ler o histórico de um canal). O app token autentica o próprio WebSocket do Socket Mode - sem ele, o runtime arranca mas nunca se liga ao Slack e o bot fica calado para sempre.

Passo 3 - Encontre o seu Slack user ID numérico

O Hermes Agent só responde aos IDs de utilizador que aparecem em SLACK_ALLOWED_USERS. É o controlo de segurança mais importante de toda a configuração e espera IDs numéricos, não @handles nem nomes visíveis.

No Slack, clique no seu avatar → Profile → menu de três pontos (⋮) → Copy member ID. O ID parece-se com U01ABCD2EFG. Repita o processo para cada colega que queira autorizar.

Saltar a allowlist é o mesmo que publicar a chave de API do seu provedor a qualquer pessoa do workspace. Se uma instância do Hermes estiver acessível a partir de um workspace de Slack aberto e a lista estiver vazia, cada mensagem em cada canal onde o bot tenha sido convidado vai queimar os seus tokens.

Passo 4 - Configure o runtime do Hermes

Abra ~/.hermes/.env (ou o .env que o seu contentor lê) e adicione:

SLACK_BOT_TOKEN=xoxb-...o-seu-bot-token...
SLACK_APP_TOKEN=xapp-...o-seu-app-token...
SLACK_ALLOWED_USERS=U01ABCD2EFG,U02HIJK3LMN
SLACK_HOME_CHANNEL=C04XYZ123AB

Uma nota sobre cada variável:

SLACK_BOT_TOKEN - o token xoxb-… do Passo 2.
SLACK_APP_TOKEN - o token xapp-…. Esquecê-lo é a falha mais comum e não produz qualquer mensagem de erro - o gateway simplesmente nunca abre o WebSocket.
SLACK_ALLOWED_USERS - lista de IDs numéricos separados por vírgula. O bot ignora qualquer outra pessoa, incluindo admins e bots.
SLACK_HOME_CHANNEL (opcional) - o ID do canal para mensagens proativas, resumos agendados e notificações disparadas por skills. Clique com o botão direito no canal no Slack → View channel details → copie o ID que aparece em baixo. Se ficar vazio, a saída proativa vai para o DM do bot com o primeiro utilizador permitido.

chmod 600 ~/.hermes/.env depois de guardar. Os dois tokens dão acesso de escrita ao seu workspace; trate-os como chaves SSH.

Um terminal a mostrar o ficheiro .env do Hermes com SLACK_BOT_TOKEN, SLACK_APP_TOKEN, SLACK_ALLOWED_USERS e SLACK_HOME_CHANNEL preenchidos, e as permissões do ficheiro em 600

Passo 5 - Arranque o gateway

Reinicie o gateway para que apanhe o novo ambiente:

hermes gateway restart

Ou, com Docker Compose:

docker compose restart gateway

Siga os logs e fique atento ao handshake com o Slack:

hermes gateway logs --follow

Está à procura de duas linhas, por esta ordem:

slack: connecting to Socket Mode
slack: connected as @o-seu-bot-name (workspace: o-seu-workspace)

Se vir só a primeira e mais nada, o token xapp-… está errado, em falta ou não tem o scope connections:write. Se não vir nenhuma, o gateway não está a ler o novo .env - confirme o caminho do ficheiro que o runtime usa.

Passo 6 - Convide o bot e envie a primeira mensagem

Em qualquer canal onde queira que o bot participe:

/invite @o-seu-bot-name

O bot só vê mensagens em canais onde foi convidado. É uma restrição do lado do Slack, não do Hermes - mesmo com channels:history concedido, lê zero histórico até o convidar.

Envie um DM ao bot, ou mencione-o (@) num canal. O Hermes responde na mesma conversa, com toda a memória persistente e as skills intactas. A partir daqui, todas as capacidades do Hermes - memória persistente, tarefas agendadas, skills personalizadas - funcionam exatamente como na superfície do Telegram.

Um canal de Slack a mostrar uma thread entre um utilizador e o bot Hermes, com o bot a responder em contexto e um pequeno indicador verde junto ao nome do bot

As falhas que mordem primeiro

Cinco erros explicam quase todas as threads de suporte do estilo "a integração com o Slack está partida":

Esquecer o token xapp-…. O Socket Mode não se liga sem ele e o painel do Slack não avisa. A correção é uma linha no .env e um restart.

Adicionar scopes depois de instalar sem reinstalar. Os novos scopes aparecem na página de OAuth mas não são de facto concedidos ao bot até clicar em Reinstall to Workspace. O bot fica com o conjunto de scopes anterior em silêncio. Se os logs do runtime mostrarem erros missing_scope, é esta a causa.

O bot não foi convidado para o canal. Um bot com channels:history continua a ler zero histórico até ser convidado. Responde aos DMs de imediato mas mantém-se calado em canais até correr /invite @o-seu-bot-name.

SLACK_ALLOWED_USERS vazio. O comportamento por defeito é ignorar toda a gente. É um default seguro intencional, mas faz o bot parecer partido a quem o testa pela primeira vez sem se lembrar de adicionar o seu próprio ID.

Dois processos de gateway contra o mesmo volume de dados. Se arrancar um gateway em modo Slack e outro em modo Telegram contra o mesmo diretório /data, a ordem das mensagens e as escritas de memória corrompem-se entre si em poucos minutos. Se quiser as duas superfícies, corra um único gateway com os blocos SLACK_* e TELEGRAM_* no .env - o runtime multiplexa ambas nativamente.

Se o problema parecer de Slack mas os sintomas forem mais gerais, o guia de troubleshooting do Telegram cobre os problemas de gateway e de provedor com mais profundidade - a maioria é agnóstica à superfície.

Slack e Telegram, lado a lado

Aspeto	Slack	Telegram
Tempo de setup	15 min (manifesto + 2 tokens)	5 min (um token do BotFather)
Acessibilidade	Atrás do firewall (WebSocket de Socket Mode)	Atrás do firewall (long-poll)
Campo de allowlist	`SLACK_ALLOWED_USERS` (IDs numéricos)	`TELEGRAM_ALLOWED_USERS` (IDs numéricos)
Melhor para	Fluxos de equipa, contexto de canal, threads	Uso pessoal, mobile-first, modo voz
Threads	Nativas	Apenas respostas com citação
Ficheiros	Uploads e previews integrados	Uploads e previews integrados

As duas superfícies não são exclusivas. O mesmo runtime do Hermes pode entregar mensagens às duas ao mesmo tempo - útil quando o mesmo agente serve um chat pessoal no Telegram e um canal de Slack da equipa a partir da mesma memória.

Salte a canalização do Slack

Os passos do Slack em si são simples, mas continua a ser dono do host: backups, TLS para o dashboard, rotação de logs e a cadência de upgrades. Para uma instalação pessoal está bem. Para uma equipa que quer o bot vivo em minutos e zero carga operacional depois, o Hermify provisiona um runtime gerido do Hermes, encripta os seus tokens do Slack em repouso, expõe a allowlist numa UI em vez de um .env e mantém a ligação de Socket Mode saudável num servidor persistente.

Você traz o workspace do Slack e uma chave de API de provedor; a plataforma trata de tudo o que está por baixo. Se está a avaliar esse trade-off, a comparação entre self-hosting e gerido percorre os números de custo e manutenção.