Pular para o conteúdo principal

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

Configuração do Discord

O Hermes Agent se integra ao Discord como um bot, o que permite conversar com o seu assistente de IA por mensagens diretas ou por canais de servidor. O bot recebe as suas mensagens, processa cada uma pelo pipeline do Hermes Agent (incluindo uso de ferramentas, memória e raciocínio) e responde em tempo real. Ele aceita texto, mensagens de voz, anexos de arquivo e comandos de barra.

Antes da configuração, vem a parte que quase todo mundo quer saber: como o Hermes se comporta depois de entrar no seu servidor.

Como o Hermes se comporta​

ContextoComportamento
Mensagens diretas (DMs)O Hermes responde a toda mensagem. Não precisa de @menção. Cada DM tem a sua própria sessão.
Canais de servidorPor padrão, o Hermes só responde quando você faz uma @menção a ele. Se você publicar em um canal sem mencioná-lo, o Hermes ignora a mensagem.
Canais de resposta livreVocê pode liberar canais específicos da menção com DISCORD_FREE_RESPONSE_CHANNELS, ou desligar a exigência de menção globalmente com DISCORD_REQUIRE_MENTION=false. As mensagens nesses canais são respondidas ali mesmo — o threading automático é pulado para o canal continuar sendo um bate-papo leve.
ThreadsO Hermes responde na mesma thread. As regras de menção continuam valendo, a não ser que aquela thread ou o canal pai esteja configurado como de resposta livre. As threads ficam isoladas do canal pai no histórico de sessão.
Canais compartilhados com vários usuáriosPor padrão, o Hermes isola o histórico de sessão por usuário dentro do canal, por segurança e clareza. Duas pessoas conversando no mesmo canal não compartilham uma transcrição, a menos que você desligue isso explicitamente.
Mensagens que mencionam outros usuáriosQuando DISCORD_IGNORE_NO_MENTION é true (o padrão), o Hermes fica calado se a mensagem faz @menção a outros usuários mas não menciona o bot. Isso evita que o bot entre em conversas dirigidas a outras pessoas. Defina como false se quiser que o bot responda a todas as mensagens, independentemente de quem foi mencionado. Isso só vale em canais de servidor, não em DMs.
dica

Se você quer um canal normal de ajuda do bot, onde as pessoas conversem com o Hermes sem marcá-lo toda vez, adicione esse canal a DISCORD_FREE_RESPONSE_CHANNELS.

O modelo de gateway do Discord​

O Hermes no Discord não é um webhook que responde sem estado. Ele roda pelo gateway de mensagens completo, o que significa que toda mensagem recebida passa por:

  1. autorização (DISCORD_ALLOWED_USERS)
  2. verificação de menção / resposta livre
  3. busca da sessão
  4. carregamento da transcrição da sessão
  5. execução normal do agente Hermes, incluindo ferramentas, memória e comandos de barra
  6. entrega da resposta de volta ao Discord

Isso importa porque, em um servidor movimentado, o comportamento depende tanto do roteamento do Discord quanto da política de sessão do Hermes.

O modelo de sessão no Discord​

Por padrão:

  • cada DM ganha a sua própria sessão
  • cada thread de servidor ganha o seu próprio espaço de nomes de sessão
  • cada usuário em um canal compartilhado ganha a sua própria sessão dentro daquele canal

Então, se Alice e Bob conversam com o Hermes em #research, o Hermes trata essas conversas como separadas por padrão, mesmo elas acontecendo no mesmo canal visível do Discord.

Isso é controlado pelo config.yaml:

group_sessions_per_user: true

Defina como 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 dividem 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
  • a execução em andamento de uma pessoa pode interromper a continuação de outra na mesma sala

Interrupções e concorrência​

O Hermes rastreia os agentes em execução pela chave de sessão.

Com o padrão group_sessions_per_user: true:

  • se Alice interromper a própria requisição em andamento, isso só afeta a sessão da Alice naquele canal
  • Bob pode continuar falando no mesmo canal sem herdar o histórico da Alice nem interromper a execução dela

Com group_sessions_per_user: false:

  • a sala inteira compartilha uma única vaga de agente em execução para aquele canal/thread
  • mensagens de continuação de pessoas diferentes podem interromper umas às outras ou ficar na fila

Este guia leva você pelo processo completo de configuração — de criar o seu bot no Portal do Desenvolvedor do Discord até enviar a sua primeira mensagem.

Saúde do WebSocket do Gateway​

O REST do Discord e o WebSocket do Gateway são transportes separados. Uma resposta REST bem-sucedida (inclusive fetch_user() retornando HTTP 200) não prova que o bot ainda consegue receber eventos do Gateway. Por isso o Hermes combina o estado de prontidão, o estado de fechamento do cliente/socket, se o socket está aberto, a idade do último ACK de heartbeat e a latência finita de heartbeat.

Depois do número configurado de amostras consecutivas com problema, o adaptador emite um único evento fatal passível de nova tentativa. O observador de reconexão do gateway já existente cria um adaptador novo; o adaptador do Discord não inicia um segundo laço de reconexão sem limite.

Configure os limiares não secretos no config.yaml:

discord:
  websocket_liveness_interval_seconds: 15
  websocket_liveness_failure_threshold: 2
  websocket_heartbeat_ack_max_age_seconds: 60
  websocket_max_latency_seconds: 30

Os nomes antigos liveness_interval_seconds e liveness_failure_threshold continuam existindo apenas como apelidos de compatibilidade; eles não significam mais sondagem via REST.

Passo 1: crie um aplicativo no Discord​

  1. Vá até o Portal do Desenvolvedor do Discord e entre com a sua conta do Discord.
  2. Clique em New Application no canto superior direito.
  3. Digite um nome para o seu aplicativo (por exemplo, "Hermes Agent") e aceite os Termos de Serviço do Desenvolvedor.
  4. Clique em Create.

Você vai cair na página General Information. Anote o Application ID — você vai precisar dele depois para montar a URL de convite.

Passo 2: crie o bot​

  1. Na barra lateral esquerda, clique em Bot.
  2. O Discord cria automaticamente um usuário de bot para o seu aplicativo. Você vai ver o nome de usuário do bot, que pode ser personalizado.
  3. Em Authorization Flow:
    • Deixe Public Bot em ON — necessário para usar o link de convite fornecido pelo Discord (recomendado). Isso permite que a aba Installation gere uma URL de autorização padrão.
    • Deixe Require OAuth2 Code Grant em OFF.
dica

Nessa página você pode definir um avatar e um banner personalizados para o seu bot. É isso que os usuários vão ver no Discord.

Alternativa com bot privado

Se você prefere manter o bot privado (Public Bot = OFF), você precisa usar o método da URL manual no Passo 5, em vez da aba Installation. O link fornecido pelo Discord exige Public Bot habilitado.

Passo 3: habilite os Privileged Gateway Intents​

