Como configurar o Hermes Agent no Discord (Bot + Voz)

Por que rodar o Hermes Agent no Discord

Se seu projeto, seu estúdio ou seus amigos já vivem em um servidor do Discord, é lá que o seu agente precisa estar acessível. Threads, canais de voz e salas fechadas por cargo dão ao Hermes um contexto que um dashboard isolado não consegue: quem está perguntando, em qual canal está, se está falando ou digitando, e onde a resposta deve cair.

O Hermes Agent traz suporte de primeira ao Discord, cobrindo tanto o lado do texto quanto o da voz de um servidor. O runtime se conecta para fora ao Discord pelo Gateway WebSocket padrão, então ele pode viver no seu notebook, em um VPS pequeno ou atrás do NAT de casa e ainda receber mensagens em tempo real. Não precisa expor webhook público nem abrir porta de entrada. O mesmo runtime que responde a mensagens de texto pode também entrar em um canal de voz com /voice join, escutar pelo STT e responder em voz alta pelo TTS.

Este guia percorre o setup completo do começo ao fim: criar o application do Discord, gerar o token do bot, habilitar os intents que o Discord exige em silêncio, configurar a allowlist e o canal home, convidar o bot com a URL de OAuth2 correta e os erros que pegam quem está deployando pela primeira vez.

O que você precisa antes de começar

Um deploy limpo no Discord precisa de cinco coisas prontas:

Um servidor do Discord onde você tenha permissão para adicionar bots. Se não for seu, peça para o admin, a URL de convite só funciona para quem tem "Gerenciar servidor" no servidor de destino.
Uma instalação do Hermes Agent rodando. O guia do Hermes Agent com Docker é o caminho mais limpo para subir uma; se você está no Windows, o setup com WSL2 é o equivalente.
Uma chave de provedor de modelo. Servem Anthropic, OpenAI, OpenRouter ou qualquer endpoint compatível com OpenAI. O runtime usa isso para de fato responder as mensagens.
Seu ID numérico de usuário do Discord para a allowlist (Modo desenvolvedor → clique com o direito no seu nome → Copiar ID do usuário).
Cerca de 15 minutos para a primeira instalação. Redeploys depois disso levam menos de um minuto.

Passo 1 - Crie o application do Discord e o bot

Abra o portal do desenvolvedor do Discord, clique em New Application, dê um nome (por exemplo, hermes-agent) e aceite os termos de desenvolvedor. Isso cria um container de aplicação que vai guardar o usuário bot, as credenciais OAuth2 e o token.

Na página do application, vá em Bot no menu lateral. O Discord não exige mais clicar em Add Bot em applications novos: o usuário bot é criado automaticamente. O que você precisa fazer é dar um nome de exibição, um avatar e desligar Public Bot se quiser que a URL de convite só seja usada por quem você decidir.

Depois clique em Reset Token para revelar o token do bot. Ele começa com MTA…. Copie uma vez e cole direto no seu .env: o Discord nunca mais vai te mostrar, só deixar gerar de novo.

Trate esse token como uma chave SSH. Quem tiver ele pode agir como o seu bot, ler todas as mensagens de todos os canais em que ele está e queimar seus tokens do provedor de modelo disparando o agente.

Passo 2 - Habilite os intents que o Discord exige

Esse é o passo que quebra em silêncio a maioria dos deploys de bots no Discord. O Discord divide "o que o Discord manda para seu bot" em intents. Alguns deles são privilegiados, ou seja, você precisa habilitar explicitamente para cada application, ou o Discord vai conectar o WebSocket, entregar os eventos e simplesmente zerar os campos que você não pediu.

Ainda em Bot, desça até Privileged Gateway Intents e habilite:

Message Content Intent - obrigatório para ler o texto das mensagens. Sem ele, o Hermes recebe os eventos de mensagem com o conteúdo vazio e fica mudo para sempre.
Server Members Intent - obrigatório para resolver a allowlist contra os IDs reais e para ver quando membros entram ou saem.
Presence Intent - opcional, útil se você quiser que o bot reaja quando alguém fica online ou entra em um canal de voz.

Clique em Save Changes lá embaixo. Isso tem de ser feito no portal de desenvolvedor: não existe interruptor no .env.

