Cómo configurar Hermes Agent en Discord (Bot + Voz)

Por qué ejecutar Hermes Agent en Discord

Si tu proyecto, tu estudio o tu grupo de amigos ya conviven en un servidor de Discord, ahí es donde debe poder alcanzarse tu agente. Los hilos, los canales de voz y las salas cerradas por rol le dan a Hermes un contexto que un dashboard aislado no puede: quién pregunta, en qué canal está, si habla o escribe, y dónde debe caer la respuesta.

Hermes Agent trae soporte de primera para Discord que cubre tanto el lado de texto como el de voz de un servidor. El runtime se conecta hacia fuera a Discord por el Gateway WebSocket estándar, así que puede vivir en tu portátil, en un VPS pequeño o detrás del NAT de tu casa y seguir recibiendo mensajes en tiempo real. No hay que exponer ningún webhook público ni abrir puertos entrantes. El mismo runtime que responde a mensajes de texto puede también entrar a un canal de voz con /voice join, escuchar a través de STT y responder en voz alta por TTS.

Esta guía recorre el setup completo de principio a fin: crear la aplicación de Discord, generar el token del bot, activar los intents que Discord exige en silencio, configurar la allowlist y el canal home, invitar al bot con la URL de OAuth2 correcta y los fallos que se comen a los despliegues nuevos.

Lo que necesitas antes de empezar

Un despliegue limpio en Discord requiere cinco cosas listas:

Un servidor de Discord donde tengas permiso para añadir bots. Si no es tuyo, pídeselo a la administración, la URL de invitación solo funciona para alguien con "Gestionar servidor" en el servidor de destino.
Una instalación de Hermes Agent funcionando. La guía de Hermes Agent con Docker es la vía más limpia para levantar una; si vas en Windows, el setup con WSL2 es su equivalente.
Una clave de proveedor de modelo. Sirve Anthropic, OpenAI, OpenRouter o cualquier endpoint compatible con OpenAI. El runtime la usa para responder de verdad.
Tu ID numérico de usuario de Discord para la allowlist (Modo desarrollador → clic derecho en tu nombre → Copiar ID de usuario).
Unos 15 minutos para la primera instalación. Los redepliegues posteriores tardan menos de un minuto.

Paso 1 - Crea la aplicación de Discord y el bot

Abre el portal de desarrolladores de Discord, pulsa New Application, ponle nombre (por ejemplo, hermes-agent) y acepta los términos de desarrollador. Esto crea un contenedor de aplicación donde vivirán el usuario bot, las credenciales OAuth2 y el token.

Desde la página de la aplicación, ve a Bot en la barra lateral. Discord ya no exige pulsar Add Bot en aplicaciones nuevas: el usuario bot se crea de forma automática. Lo que sí tienes que hacer es darle un nombre visible, un avatar y desactivar Public Bot si quieres que la URL de invitación solo la pueda usar quien tú decidas.

Después pulsa Reset Token para revelar el token del bot. Empieza por MTA…. Cópialo una vez y pégalo directamente en tu .env: Discord no te lo volverá a enseñar, solo te dejará regenerarlo.

Trata este token como una clave SSH. Cualquiera que lo tenga puede actuar como tu bot, leer todos los mensajes de todos los canales donde esté y quemar tus tokens del proveedor de modelo disparando al agente.

Paso 2 - Activa los intents del Gateway que Discord exige

Este es el paso que rompe en silencio a la mayoría de los despliegues de bots de Discord. Discord divide "qué manda a tu bot" en intents. Algunos son privilegiados, es decir, tienes que activarlos explícitamente en cada aplicación, o Discord conectará el WebSocket, entregará los eventos y simplemente vaciará los campos que no hayas pedido.

Todavía en Bot, baja hasta Privileged Gateway Intents y activa:

Message Content Intent - obligatorio para leer el texto de los mensajes. Sin él, Hermes recibe los eventos de mensaje con el contenido vacío y se queda mudo para siempre.
Server Members Intent - obligatorio para resolver la allowlist contra los IDs reales y para ver cuándo entran o salen miembros.
Presence Intent - opcional, útil si quieres que el bot reaccione cuando alguien se conecta o entra en un canal de voz.