Este é o passo mais crítico de toda a configuração. Sem os intents corretos habilitados, o seu bot vai se conectar ao Discord mas não vai conseguir ler o conteúdo das mensagens.

Na página Bot, role até Privileged Gateway Intents. Você vai ver três chaves:

IntentPara que serveObrigatório?
Presence IntentVer o status online/offline dos usuáriosOpcional
Server Members IntentAcessar a lista de membros, resolver nomes de usuárioObrigatório
Message Content IntentLer o conteúdo em texto das mensagensObrigatório

Habilite tanto o Server Members Intent quanto o Message Content Intent, colocando os dois em ON.

  • Sem o Message Content Intent, o seu bot recebe os eventos de mensagem mas o texto vem vazio — o bot literalmente não consegue ver o que você digitou.
  • Sem o Server Members Intent, o bot não consegue resolver nomes de usuário para a lista de usuários permitidos e pode falhar ao identificar quem está falando com ele.
Este é o motivo nº 1 de bots do Discord não funcionarem

Se o seu bot está online mas nunca responde às mensagens, o Message Content Intent está quase certamente desligado. Volte ao Portal do Desenvolvedor, selecione o seu aplicativo → Bot → Privileged Gateway Intents e confirme que o Message Content Intent está em ON. Clique em Save Changes.

Sobre a quantidade de servidores:

  • Se o seu bot está em menos de 100 servidores, você pode ligar e desligar os intents à vontade.
  • Se o seu bot está em 100 servidores ou mais, o Discord exige que você envie um pedido de verificação para usar intents privilegiados. Para uso pessoal, isso não é um problema.

Clique em Save Changes no fim da página.

Passo 4: pegue o token do bot​

O token do bot é a credencial que o Hermes Agent usa para entrar como o seu bot. Ainda na página Bot:

  1. Na seção Token, clique em Reset Token.
  2. Se você tem autenticação em dois fatores na sua conta do Discord, digite o código 2FA.
  3. O Discord vai exibir o seu novo token. Copie na hora.
O token aparece uma vez só

O token é exibido uma única vez. Se você perdê-lo, vai precisar redefini-lo e gerar um novo. Nunca compartilhe o seu token publicamente nem faça commit dele no Git — quem tem esse token tem controle total do seu bot.

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

Passo 5: gere a URL de convite​

Você precisa de uma URL OAuth2 para convidar o bot para o seu servidor. Existem dois caminhos:

Exige Public Bot

Este método exige que Public Bot esteja em ON, como no Passo 2. Se você deixou Public Bot em OFF, use o método da URL manual abaixo.

  1. Na barra lateral esquerda, clique em Installation.
  2. Em Installation Contexts, habilite Guild Install.
  3. Em Install Link, selecione Discord Provided Link.
  4. Em Default Install Settings para Guild Install:
    • Scopes: selecione bot e applications.commands
    • Permissions: selecione as permissões listadas abaixo.

Opção B: URL manual​

Você pode montar a URL de convite diretamente, neste formato:

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

Troque YOUR_APP_ID pelo Application ID do Passo 1.

Permissões obrigatórias​

Estas são as permissões mínimas de que o seu bot precisa:

  • View Channels — enxergar os canais a que tem acesso
  • Send Messages — responder às suas mensagens
  • Embed Links — formatar respostas ricas
  • Attach Files — enviar imagens, áudio e arquivos de saída
  • Read Message History — manter o contexto da conversa
  • Send Messages in Threads — responder em conversas dentro de threads
  • Add Reactions — reagir às mensagens como forma de confirmação

Inteiros de permissão​

NívelInteiro de permissõesO que inclui
Mínimo117760View Channels, Send Messages, Read Message History, Attach Files
Recomendado274878286912Tudo acima mais Embed Links, Send Messages in Threads, Add Reactions

Passo 6: convide para o seu servidor​

  1. Abra a URL de convite no navegador (a da aba Installation ou a URL manual que você montou).
  2. No menu Add to Server, selecione o seu servidor.
  3. Clique em Continue e depois em Authorize.
  4. Resolva o CAPTCHA, se aparecer.
informação

Você precisa da permissão Manage Server no servidor do Discord para convidar um bot. Se o seu servidor não aparecer na lista, peça a um administrador do servidor que use o link de convite.

Depois de autorizar, o bot vai aparecer na lista de membros do seu servidor (ele fica como offline até você iniciar o gateway do Hermes).

Passo 7: descubra o seu ID de usuário do Discord​

O Hermes Agent usa o seu ID de usuário do Discord para controlar quem pode interagir com o bot. Para descobri-lo:

  1. Abra o Discord (aplicativo de desktop ou web).
  2. Vá em Settings → Advanced → coloque Developer Mode em ON.
  3. Feche as configurações.
  4. Clique com o botão direito no seu próprio nome de usuário (em uma mensagem, na lista de membros ou no seu perfil) → Copy User ID.

O seu ID de usuário é um número longo, como 284102345871466496.

dica

O Developer Mode também permite copiar IDs de canal e IDs de servidor do mesmo jeito — clique com o botão direito no nome do canal ou do servidor e escolha Copy ID. Você vai precisar de um ID de canal se quiser definir um canal padrão manualmente.

Passo 8: configure o Hermes Agent​

Rode o comando guiado de configuração:

hermes gateway setup

Escolha Discord quando for perguntado, depois cole o token do bot e o seu ID de usuário.

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

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

# Obrigatório
DISCORD_BOT_TOKEN=seu-token-de-bot
DISCORD_ALLOWED_USERS=284102345871466496

# Vários usuários permitidos (separados por vírgula)
# DISCORD_ALLOWED_USERS=284102345871466496,198765432109876543

Depois inicie o gateway:

hermes gateway

O bot deve ficar online no Discord em alguns segundos. Mande uma mensagem para ele — uma DM ou em um canal que ele enxergue — para testar.

dica

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

Referência de configuração​

O comportamento do Discord é controlado por dois arquivos: ~/.hermes/.env para credenciais e chaves de ambiente, e ~/.hermes/config.yaml para ajustes estruturados. As variáveis de ambiente sempre têm precedência sobre os valores do config.yaml quando as duas fontes estão definidas.

Variáveis de ambiente (.env)​