Quando o seu bot estiver verificado e em mais de 100 servidores, o Discord vai te obrigar a solicitar esses intents. Abaixo desse limite, basta ligar os toggles.

Passo 3 - Descubra seu ID numérico de usuário do Discord

O Hermes Agent só responde a IDs que apareçam em DISCORD_ALLOWED_USERS. É o controle de segurança mais importante do setup inteiro, e ele espera IDs numéricos, não @handles.

No Discord, abra Configurações do usuário → Avançado → ligue Modo de desenvolvedor. Feche as configurações, clique com o direito no seu nome em qualquer canal ou lista de membros e escolha Copiar ID do usuário. O ID tem essa cara: 284102345871466496. Repita para cada pessoa que você queira autorizar.

Pular a allowlist é o mesmo que publicar a chave do seu provedor na cara do servidor inteiro. Se uma instância do Hermes é acessível a partir de um servidor público com a allowlist vazia, toda mensagem que o bot conseguir ler vai queimar seus tokens e, em um canal de voz, todo ruído que ele escutar vai ser transcrito.

Passo 4 - Configure o runtime do Hermes

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

DISCORD_BOT_TOKEN=MTA...seu-bot-token...
DISCORD_ALLOWED_USERS=284102345871466496,297811223344556677
DISCORD_HOME_CHANNEL=123456789012345678
DISCORD_HOME_CHANNEL_NAME="#bot-updates"

Uma nota sobre cada um:

DISCORD_BOT_TOKEN - o token que você copiou no Passo 1.
DISCORD_ALLOWED_USERS - lista separada por vírgulas de IDs numéricos. O bot ignora todo mundo fora dessa lista, incluindo admins do servidor e outros bots.
DISCORD_HOME_CHANNEL (opcional) - o ID do canal para mensagens proativas, saídas de tarefas agendadas e notificações de skills. Clique com o direito no canal no Discord → Copiar ID do canal. Se não definir, a saída proativa vai para o DM do bot com o primeiro usuário autorizado.
DISCORD_HOME_CHANNEL_NAME (opcional) - um rótulo humano usado nos logs, não afeta o roteamento.

chmod 600 ~/.hermes/.env depois de salvar. O token dá acesso total ao seu bot; trate como uma chave SSH.

Passo 5 - Convide o bot para o seu servidor

Bots não entram em servidores, eles são convidados por uma URL de OAuth2 que pede de cara os scopes e permissões certos. Os que o Hermes espera são:

Scopes: bot e applications.commands (o segundo habilita os slash commands /voice).
Permissions integer: 274878286912, que cobre Ver canais, Enviar mensagens, Incorporar links, Anexar arquivos, Ler histórico de mensagens, Enviar mensagens em threads e Adicionar reações.

Pegue o Client ID da sua aplicação em General Information no portal e coloque neste template:

https://discord.com/oauth2/authorize?client_id=YOUR_APP_ID&scope=bot+applications.commands&permissions=274878286912

Abra a URL, escolha o servidor, confirme as permissões e o Discord solta o bot lá dentro como mais um membro. Dá para montar a URL pelo OAuth2 → URL Generator do portal se preferir marcar caixinhas: o resultado é o mesmo.

Para voz, você também vai querer Conectar e Falar no canal de voz específico que pretende usar. Se faltarem depois do convite, adicione um cargo ao bot que conceda esses ou edite direto as substituições de permissão do canal.

Passo 6 - Suba o gateway e mande a primeira mensagem

Reinicie o gateway para pegar o novo ambiente:

hermes gateway restart

Ou, com Docker Compose:

docker compose restart gateway

Acompanhe os logs e espere o handshake do Discord:

hermes gateway logs --follow

Você quer ver duas linhas, nesta ordem:

discord: connecting to Gateway
discord: connected as seu-nome-bot#1234 (guilds: 1)

Se você vê só a primeira e nada depois, o token está errado ou foi rotacionado. Se o bot conecta mas não responde no canal, ou Message Content Intent continua desligado no portal, ou o seu ID não está em DISCORD_ALLOWED_USERS.

Com ele no ar, mande um DM ou marque com @ em um canal que ele consiga ver. O Hermes responde na mesma conversa, com toda a memória e o contexto de skills intactos. Daqui em diante, todas as capacidades do Hermes, memória persistente, tarefas agendadas e skills personalizadas, funcionam igualzinho ao que rola na superfície do Telegram.