Pulsa Save Changes abajo del todo. Esto se hace en el portal de desarrolladores: no hay un interruptor en .env.

Cuando tu bot esté verificado y en más de 100 servidores, Discord te obligará a pedir estos intents. Por debajo de ese umbral, con activarlos basta.

Paso 3 - Encuentra tu ID numérico de usuario de Discord

Hermes Agent solo responderá a los IDs que aparezcan en DISCORD_ALLOWED_USERS. Es el control de seguridad más importante de todo el setup, y espera IDs numéricos, no @handles.

En Discord, abre Ajustes de usuario → Avanzado → activa Modo desarrollador. Cierra los ajustes, haz clic derecho sobre tu nombre en cualquier canal o lista de miembros y elige Copiar ID de usuario. El ID tiene esta pinta: 284102345871466496. Repite el proceso con cada persona a la que quieras autorizar.

Saltarse la allowlist equivale a publicar la clave de tu proveedor delante de todo el servidor. Si una instancia de Hermes es alcanzable desde un servidor público con la allowlist vacía, cada mensaje que el bot pueda leer quemará tus tokens y, en un canal de voz, cualquier ruido que oiga se transcribirá.

Paso 4 - Configura el runtime de Hermes

Abre ~/.hermes/.env (o el .env que lea tu contenedor) y añade:

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

Nota sobre cada uno:

DISCORD_BOT_TOKEN - el token que copiaste en el paso 1.
DISCORD_ALLOWED_USERS - lista separada por comas de IDs numéricos. El bot ignora a todo el mundo que no esté ahí, incluidos admins del servidor y otros bots.
DISCORD_HOME_CHANNEL (opcional) - el ID del canal para mensajes proactivos, salidas de tareas programadas y notificaciones de skills. Clic derecho en el canal en Discord → Copiar ID del canal. Si no lo defines, la salida proactiva va al DM del bot con el primer usuario autorizado.
DISCORD_HOME_CHANNEL_NAME (opcional) - una etiqueta legible que se usa en los logs, no afecta al enrutado.

chmod 600 ~/.hermes/.env después de guardar. El token da acceso total a tu bot; trátalo como una clave SSH.

Paso 5 - Invita al bot a tu servidor

Los bots no se unen a servidores, se invitan mediante una URL de OAuth2 que pide de entrada los scopes y permisos correctos. Los que Hermes espera son:

Scopes: bot y applications.commands (el segundo habilita los slash commands /voice).
Permissions integer: 274878286912, que cubre Ver canales, Enviar mensajes, Insertar enlaces, Adjuntar archivos, Leer historial de mensajes, Enviar mensajes en hilos y Añadir reacciones.

Coge el Client ID de tu aplicación en General Information del portal y mételo en esta plantilla:

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

Abre la URL, elige tu servidor, confirma los permisos y Discord soltará al bot como un miembro más. También puedes montar la URL desde OAuth2 → URL Generator del portal si prefieres marcar casillas: el resultado es el mismo.

Para voz, además vas a querer Conectar y Hablar sobre el canal de voz concreto que vayas a usar. Si faltan tras la invitación, añádele al bot un rol que se los conceda o edita directamente las anulaciones de permiso del canal.

Paso 6 - Arranca el gateway y envía el primer mensaje

Reinicia el gateway para que recoja el nuevo entorno:

hermes gateway restart

O, con Docker Compose:

docker compose restart gateway

Sigue los logs y espera el handshake con Discord:

hermes gateway logs --follow

Buscas dos líneas, en este orden:

discord: connecting to Gateway
discord: connected as tu-nombre-bot#1234 (guilds: 1)

Si solo ves la primera y nada después, el token está mal o lo has rotado. Si el bot conecta pero no responde en el canal, o Message Content Intent sigue apagado en el portal, o tu ID no está en DISCORD_ALLOWED_USERS.

Cuando ya esté arriba, mándale un DM o menciónalo con @ en un canal que pueda ver. Hermes responde en la misma conversación, con toda la memoria y el contexto de skills intacto. A partir de aquí, todas las capacidades de Hermes, memoria persistente, tareas programadas y skills personalizadas, funcionan exactamente igual que en la superficie de Telegram.

Paso 7 - Enciende la voz (opcional, pero divertido)