VariávelObrigatóriaPadrãoDescrição
DISCORD_BOT_TOKENSim—Token do bot obtido no Portal do Desenvolvedor do Discord.
DISCORD_ALLOWED_USERSCondicional—IDs de usuário do Discord, separados por vírgula, autorizados a interagir com o bot. Sem isso ou sem DISCORD_ALLOWED_ROLES, o gateway nega todos os usuários, a menos que DISCORD_ALLOW_ALL_USERS=true, GATEWAY_ALLOW_ALL_USERS=true ou DISCORD_ALLOWED_CHANNELS delimite explicitamente o acesso no servidor.
DISCORD_ALLOWED_ROLESNão—IDs de cargo do Discord, separados por vírgula. Qualquer membro com um desses cargos está autorizado — semântica de OU com DISCORD_ALLOWED_USERS. Habilita automaticamente o Server Members Intent na conexão. Útil quando o time de moderação muda muito: moderadores novos ganham acesso assim que o cargo é concedido, sem precisar publicar configuração nova.
DISCORD_ALLOW_ALL_USERSNãofalseAdesão explícita para permitir todo usuário do Discord que consiga alcançar o bot. Isso restaura o comportamento aberto de antes da 0.18 apenas para o Discord; use só em servidores confiáveis/privados ou em desenvolvimento.
GATEWAY_ALLOW_ALL_USERSNãofalseAdesão global de "permitir todos" para toda plataforma de gateway. Prefira a variável específica de plataforma DISCORD_ALLOW_ALL_USERS, a menos que você queira mesmo abrir todas as plataformas conectadas.
DISCORD_HOME_CHANNELNão—ID do canal onde o bot envia mensagens proativas (saída de cron, lembretes, notificações).
DISCORD_HOME_CHANNEL_NAMENão"Home"Nome de exibição do canal padrão nos logs e na saída de status.
DISCORD_COMMAND_SYNC_POLICYNão"safe"Controla a sincronização de comandos de barra nativos na inicialização. "safe" compara os comandos globais existentes e só atualiza o que mudou, recriando comandos quando mudanças de metadados do Discord não podem ser aplicadas por patch. "bulk" preserva o comportamento antigo de tree.sync(). "off" pula a sincronização de inicialização por completo.
DISCORD_REQUIRE_MENTIONNãotrueQuando true, o bot só responde em canais de servidor se receber uma @menção. Defina como false para responder a todas as mensagens em todos os canais.
DISCORD_THREAD_REQUIRE_MENTIONNãofalseQuando true, o atalho de menção dentro da thread é desativado — as threads passam a ser barradas como os canais, exigindo @menção mesmo depois de o bot já ter participado. Use isso quando vários bots dividem uma thread e você quer que cada um só dispare com @menção explícita.
DISCORD_FREE_RESPONSE_CHANNELSNão—IDs de canal, separados por vírgula, onde o bot responde sem exigir @menção, mesmo com DISCORD_REQUIRE_MENTION em true.
DISCORD_IGNORE_NO_MENTIONNãotrueQuando true, o bot fica calado se a mensagem faz @menção a outros usuários mas não menciona o bot. Evita que o bot entre em conversas dirigidas a outras pessoas. Só vale em canais de servidor, não em DMs.
DISCORD_AUTO_THREADNãotrueQuando true, cria automaticamente uma thread nova para cada @menção em um canal de texto, de modo que cada conversa fique isolada (parecido com o comportamento do Slack). Mensagens que já estão dentro de threads ou em DMs não são afetadas.
DISCORD_ALLOW_BOTSNão"none"Controla como o bot trata mensagens de outros bots do Discord. "none" — ignora todos os outros bots. "mentions" — só aceita mensagens de bot que fazem @menção ao Hermes. "all" — aceita todas as mensagens de bot.
DISCORD_REACTIONSNãotrueQuando true, o bot adiciona reações em emoji às mensagens durante o processamento (👀 ao começar, ✅ em caso de sucesso, ❌ em caso de erro). Defina como false para desativar as reações por completo.
DISCORD_IGNORED_CHANNELSNão—IDs de canal, separados por vírgula, onde o bot nunca responde, mesmo com @menção. Tem prioridade sobre todas as outras configurações de canal.
DISCORD_ALLOWED_CHANNELSNão—IDs de canal separados por vírgula. Quando definida, o bot só responde nesses canais (mais as DMs, se permitidas). Sobrepõe o discord.allowed_channels do config.yaml. Combine com DISCORD_IGNORED_CHANNELS para expressar regras de permissão/negação.
DISCORD_NO_THREAD_CHANNELSNão—IDs de canal, separados por vírgula, onde o bot responde direto no canal em vez de criar uma thread. Só é relevante quando DISCORD_AUTO_THREAD está em true.
DISCORD_HISTORY_BACKFILLNãotrueQuando true, acrescenta ao início da mensagem do usuário o histórico recente do canal (desde a última resposta do bot) quando o bot é mencionado. Recupera o contexto que o bot perderia com require_mention. É pulado em DMs e em canais de resposta livre. Defina como false para desativar.
DISCORD_HISTORY_BACKFILL_LIMITNão50Número máximo de mensagens a varrer para trás ao montar o bloco de recuperação. Na prática a varredura normalmente para antes — na última mensagem do próprio bot no canal.
DISCORD_REPLY_TO_MODENão"first"Controla o comportamento de referência de resposta: "off" — nunca responder à mensagem original, "first" — referência de resposta só no primeiro pedaço da mensagem (padrão), "all" — referência de resposta em todos os pedaços.
DISCORD_ALLOW_MENTION_EVERYONENãofalseQuando false (padrão), o bot não pode marcar @everyone nem @here, mesmo que a resposta contenha esses termos. Defina como true para reativar. Veja Controle de menções abaixo.
DISCORD_ALLOW_MENTION_ROLESNãofalseQuando false (padrão), o bot não pode marcar menções a @role. Defina como true para permitir.
DISCORD_ALLOW_MENTION_USERSNãotrueQuando true (padrão), o bot pode marcar usuários individuais pelo ID.
DISCORD_ALLOW_MENTION_REPLIED_USERNãotrueQuando true (padrão), responder a uma mensagem marca o autor original.
DISCORD_PROXYNão—URL de proxy para as conexões com o Discord (HTTP, WebSocket, REST). Sobrepõe HTTPS_PROXY/ALL_PROXY. Aceita os esquemas http://, https:// e socks5://.
DISCORD_ALLOW_ANY_ATTACHMENTNãofalseQuando true, o bot aceita anexos de qualquer tipo de arquivo (não só a lista embutida de PDF/texto/zip/office). Tipos desconhecidos são guardados em disco e apresentados ao agente como um caminho local com MIME application/octet-stream, para que ele possa inspecioná-los com terminal / read_file / ffprobe / etc.
DISCORD_MAX_ATTACHMENT_BYTESNão33554432Número máximo de bytes por anexo que o gateway vai baixar e guardar em cache. O padrão é 32 MiB. Defina 0 para não ter limite (os anexos são mantidos em memória enquanto são gravados, então "ilimitado" tem um custo real de memória).
HERMES_DISCORD_TEXT_BATCH_DELAY_SECONDSNão0.6Janela de tolerância que o adaptador espera antes de despachar um pedaço de texto na fila. Útil para suavizar a saída em streaming.
HERMES_DISCORD_TEXT_BATCH_SPLIT_DELAY_SECONDSNão2.0Atraso entre pedaços divididos quando uma única mensagem passa do limite de tamanho do Discord.
Conversa entre bots não é suportada