Passo 7 - Ligue a voz (opcional, mas divertido)

Os canais de voz do Discord são uma superfície de primeira para o Hermes. Com o bot no servidor com Conectar e Falar, entre você num canal de voz e, em qualquer canal de texto onde o bot consiga ler, escreva:

/voice join

O bot vai entrar no canal de voz em que você está, começar a escutar pelo provedor de STT que você configurou e responder em voz alta pelo TTS. A superfície de comandos é:

/voice join - entra no seu canal de voz atual.
/voice channel - apelido de /voice join.
/voice leave - desconecta do canal de voz.
/voice status - informa se o modo voz está ativo e em qual canal o bot está.

Só usuários em DISCORD_ALLOWED_USERS são transcritos; o áudio dos demais é ignorado, o que importa se o canal de voz é compartilhado com gente que você não autorizou explicitamente. Para escolher um stack STT/TTS que se dê bem com o stream Opus do Discord, o panorama do modo voz do Hermes é a próxima leitura.

Os erros que pegam primeiro

Cinco erros explicam quase todos os tópicos de "meu setup do Discord está quebrado":

Message Content Intent ainda desligado. O bot conecta, entra no servidor e não responde a nada. O Discord não avisa. Ligue no portal e reinicie o gateway.

DISCORD_ALLOWED_USERS vazio. O padrão é ignorar todo mundo. É um default seguro de propósito, mas faz o bot parecer quebrado para quem está testando pela primeira vez e esqueceu de adicionar o próprio ID.

Permissões erradas no convite. Se o bot não enxerga o canal ou não tem Enviar mensagens, ele fica mudo mesmo para usuários autorizados. Re-convide com o permissions integer 274878286912 ou ajuste o cargo em Configurações do servidor → Cargos.

Permissões de voz faltando em um canal específico. O bot tem Conectar e Falar no nível do servidor, mas uma substituição do canal tira essas permissões. O Discord mostra o bot como "conectado" mas não produz áudio em nenhuma direção. Confira a aba de permissões do canal de voz.

Dois processos de gateway contra o mesmo volume de dados. Se você sobe um gateway em modo Discord e outro em modo Telegram contra o mesmo diretório /data, a ordem das mensagens e as escritas de memória se corrompem entre si em minutos. Rode um único gateway com os blocos DISCORD_* e TELEGRAM_* juntos no .env se quiser as duas superfícies: o runtime multiplexa nativamente.

Se o problema parece do Discord mas os sintomas soam gerais, o guia de troubleshooting do Telegram cobre os problemas de gateway e provedor com mais profundidade, e a maioria independe da superfície.

Discord e Telegram, lado a lado

Aspecto	Discord	Telegram
Tempo de setup	15 min (app + intents + convite)	5 min (um token do BotFather)
Alcance	Atrás de firewall (Gateway WebSocket)	Atrás de firewall (long-poll)
Campo da allowlist	`DISCORD_ALLOWED_USERS` (IDs numéricos)	`TELEGRAM_ALLOWED_USERS` (IDs numéricos)
Melhor para	Comunidades, salas de voz, servidores de projeto	Uso pessoal, mobile-first, áudios
Threads	Nativas (canais + threads)	Só respostas citadas
Voz	Entrar no canal de voz, STT/TTS ao vivo	Áudios, respostas transcritas

As duas superfícies não são excludentes. O mesmo runtime do Hermes pode servir as duas ao mesmo tempo, útil quando um chat pessoal no Telegram e uma sala de voz compartilhada no Discord bebem do mesmo armazém de memória.

Pule o encanamento do Discord

Os passos em si são diretos, mas você continua dono do host: backups, TLS do dashboard, rotação de logs e a cadência de atualização. Para uma instalação pessoal isso é ok. Para um servidor que quer o bot no ar em minutos e sem custo operacional depois, a Hermify provisiona um runtime do Hermes gerenciado no Telegram, mantém a memória persistente e rotaciona os tokens sem você tocar no .env.

Você entra com a chave do provedor de modelo e a superfície que quiser usar; a plataforma cuida de tudo por baixo. Se você está avaliando esse trade-off antes de investir no seu próprio VPS, a comparação de self-hosting vs gerenciado percorre os números de custo e manutenção.