Los canales de voz de Discord son una superficie de primera para Hermes. Con el bot ya en el servidor con Conectar y Hablar, únete tú a un canal de voz y, en cualquier canal de texto donde el bot esté, escribe:

/voice join

El bot entrará en el canal de voz en el que estés, empezará a escuchar por el proveedor STT que tengas configurado y responderá en voz alta por el TTS. La superficie de comandos es:

/voice join - entra en tu canal de voz actual.
/voice channel - alias de /voice join.
/voice leave - se desconecta del canal de voz.
/voice status - informa de si el modo voz está activo y en qué canal está el bot.

Solo se transcribe a los usuarios de DISCORD_ALLOWED_USERS; el audio del resto se ignora, lo que importa si el canal de voz lo compartes con gente a la que no has autorizado explícitamente. Para elegir un stack STT/TTS que funcione bien sobre el stream Opus de Discord, la introducción al modo voz de Hermes es la siguiente lectura.

Los fallos que muerden primero

Cinco errores explican casi todos los hilos de "el setup de Discord no funciona":

Message Content Intent apagado. El bot conecta, entra al servidor y no responde a nada. Discord no te avisa. Actívalo en el portal y reinicia el gateway.

DISCORD_ALLOWED_USERS vacío. Por defecto se ignora a todo el mundo. Es un default seguro a propósito, pero hace que el bot parezca roto para quien lo prueba por primera vez y olvida añadir su propio ID.

Permisos mal en la invitación. Si el bot no ve el canal o no tiene Enviar mensajes, permanece mudo incluso para los usuarios autorizados. Reinvítalo con el permissions integer 274878286912 o corrige el rol en Ajustes del servidor → Roles.

Permisos de voz que faltan en un canal concreto. El bot tiene Conectar y Hablar a nivel servidor, pero una anulación de canal se los quita. Discord muestra el bot como "conectado" pero no produce audio en ninguna dirección. Revisa la pestaña de permisos del canal de voz.

Dos procesos de gateway contra el mismo volumen de datos. Si arrancas un gateway en modo Discord y otro en modo Telegram contra el mismo directorio /data, el orden de mensajes y las escrituras de memoria se corrompen entre sí en cuestión de minutos. Ejecuta un único gateway con los bloques DISCORD_* y TELEGRAM_* juntos en .env si quieres las dos superficies: el runtime las multiplexa de forma nativa.

Si el problema parece de Discord pero los síntomas huelen a algo general, la guía de troubleshooting de Telegram cubre los fallos de gateway y de proveedor con más profundidad, y la mayoría son independientes de la superficie.

Discord y Telegram, lado a lado

Aspecto	Discord	Telegram
Tiempo de setup	15 min (app + intents + invitación)	5 min (un token de BotFather)
Alcance	Detrás de firewall (Gateway WebSocket)	Detrás de firewall (long-poll)
Campo de allowlist	`DISCORD_ALLOWED_USERS` (IDs numéricos)	`TELEGRAM_ALLOWED_USERS` (IDs numéricos)
Mejor para	Comunidades, salas de voz, servidores de proyecto	Uso personal, mobile-first, notas de voz
Hilos	Nativos (canales + threads)	Solo respuestas citadas
Voz	Entrar al canal de voz, STT/TTS en directo	Notas de voz, respuestas transcritas

Las dos superficies no son excluyentes. El mismo runtime de Hermes puede servir a ambas a la vez, útil cuando un chat personal en Telegram y una sala de voz compartida en Discord beben del mismo almacén de memoria.

Sáltate la fontanería de Discord

Los pasos en sí son sencillos, pero sigues siendo dueño del host: backups, TLS del dashboard, rotación de logs y el ritmo de actualización. Para una instalación personal está bien. Para un servidor que quiere el bot en marcha en minutos y sin sobrecarga operativa, Hermify provisiona un runtime de Hermes gestionado sobre Telegram, mantiene la memoria persistente y rota los tokens sin que toques un .env.

Tú pones la clave del proveedor de modelo y la superficie que quieras usar; la plataforma se encarga de todo lo de abajo. Si estás valorando esa opción antes de invertir en tu propio VPS, la comparativa de autohospedaje frente a gestionado recorre los números de coste y mantenimiento.