DISCORD_ALLOW_BOTS existe para aceitar entrada de um bot confiável específico (por exemplo, um bot de repasse ou de webhook), não para deixar dois perfis do Hermes conversarem entre si. O padrão, "none", ignora todos os outros bots e é a configuração segura.

Ligar vários perfis do Hermes para responderem uns aos outros em um canal compartilhado — definindo "mentions" ou "all" em vários perfis — é uma topologia não suportada. O Discord faz @menção automática ao autor respondido em toda resposta, então, com "mentions", dois bots vão satisfazer indefinidamente a exigência de menção um do outro e entrar em um laço de confirmações. Não existe disjuntor para isso, porque a configuração suportada é simplesmente deixar DISCORD_ALLOW_BOTS em "none". Se você precisa mesmo aceitar um bot específico, delimite a aceitação de forma bem restrita e nunca a outro agente que responde automaticamente.

Arquivo de configuração (config.yaml)​

A seção discord em ~/.hermes/config.yaml espelha as variáveis de ambiente acima. Os ajustes do config.yaml são aplicados como padrões — se a variável de ambiente equivalente já estiver definida, ela vence.

# Ajustes específicos do Discord
discord:
  require_mention: true           # Exigir @menção em canais de servidor
  thread_require_mention: false   # Se true, exigir @menção também nas threads (threads com vários bots)
  free_response_channels: ""      # IDs de canal separados por vírgula (ou lista YAML)
  auto_thread: true               # Criar threads automaticamente na @menção
  reactions: true                 # Adicionar reações em emoji durante o processamento
  ignored_channels: []            # IDs de canal onde o bot nunca responde
  no_thread_channels: []          # IDs de canal onde o bot responde sem criar thread
  history_backfill: true          # Acrescentar histórico recente do canal na menção (padrão: true)
  history_backfill_limit: 50      # Máximo de mensagens a varrer para trás (padrão: 50)
  missed_message_backfill:        # Reproduzir mensagens perdidas durante a desconexão (opcional)
    enabled: false
    channels: []                  # Vazio usa free_response_channels
    window_seconds: 21600         # Olhar no máximo 6 horas para trás
    limit: 100                    # Limite global de varredura por reconexão
    max_dispatches: 10            # Limite de despachos de recuperação por reconexão
  channel_prompts: {}             # Prompts de sistema efêmeros por canal
  voice_channel_inactivity_timeout_seconds: 300  # Use 0 para ficar no canal de voz até um /voice leave explícito
  voice_playback_timeout_seconds: 120             # Piso do vigia de reprodução; áudios longos ganham duração+folga
  allow_mentions:                 # O que o bot tem permissão de marcar (padrões seguros)
    everyone: false               # Marcações de @everyone / @here (padrão: false)
    roles: false                  # Marcações de @role (padrão: false)
    users: true                   # Marcações de @user (padrão: true)
    replied_user: true            # A referência de resposta marca o autor (padrão: true)

# Isolamento de sessão (vale para todas as plataformas de gateway, não só o Discord)
group_sessions_per_user: true     # Isolar as sessões por usuário em canais compartilhados

discord.require_mention​

Tipo: booleano — Padrão: true

Quando habilitado, o bot só responde em canais de servidor se receber uma @menção direta. As DMs sempre recebem resposta, independentemente desse ajuste.

discord.thread_require_mention​

Tipo: booleano — Padrão: false

Por padrão, depois que o bot participa de uma thread (criada automaticamente por @menção ou respondida uma vez), ele continua respondendo a toda mensagem seguinte daquela thread sem precisar de nova @menção. Esse é o padrão certo para conversas de um para um.

Em threads com vários bots, onde os usuários se dirigem a um bot por vez, esse padrão vira uma armadilha — todos os outros bots da thread também disparam em cada mensagem, queimando créditos e enchendo o canal. Defina thread_require_mention: true para desativar o atalho dentro da thread e barrar as threads do mesmo jeito que os canais. As @menções explícitas continuam funcionando como antes.

discord:
  require_mention: true
  thread_require_mention: true    # configuração com vários bots

discord.free_response_channels​

Tipo: string ou lista — Padrão: ""

IDs de canal onde o bot responde a todas as mensagens sem precisar de @menção. Aceita uma string separada por vírgulas ou uma lista YAML:

# Formato em string
discord:
  free_response_channels: "1234567890,9876543210"

# Formato em lista
discord:
  free_response_channels:
    - 1234567890
    - 9876543210

Se o canal pai de uma thread estiver nessa lista, a thread também fica livre de menção.

Canais de resposta livre também pulam o threading automático — o bot responde ali mesmo, em vez de abrir uma thread nova por mensagem. Isso mantém o canal utilizável como uma superfície leve de bate-papo. Se você quer o comportamento com threads, não liste o canal como de resposta livre (use o fluxo normal de @menção).

discord.auto_thread​

Tipo: booleano — Padrão: true

Quando habilitado, cada @menção em um canal de texto comum cria automaticamente uma thread nova para a conversa. Isso mantém o canal principal limpo e dá a cada conversa o seu próprio histórico de sessão isolado. Uma vez criada a thread, as mensagens seguintes ali não exigem @menção — o bot sabe que já está participando. Defina thread_require_mention como true para desativar esse atalho em configurações com vários bots.

Mensagens enviadas em threads já existentes ou em DMs não são afetadas por esse ajuste. Canais listados em discord.free_response_channels ou discord.no_thread_channels também escapam do threading automático e recebem respostas ali mesmo.

discord.reactions​

Tipo: booleano — Padrão: true

Controla se o bot adiciona reações em emoji às mensagens como retorno visual:

  • 👀 adicionado quando o bot começa a processar a sua mensagem
  • ✅ adicionado quando a resposta é entregue com sucesso
  • ❌ adicionado se ocorrer um erro durante o processamento

Desative isso se você achar as reações incômodas ou se o cargo do bot não tiver a permissão Add Reactions.

discord.ignored_channels​

Tipo: string ou lista — Padrão: []

IDs de canal onde o bot nunca responde, mesmo com @menção direta. Isso tem a prioridade mais alta — se um canal está nessa lista, o bot ignora silenciosamente todas as mensagens dele, independentemente de require_mention, free_response_channels ou qualquer outro ajuste.

# Formato em string
discord:
  ignored_channels: "1234567890,9876543210"

# Formato em lista
discord:
  ignored_channels:
    - 1234567890
    - 9876543210

Se o canal pai de uma thread estiver nessa lista, as mensagens daquela thread também são ignoradas.

discord.no_thread_channels​

Tipo: string ou lista — Padrão: []

IDs de canal onde o bot responde direto no canal em vez de criar uma thread automaticamente. Isso só tem efeito quando auto_thread está em true (o padrão). Nesses canais, o bot responde ali mesmo, como uma mensagem normal, em vez de abrir uma thread nova.

discord:
  no_thread_channels:
    - 1234567890  # O bot responde aqui mesmo, sem thread

Útil para canais dedicados à interação com o bot, onde threads só acrescentariam ruído.

discord.channel_prompts​

Tipo: mapeamento — Padrão: {}

Prompts de sistema efêmeros por canal, injetados em cada turno no canal ou na thread do Discord correspondente, sem serem gravados no histórico da transcrição.

discord:
  channel_prompts:
    "1234567890": |
      Este canal é para tarefas de pesquisa. Prefira comparações profundas,
      citações e síntese concisa.
    "9876543210": |
      Este fórum é para apoio em estilo terapêutico. Seja acolhedor, com os pés
      no chão e sem julgamento.

Comportamento:

  • Correspondências exatas de ID de thread/canal têm prioridade.
  • Se uma mensagem chega dentro de uma thread ou de um post de fórum e essa thread não tem entrada explícita, o Hermes recorre ao ID do canal/fórum pai.
  • Os prompts são aplicados de forma efêmera em tempo de execução, então mudá-los afeta os turnos seguintes na hora, sem reescrever o histórico de sessão passado.

discord.history_backfill​

Tipo: booleano — Padrão: true

Quando habilitado, o bot recupera as mensagens de canal que perdeu a cada @menção. Com require_mention: true, o bot só processa as mensagens que o marcam diretamente — todo o resto do canal é invisível para a transcrição da sessão. A recuperação de histórico varre para trás o histórico recente do canal quando é acionada, junta as mensagens entre a última resposta do bot e a menção atual, e inclui tudo como contexto.

Comportamento por superfície:

  • Canais de servidor (com require_mention: true): a recuperação varre o canal desde a última resposta do bot. Útil quando outros participantes publicaram enquanto ninguém falava com o bot.
  • Threads: a recuperação varre só a thread — o channel.history() do Discord em uma thread devolve apenas as mensagens daquela thread, não as do canal pai. Esse é o escopo certo, porque threads costumam ser conversas autocontidas.
  • DMs: pulado. Toda mensagem de DM aciona o bot, então a transcrição da sessão já está completa — não existe lacuna de menção para preencher.
  • Canais de resposta livre e threads criadas automaticamente pelo próprio bot: pulados pelo mesmo motivo — sem exigência de menção, não há lacuna.

Sessões por usuário (group_sessions_per_user: true, o padrão) também se beneficiam: a sessão de um usuário não tem o contexto publicado pelos outros participantes do canal nem as mensagens do próprio usuário anteriores ao momento em que ele marcou o bot. A recuperação preenche as duas lacunas.

discord:
  history_backfill: true   # padrão

Para desligar:

discord:
  history_backfill: false

Nota: mensagens que chegam enquanto o bot está processando (entre um acionamento e a resposta dele) não são capturadas. Essa é uma simplificação aceita — o usuário pode reenviar ou marcar de novo.

discord.history_backfill_limit​

Tipo: inteiro — Padrão: 50

Número máximo de mensagens a varrer para trás ao recuperar o contexto do canal. Na prática a varredura normalmente para bem antes — na última mensagem do próprio bot no canal, que é a fronteira natural entre turnos. Esse limite é uma trava de segurança para partidas frias e lacunas longas em que não existe mensagem anterior do bot no histórico recente.

discord:
  history_backfill: true
  history_backfill_limit: 50

discord.missed_message_backfill​

Tipo: objeto — Padrão: desativado

A janela de retomada do WebSocket do Discord pode expirar durante um reinício ou uma queda de rede. As mensagens enviadas nesse intervalo não são entregues como eventos ao vivo do gateway. Quando essa opção está habilitada, o Hermes varre um conjunto delimitado de históricos de canais e threads configurados depois que o Discord reconecta, e então manda as mensagens ainda não tratadas pelo mesmo caminho de autorização, menção, canal, desduplicação e despacho dos eventos ao vivo.

discord:
  missed_message_backfill:
    enabled: true
    channels: ["123456789012345678"]
    window_seconds: 3600
    limit: 100
    max_dispatches: 10

Se channels estiver vazio, o Hermes usa discord.free_response_channels. Defina como "*" só quando o bot deve inspecionar todo canal de texto de servidor que ele alcança. O registro de recuperação é guardado por perfil em gateway/discord_message_recovery.db, o que evita que uma mensagem já respondida com sucesso seja reproduzida de novo depois de um reinício posterior.

group_sessions_per_user​

Tipo: booleano — Padrão: true

Esse é um ajuste global do gateway (não específico do Discord) que controla se usuários no mesmo canal recebem históricos de sessão isolados.

Quando true: Alice e Bob conversando em #research têm cada um a sua conversa separada com o Hermes. Quando false: o canal inteiro compartilha uma única transcrição de conversa e uma única vaga de agente em execução.

group_sessions_per_user: true

Veja a seção Modelo de sessão acima para todas as implicações de cada modo.

display.tool_progress​

Tipo: string — Padrão: "all" — Valores: off, new, all, verbose

Controla se o bot envia mensagens de progresso no chat durante o processamento (por exemplo, "Lendo arquivo...", "Rodando comando no terminal..."). Esse é um ajuste global do gateway que vale para todas as plataformas.

display:
  tool_progress: "all"    # off | new | all | verbose
  • off — nenhuma mensagem de progresso
  • new — mostra só a primeira chamada de ferramenta por turno
  • all — mostra todas as chamadas de ferramenta (truncadas em 40 caracteres nas mensagens do gateway)
  • verbose — mostra os detalhes completos da chamada de ferramenta (pode gerar mensagens longas)

display.tool_progress_command​

Tipo: booleano — Padrão: false

Quando habilitado, deixa o comando de barra /verbose disponível no gateway, o que permite alternar entre os modos de progresso de ferramenta (off → new → all → verbose → off) sem editar o config.yaml.

display:
  tool_progress_command: true

display.reasoning_style​

Tipo: string — Padrão (Discord): "subtext" — Valores: code, blockquote, subtext

Controla como o bloco de raciocínio do modelo é renderizado quando a exibição de raciocínio está habilitada. No Discord o padrão é subtext, que usa o texto de metadados pequeno e cinza nativo do Discord (-# ), para o raciocínio ficar visualmente secundário em relação à resposta. blockquote renderiza como uma citação com >, e code (o padrão nas outras plataformas) usa um bloco de código cercado. Raciocínios longos são reduzidos às primeiras 15 linhas.

display:
  platforms:
    discord:
      reasoning_style: subtext   # code | blockquote | subtext

Controle de acesso aos comandos de barra​

Por padrão, todo usuário permitido pode rodar todo comando de barra. Para dividir a sua lista de permissões entre administradores (acesso total aos comandos de barra) e usuários comuns (só os comandos que você habilitar explicitamente), acrescente allow_admin_from e user_allowed_commands ao bloco extra da plataforma Discord:

gateway:
  platforms:
    discord:
      extra:
        # Lista de usuários já existente (sem mudança)
        allow_from:
          - "123456789012345678"  # ID de usuário administrador
          - "999888777666555444"  # ID de usuário comum

        # NOVO — administradores recebem todos os comandos de barra (embutidos + de plugin)
        allow_admin_from:
          - "123456789012345678"

        # NOVO — usuários permitidos que não são administradores só podem rodar estes comandos de barra.
        # /help e /whoami são sempre permitidos, para o usuário poder ver o seu acesso.
        user_allowed_commands:
          - status
          - model
          - history

        # Opcional: listas separadas de administradores / comandos para canais de servidor
        group_allow_admin_from:
          - "123456789012345678"
        group_user_allowed_commands:
          - status

Comportamento:

  • Um usuário que está em allow_admin_from para um escopo (DM ou canal de servidor) pode rodar todo comando de barra registrado — embutido E registrado por plugin — pelo registro de comandos ao vivo.
  • Um usuário que não está em allow_admin_from só pode rodar os comandos listados em user_allowed_commands, mais o piso sempre permitido: /help e /whoami.
  • O bate-papo comum (mensagens que não são comandos de barra) não é afetado. Usuários que não são administradores continuam podendo falar normalmente com o agente; eles só não conseguem disparar comandos arbitrários.
  • Compatibilidade com o que já existe: se allow_admin_from não estiver definido para um escopo, a limitação de comandos de barra fica desativada nesse escopo. Instalações existentes continuam funcionando sem mudança nenhuma.
  • Ser administrador em DM não implica ser administrador em canal de servidor. Cada escopo tem a sua própria lista de administradores.

Use /whoami para ver o escopo ativo, o seu nível (administrador / usuário / sem restrição) e quais comandos de barra você pode rodar.

Seletor interativo de modelo​

Envie /model sem argumentos em um canal do Discord para abrir um seletor de modelo em forma de lista:

  1. Seleção de provedor — uma lista suspensa com os provedores disponíveis (até 25).
  2. Seleção de modelo — uma segunda lista com os modelos do provedor escolhido (até 25).

O seletor expira depois de 120 segundos. Só usuários autorizados (os que estão em DISCORD_ALLOWED_USERS) podem interagir com ele. Se você já sabe o nome do modelo, digite /model <nome> direto.

Comandos de barra nativos para skills​

O Hermes registra automaticamente as skills instaladas como Application Commands nativos do Discord. Isso significa que as skills aparecem no menu de autocompletar / do Discord ao lado dos comandos embutidos.

  • Cada skill se torna um comando de barra do Discord (por exemplo, /code-review, /ascii-art)
  • As skills aceitam um parâmetro de string opcional chamado args
  • O Discord tem um limite de 100 application commands por bot — se você tem mais skills do que vagas disponíveis, as skills extras são puladas com um aviso nos logs
  • As skills são registradas na inicialização do bot, junto com comandos embutidos como /model, /reset e /background

Nenhuma configuração extra é necessária — qualquer skill instalada via hermes skills install é registrada automaticamente como comando de barra do Discord no próximo reinício do gateway.

Desativando o registro de comandos de barra​

Se você roda vários gateways do Hermes contra o mesmo aplicativo do Discord (por exemplo, homologação + produção), só um deles deve ser dono do registro global de comandos de barra — senão a última inicialização vence e os registros ficam oscilando. Desligue o registro de comandos de barra no gateway "seguidor":

gateway:
  platforms:
    discord:
      extra:
        slash_commands: false   # padrão: true

Deixar isso em true no gateway "principal" mantém o comportamento normal — comandos globais no menu / para os embutidos e para as skills instaladas.

Enviando mídia (tags MEDIA: embutidas)​

O adaptador do Discord aceita upload nativo de arquivo para todos os tipos comuns de mídia por meio de tags MEDIA:/caminho/do/arquivo embutidas na resposta do agente — o adaptador remove a tag e sobe o arquivo automaticamente:

TipoComo é entregue
Imagens (PNG/JPG/WebP)Anexo nativo de imagem do Discord com prévia embutida
GIFs animadossend_animation sobe como animation.gif, para o Discord reproduzir ali mesmo (não como miniatura estática)
Vídeo (MP4/MOV)send_video — reprodutor de vídeo nativo
Áudio / vozsend_voice — mensagem de voz nativa quando possível, anexo de arquivo caso contrário
Documentos (PDF/ZIP/docx/etc.)send_document — anexo nativo com botão de download

O limite de tamanho por upload do Discord depende do nível de boost do servidor (25 MB no gratuito, até 500 MB). Se o Hermes receber um HTTP 413, o adaptador recorre a um link apontando para o caminho do cache local, em vez de falhar silenciosamente.

Recebendo tipos de arquivo arbitrários​

Qualquer tipo de arquivo que um usuário suba é aceito. A barreira é a autorização para falar com o agente — não a extensão do arquivo. Todo upload é baixado, guardado em cache em ~/.hermes/cache/documents/ e apresentado ao agente como um evento de mensagem do tipo DOCUMENT, para que ele possa inspecionar o arquivo com terminal (ffprobe, unzip, file, strings, etc.) ou com read_file.

  • Tipos conhecidos (PDF, docx/xlsx/pptx, zip, imagens/áudio/vídeo, etc.) mantêm o seu MIME exato.
  • Tipos desconhecidos recorrem ao content type informado pelo upload, ou a application/octet-stream quando nenhum é informado.
  • Arquivos pequenos decodificáveis em UTF-8 (texto, código, configuração, HTML, CSS, JSON, YAML, ...) têm o conteúdo injetado automaticamente no prompt, até 100 KiB. Arquivos binários que não podem ser decodificados são apresentados apenas como uma nota de contexto apontando o caminho (traduzida automaticamente para terminais em sandbox Docker/Modal via to_agent_visible_cache_path), para não estourarem a janela de contexto.

O único limite de entrada é o teto de tamanho por arquivo (padrão de 32 MiB):

discord:
  # Opcional — aumente ou desative o teto de tamanho por arquivo. O padrão é 32 MiB.
  # O arquivo inteiro é mantido em memória enquanto é guardado em cache, então
  # uploads ilimitados têm um custo real de memória.
  max_attachment_bytes: 33554432   # bytes; 0 = ilimitado

Variável de ambiente equivalente: DISCORD_MAX_ATTACHMENT_BYTES=33554432 (ou 0 para não ter teto).

A antiga chave discord.allow_any_attachment agora não faz nada — todo tipo de arquivo é sempre aceito — e é mantida só para que configurações existentes não gerem erro.

Custo de memória do ilimitado

Desativar o teto de tamanho (max_attachment_bytes: 0) significa que um usuário pode jogar um arquivo de vários GB no bot e o gateway vai obedientemente passá-lo pela memória enquanto guarda em disco. Só use isso em instalações confiáveis de um único usuário. Em bots compartilhados, mantenha o padrão de 32 MiB ou aumente com moderação.

Perguntas interativas (clarify)​

Quando o agente chama a ferramenta clarify — para perguntar qual abordagem você prefere, pedir retorno depois de uma tarefa ou confirmar antes de uma decisão não trivial — o Discord renderiza a pergunta com um botão por escolha:

Qual framework devo usar para o painel?

[1. Next.js] [2. Remix] [3. Astro] [Outro (digite a resposta)]

Clique em um botão numerado para responder, ou clique em Outro para digitar uma resposta livre (a próxima mensagem que você enviar naquele canal se torna a resposta). Chamadas de clarify em aberto (sem escolhas predefinidas) pulam os botões e simplesmente capturam a sua próxima mensagem.

Os botões se desabilitam sozinhos depois que uma escolha é feita, para que cliques duplicados não resolvam a pergunta duas vezes. Configure o tempo limite de resposta com agent.clarify_timeout no ~/.hermes/config.yaml (padrão de 600 segundos). Se você não responder dentro do tempo limite, o agente se desbloqueia com uma mensagem sentinela e se adapta, em vez de ficar travado.

Canal padrão​

Você pode designar um "canal padrão" (home channel), onde o bot envia mensagens proativas (como a saída de tarefas de cron, lembretes e notificações). Existem dois jeitos de definir isso:

Usando o comando de barra​

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

Configuração manual​

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

DISCORD_HOME_CHANNEL=123456789012345678
DISCORD_HOME_CHANNEL_NAME="#bot-updates"

Troque o ID pelo ID real do canal (clique com o botão direito → Copy Channel ID, com o Developer Mode ligado).

Mensagens de voz​

O Hermes Agent aceita mensagens de voz do Discord:

  • Mensagens de voz recebidas são transcritas automaticamente pelo provedor de STT configurado: o faster-whisper local (sem chave), o Groq Whisper (GROQ_API_KEY) ou o OpenAI Whisper (VOICE_TOOLS_OPENAI_KEY).
  • Texto para fala: use /voice tts para o bot enviar respostas faladas em áudio junto com as respostas em texto.
  • Canais de voz do Discord: o Hermes também pode entrar em um canal de voz, ouvir as pessoas falando e responder falando no canal.

Para o guia completo de configuração e operação, veja:

Efeitos de áudio em canal de voz (som ambiente + confirmações faladas)​

Quando o bot está em um canal de voz, você pode dar a ele um jeito mais conversacional: uma confirmação falada curta ("deixa eu ver isso") antes de começar a trabalhar, e uma cama sonora ambiente discreta de "pensando" que toca por baixo enquanto as ferramentas rodam — a fala abaixa o ambiente e ele volta a subir ao terminar, parecido com o modo de voz do Grok.

O discord.py toca só um fluxo de áudio por conexão, então o Hermes instala um mixer em software no fluxo de saída, que soma um loop ambiente, as confirmações e as respostas de TTS nesse fluxo único — eles se sobrepõem em vez de se cortarem.

Isso vem desligado por padrão. Habilite no config.yaml:

discord:
  voice_fx:
    enabled: true          # chave geral
    ambient_enabled: true   # cama de "pensando" enquanto as ferramentas rodam
    ambient_path: ""       # arquivo de loop personalizado (qualquer formato de áudio); "" = pad sintetizado embutido
    ambient_gain: 0.18     # volume da cama em repouso (0.0–1.0)
    duck_gain: 0.06        # volume do ambiente enquanto o bot fala
    speech_gain: 1.0       # volume do TTS / das confirmações
    ack_enabled: true      # falar uma frase curta antes da primeira chamada de ferramenta do turno
    ack_phrases:           # escolhida aleatoriamente; use [] para desativar a confirmação falada
      - "Deixa eu ver isso."
      - "Um momento."
      - "Vou verificar agora."

Notas:

  • Use voice_channel_inactivity_timeout_seconds: 0 se você quer que o bot fique no canal de voz até um /voice leave explícito ou uma desconexão manual. O padrão preserva a saída automática histórica por 300 segundos de inatividade.
  • voice_playback_timeout_seconds é um piso, não um teto rígido para TTS longo. O Hermes mede a duração do áudio gerado e espera duração + 30s quando isso é maior que o piso configurado.
  • A confirmação dispara no máximo uma vez por turno, e só quando o bot está em um canal de voz e o mixer está ativo. Ela usa o provedor de TTS que você configurou.
  • ambient_path aceita qualquer arquivo que o ffmpeg consiga decodificar; ele é repetido em loop sem emenda. Deixe vazio para usar o pad sintetizado embutido (não precisa de nenhum arquivo).
  • Todos os ajustes ficam no config.yaml (não no .env) — são comportamentais, não segredos.
  • Quando voice_fx.enabled é false, a reprodução de voz usa o caminho original de disparo único e nada muda.

Canais de fórum​

Os canais de fórum do Discord (tipo 15) não aceitam mensagens diretas — todo post em um fórum tem que ser uma thread. O Hermes detecta canais de fórum automaticamente e cria um post em thread nova sempre que precisa enviar algo para lá, então respostas em texto, TTS, imagens, mensagens de voz e anexos de arquivo funcionam todos sem tratamento especial do agente.

  • O nome da thread é derivado da primeira linha da mensagem (o prefixo de título em markdown é removido, com limite de 100 caracteres). Quando a mensagem só tem anexo, o nome do arquivo é usado como nome de thread reserva.
  • Os anexos vão junto na mensagem inicial da nova thread — sem passo de upload separado, sem envios parciais.
  • Uma chamada, uma thread: cada envio para o fórum cria uma thread nova. Envios sucessivos para o mesmo fórum vão, portanto, produzir threads separadas.
  • A detecção tem três camadas: primeiro o cache do diretório de canais, depois um cache de sondagem local ao processo e, como último recurso, uma sondagem ao vivo com GET /channels/{id} (cujo resultado é então memoizado para o resto da vida do processo).

Atualizar o diretório (/channels refresh nas plataformas que expõem esse comando, ou um reinício do gateway) popula o cache com quaisquer canais de fórum criados depois de o bot ter iniciado.

Solução de problemas​

O bot está online mas não responde às mensagens​

Causa: ou o Message Content Intent está desligado, ou a autorização do Discord está falhando de forma fechada porque nenhuma política de acesso foi configurada.

Solução:

  1. Vá ao Portal do Desenvolvedor → seu app → Bot → Privileged Gateway Intents → habilite o Message Content Intent → Save Changes.

  2. Confirme que pelo menos uma política de acesso do Discord está configurada:

    # recomendado: permitir usuários específicos
    DISCORD_ALLOWED_USERS=284102345871466496

    # ou liberar um servidor confiável / bot de desenvolvimento para se comportar como o Discord pré-0.18
    DISCORD_ALLOW_ALL_USERS=true

  3. Reinicie o gateway:

    hermes gateway restart

Se o log do gateway diz que o Discord está conectado e as verificações da API REST funcionam, mas toda mensagem que entra é ignorada, procure este aviso em ~/.hermes/logs/gateway.log:

No Discord access policy configured; inbound Discord messages will be denied by default.

O Hermes 0.18 falha de forma fechada, de propósito, nos adaptadores acessíveis de fora. Um bot do Discord sem DISCORD_ALLOWED_USERS, sem DISCORD_ALLOWED_ROLES, sem DISCORD_ALLOWED_CHANNELS e sem uma chave explícita de permitir-todos vai conectar com sucesso, mas negar os usuários que entram antes do tratamento normal das mensagens.

Erro de "Privileged intents" / PrivilegedIntentsRequired na inicialização​

Causa: o Hermes pede Privileged Gateway Intents que não estão habilitados para o seu bot no Portal do Desenvolvedor. O Discord então rejeita a conexão WebSocket. O Hermes sempre pede o Message Content Intent. Ele também pede o Server Members Intent quando a sua lista de permissões usa nomes de usuário (não IDs numéricos) ou quando DISCORD_ALLOWED_ROLES está definida. O Presence Intent não é necessário.

Solução:

  1. Vá ao Portal do Desenvolvedor → seu app → Bot → Privileged Gateway Intents.
  2. Habilite o Message Content Intent (obrigatório). Habilite o Server Members Intent se você usa nomes de usuário ou listas de cargos.
  3. Clique em Save Changes e reinicie o gateway (hermes gateway restart).

O log do gateway deve nomear exatamente qual ou quais intents o Hermes pediu. Até que eles sejam habilitados, o Discord vai continuar rejeitando a conexão — isso é um erro de configuração no portal, não uma instabilidade de rede.

O bot não consegue ver as mensagens de um canal específico​

Causa: o cargo do bot não tem permissão para ver aquele canal.

Solução: no Discord, vá nas configurações do canal → Permissions → adicione o cargo do bot com View Channel e Read Message History habilitados.

Erros 403 Forbidden​

Causa: o bot está sem as permissões necessárias.

Solução: convide o bot de novo com as permissões corretas, usando a URL do Passo 5, ou ajuste manualmente as permissões do cargo do bot em Server Settings → Roles.

O bot está offline​

Causa: o gateway do Hermes não está rodando, ou o token está errado.

Solução: confira se o hermes gateway está rodando. Verifique o DISCORD_BOT_TOKEN no seu arquivo .env. Se você redefiniu o token recentemente, atualize-o.

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

Causa: o seu ID de usuário não está em DISCORD_ALLOWED_USERS.

Solução: adicione o seu ID de usuário a DISCORD_ALLOWED_USERS no ~/.hermes/.env e reinicie o gateway.

Pessoas no mesmo canal estão compartilhando contexto sem querer​

Causa: group_sessions_per_user está desativado, ou a plataforma não consegue fornecer um ID de usuário para as mensagens naquele contexto.

Solução: defina isto no ~/.hermes/config.yaml e reinicie o gateway:

group_sessions_per_user: true

Se você quer de propósito uma conversa compartilhada na sala, deixe desligado — só espere histórico de transcrição compartilhado e comportamento de interrupção compartilhado.

Segurança​

aviso

Sempre defina DISCORD_ALLOWED_USERS (ou DISCORD_ALLOWED_ROLES) para restringir quem pode interagir com o bot. Sem uma das duas, o gateway nega todos os usuários por padrão, como medida de segurança. Autorize apenas pessoas em quem você confia — usuários autorizados têm acesso total às capacidades do agente, incluindo uso de ferramentas e acesso ao sistema.

Controle de acesso por cargo​

Em servidores onde o acesso é gerenciado por cargos em vez de listas individuais de usuários (times de moderação, equipe de suporte, ferramentas internas), use DISCORD_ALLOWED_ROLES — uma lista de IDs de cargo separados por vírgula. Qualquer membro com um desses cargos está autorizado.

# ~/.hermes/.env — funciona junto com ou em vez de DISCORD_ALLOWED_USERS
DISCORD_ALLOWED_ROLES=987654321098765432,876543210987654321

Semântica:

  • OU com a lista de usuários. Um usuário está autorizado se o ID dele está em DISCORD_ALLOWED_USERS ou se ele tem qualquer cargo de DISCORD_ALLOWED_ROLES.
  • Server Members Intent habilitado automaticamente. Quando DISCORD_ALLOWED_ROLES está definida, o bot habilita o Members intent na conexão — necessário para o Discord enviar informação de cargo junto com os registros de membro.
  • IDs de cargo, não nomes. Pegue-os no Discord: User Settings → Advanced → Developer Mode ON, depois clique com o botão direito em qualquer cargo → Copy Role ID.
  • Alternativa em DM. Nas DMs, a verificação de cargo varre os servidores em comum; um usuário com um cargo permitido em qualquer servidor compartilhado também está autorizado nas DMs.

Esse é o padrão preferido quando o time de moderação muda muito — moderadores novos ganham acesso no momento em que o cargo é concedido, sem editar o .env nem reiniciar o gateway.

Controle de menções​

Por padrão, o Hermes impede o bot de marcar @everyone, @here e cargos, mesmo que a resposta dele contenha esses termos. Isso evita que um prompt mal formulado ou um conteúdo de usuário repetido encha um servidor inteiro de notificações. As marcações individuais de @usuário e as marcações por referência de resposta (aquele selinho de "respondendo a…") continuam habilitadas, para a conversa normal seguir funcionando.

Você pode relaxar esses padrões por variáveis de ambiente ou pelo config.yaml:

# ~/.hermes/config.yaml
discord:
  allow_mentions:
    everyone: false      # permitir que o bot marque @everyone / @here
    roles: false         # permitir que o bot marque menções a @role
    users: true          # permitir que o bot marque @usuários individuais
    replied_user: true   # marcar o autor ao responder à mensagem dele
# ~/.hermes/.env — as variáveis de ambiente vencem o config.yaml
DISCORD_ALLOW_MENTION_EVERYONE=false
DISCORD_ALLOW_MENTION_ROLES=false
DISCORD_ALLOW_MENTION_USERS=true
DISCORD_ALLOW_MENTION_REPLIED_USER=true
dica

Deixe everyone e roles em false a menos que você saiba exatamente por que precisa deles. É muito fácil um LLM produzir a string @everyone dentro de uma resposta de aparência normal; sem essa proteção, isso notificaria todos os membros do seu servidor.

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