Configuración de la Puerta de Enlace de Hermes para Telegram y Slack

Hola, soy Lena. Seré sincera — cada vez que alguien me pregunta "¿cómo conecto a mi agente a Telegram?", mi primera respuesta es siempre la misma: ¿tu CLI** es ya estable?** Este artículo está escrito para constructores que planean ejecutar una configuración real de **Hermes Agent **gateway, no un tutorial genérico de bots. Nos centraremos en Telegram y Slack, y otras plataformas se tocarán donde importe.

Lo que realmente hace la puerta de Hermes

Un agente entre plataformas de CLI y mensajería

Primero aclaremos el concepto. Hermes tiene dos puntos de entrada: la interfaz de terminal que inicias con hermes y el proceso en segundo plano que inicias con hermes gateway. El gateway es esencialmente una capa de adaptador unificada: se conecta simultáneamente a todas tus plataformas de mensajería configuradas y enruta cada mensaje a la misma instancia de AIAgent. En otras palabras, el agente con el que hablas desde Telegram** y el que tienes desde Slack son el mismo agente, compartiendo el mismo almacén de sesiones, memoria, habilidades y horario cron**.

Según la documentación oficial de la puerta de enlace de mensajería de Hermes, un solo proceso de la pasarela puede ejecutar Telegram, Slack, Discord, WhatsApp, Signal, Email, Matrix, Mattermost y una docena más al mismo tiempo. Cada adaptador de plataforma recibe mensajes, los enruta a través de una tienda de sesiones por chat y se los entrega al agente. Por eso siempre digo: la pasarela es una capa de fan-out, no un cerebro separado.

Por qué el gateway no debería ser tu primer paso de montaje

Aquí es donde la mayoría de la gente se tropieza. Se emocionan, instalan Hermes y inmediatamente intentan cablear un bot de Telegram — y luego pasan tres horas depurando por qué los mensajes "entran pero no sale nada." Mira, yo he estado ahí. La pasarela depende de que tres cosas sean correctas aguas arriba: configuración de modelos, configuración de herramientas y configuración de autorización. Si alguna de ellas está roto en CLI, la pasarela heredará esa rotura y hará que sea diez veces más difícil de diagnosticar, porque ahora estás mirando un chat de Telegram en lugar de un registro de terminal con mucho texto.

Así que mi regla general, y la digo siempre: CLI primero, gateway después. Consigue una conversación limpia en hermes localmente antes incluso de abrir BotFather.

! [imagen] (https://uploads.evomap.ai/blog/b4107c4ad88e7508.png)

Prepara una base estable antes de montar la plataforma

Verifica primero el chat local, las herramientas y la configuración del modelo

Antes de tocar cualquier token de la plataforma, repasa esta lista de verificación en la máquina que alojará la pasarela (idealmente un VPS pequeño; tu laptop no es el lugar correcto porque la pasarela necesita estar funcionando 24/7):

hermes model — confirma que tu proveedor y modelo sean accesibles. Si estás en un modelo local, asegúrate de que la longitud de contexto sea al menos 64K.
hermes tools — activa solo lo que realmente necesites. Cada herramienta amplía el radio de impacto después.
hermes — abre una conversación real. Pídele que ejecute un comando de shell, haga una búsqueda web, escriba un archivo. Observa la salida. Cualquier cosa rara aquí será diez veces más rara a través de Telegram.
hermes doctor — deja que los diagnósticos integrados detecten problemas de ruta, permisos y dependencias.

Solo cuando los cuatro estén limpios continúo. Los propios mantenedores de Hermes enfatizan esto en el repositorio GitHub del proyecto, donde el flujo documentado es asistente de configuración → CLI → pasarela, en ese orden. Honestamente, saltarse esto es la razón más común por la que la gente abandona Hermes.

Configurar Telegram y Slack paso a paso

Tokens, permisos, emparejamiento y enrutamiento destino

Ahora, a las plataformas. Voy a explicarlas en paralelo porque los conceptos son similares: creas una aplicación, obtienes tokens, estableces alcances/listas permitidas, diriges Hermes hacia ella; pero la mecánica es bastante diferente, y asumir que son iguales es cómo la gente termina con pasarelas silenciosas.

Telegram

Telegram es más rápido de poner en marcha. Todo el flujo se realiza dentro de Telegram mismo:

Abre un chat con @BotFather. Según la documentación oficial de bots de Telegram, esta es la única manera autorizada de registrar un bot y obtener un token.
Envía /newbot, elige un nombre para mostrar y un nombre de usuario que termine en bot, y BotFather te entrega un token con forma de 123456789:ABCdef….
Encuentra tu ID de usuario numérico enviando un mensaje a @userinfobot. No lo confundas con tu @username; Hermes autoriza por ID numérico.
Introduce ambos en ~/.hermes/.env:

Plain

TELEGRAM_BOT_TOKEN=123456789:ABCdef...
TELEGRAM_ALLOWED_USERS=123456789

Ejecuta hermes gateway start, luego envía un mensaje directo al bot. Deberías recibir una respuesta en segundos.

Un detalle que afecta a las personas: si deseas agregar compañeros de equipo más tarde, tienes dos opciones: extender TELEGRAM_ALLOWED_USERS con sus IDs numéricos, o usar emparejamiento DM, donde los usuarios desconocidos obtienen un código de un solo uso que apruebas con hermes pairing approve telegram XKGH5N7P. El flujo de emparejamiento está documentado en la guía de configuración de Hermes para Telegram y, sinceramente, es la mejor opción por defecto para asistentes compartidos: no necesitas buscar los IDs de los usuarios con anticipación.

Slack

Slack es más complejo. Omite un paso y el bot estará en línea pero completamente silencioso en los canales.

Ve a api.slack.com/apps y crea una nueva aplicación desde cero (no desde un manifiesto, la primera vez — aprenderás más rápido). Las aplicaciones clásicas de Slack fueron totalmente descontinuadas en marzo de 2025, por lo que debes usar el flujo moderno basado en Bolt.
Bajo OAuth & Permissions → Bot Token Scopes, agrega al menos: app_mentions:read, chat:write, im:history, im:read, im:write, channels:history, groups:history, mpim:history. Los dos scopes *:history son los que más se omiten — sin ellos tu bot funcionará en DMs pero ignorarará silenciosamente todo en los canales.
Bajo Socket Mode, actívalo. Este es el camino que utiliza Hermes, y es la elección correcta para casi todas las configuraciones autoalojadas — tu gateway no necesita un endpoint HTTP público, se conecta vía WebSocket. La mecánica y la razón se explican en la documentación oficial de Slack Socket Mode.
Bajo Basic Information → App-Level Tokens, genera un token con connections:write. Este es el token xapp-…. El token de bot del paso 2 es el token xoxb-…. Necesitas ambos.
Instala la aplicación en tu espacio de trabajo, luego coloca ambos tokens más una lista de permitidos SLACK_ALLOWED_USERS en ~/.hermes/.env.
/invite @YourBot en el canal donde quieres que esté activo. No verá mensajes en los canales donde no ha sido invitado.

Cómo verificar que la mensajería entrante y saliente funciona

No solo envíes "hola" y lo des por terminado. Yo realizo la misma verificación de tres pasos en cada plataforma:

Entrada: envía un mensaje simple en un DM. El bot debería responder.
Salida: pide al agente que ejecute una tarea de varios pasos ("buscar en la web X y resumir"). Observa los indicadores de transmisión/escritura — si no aparecen, el adaptador está conectado pero los eventos de progreso no están configurados.
Entrega dirigida: configura SLACK_HOME_CHANNEL (o ejecuta /sethome en Telegram) y activa un trabajo cron. Si el cron se ejecuta en el lugar incorrecto, tu configuración home es incorrecta, no el horario.

Si los tres pasan en ambas plataformas, realmente has terminado. Si solo el primero pasa, tienes una configuración parcial que fallará en uso real.

Modos de fallo específicos de la plataforma

Aquí es donde paso la mayor parte de mi tiempo de soporte, así que presta atención.

Fallos de autenticación, adaptadores faltantes, permisos incorrectos, problemas de entrega silenciosa

Los modos de fallo de Telegram suelen estar relacionados con el token o la lista de permitidos. Un token revocado o mal escrito te da un 401 limpio — fácil. Un token correcto sin TELEGRAM_ALLOWED_USERS configurado es más sigiloso: la pasarela niega a todos los usuarios por defecto como medida de seguridad, así que el bot parece muerto pero en realidad está haciendo exactamente lo que se le dijo. Si estás detrás de un firewall, configura HTTPS_PROXY o la variable proxy específica de Telegram; la pasarela se ajusta de manera segura pero debes darle un camino de salida.

Los modos de fallo de Slack se agrupan alrededor de los permisos. El patrón que veo semanalmente: el bot responde en DMs, ignora los canales. Eso es casi siempre un channels:history o groups:history faltante, además de que el bot no haya sido invitado al canal. Ambos deben ser corregidos; uno solo no es suficiente. Otros errores clásicos:

Olvidaste el token a nivel de app xapp- → Socket Mode no se conectará en absoluto.
Agregaste permisos después de la instalación pero no reinstalaste la app → los nuevos permisos no se otorgan realmente. Reinstalar es obligatorio.
Usaste una app clásica anterior a marzo de 2025 → simplemente no funcionará. Recréala desde cero.

Un modo de fallo multiplataforma que vale la pena señalar: que el servicio de la pasarela mismo falle. En macOS, hermes gateway install registra un plist lanzado. En Linux, generalmente lo envolverás en una unidad systemd. Si el servicio subyacente no está supervisado, tu "asistente 24/7" es en realidad un asistente de 4 horas que muere la próxima vez que se reinicia la máquina.

Límites operativos para asistentes compartidos

Quién puede hablar con el agente, límites de aprobación, radio de impacto

Aquí está la parte en la que nadie quiere pensar hasta que sea demasiado tarde. En el momento en que pones a un agente en Telegram o Slack, cualquiera con acceso a esa superficie de chat puede dar órdenes a un proceso que se ejecute en tu servidor. Eso merece un respeto real.

Algunas reglas que nunca rompo:

Establece siempre una lista explícita de permisos. TELEGRAM_ALLOWED_USERS y SLACK_ALLOWED_USERS no son opcionales — sin ellos, el valor seguro por defecto es la denegación, y deberías dejarlo así hasta que hayas tomado una decisión deliberada. GATEWAY_ALLOW_ALL_USERS=true es un rifle y nunca he tenido un uso legítimo para ella.
Ejecuta el agente en un backend de terminal aislado. Hermes soporta un backend de terminal Docker que elimina capacidades y desactiva la escalada de privilegios. Para cualquier agente accesible desde el exterior, esta es la única configuración que uso. La CLI de mi equipo de desarrollo puede tener shell en bruto; el agente respaldado por gateway no debería.
Trata los tokens como secretos de producción. Los tokens de bots, tokens de app y archivos de lista de permisos deberían estar en ~/.hermes/.env con el modo 600 y en ningún otro lugar. La Hoja de Trucos de Gestión de Secretos OWASP profundiza en rotación, almacenamiento centralizado y acceso con privilegios mínimos — si lo ejecutas para un equipo, esas prácticas dejan de ser opcionales.
Guarda las indicaciones de aprobación sobre acciones destructivas. Cuando el agente quiere hacer algo peligroso, debería preguntar en el chat y esperar a yes. No desactives eso para "hacerlo más fluido" — esa indicación me ha salvado de rm -rf más de una vez.
Limita el radio de explosión**.** Los trabajos cron entregan a SLACK_HOME_CHANNEL o al canal /sethome de Telegram. No los dirijas a un canal público del equipo "para mayor visibilidad" — diríjalos a un canal privado en el que solo estén los operadores, y reenvía los resúmenes manualmente.

Si lo haces para algo más que para ti mismo, apunta las respuestas a estas preguntas antes de publicar: ¿Quién puede hablar con el agente? ¿Qué puede hacer sin preguntar? ¿Dónde aterrizan sus salidas? ¿Quién rota los tokens? Si no puedes responder las cuatro en una sola frase cada una, no estás listo para compartirlo.

! [imagen] (https://uploads.evomap.ai/blog/80762ecbd4db1799.png)

Preguntas frecuentes

¿Necesito fichas xoxb** y xapp**** para Slack?**

Sí. El token bot (xoxb-…) se usa para publicar mensajes y llamadas a la API Web. El token a nivel de aplicación (xapp-…, con connections:write) es el que abre el WebSocket para el Modo Socket. Si falta alguno de los dos, la conexión falla de forma diferente — pero la falta del token significa que no hay respuestas; la falta del token de la app significa que no hay eventos entrantes en absoluto.

¿Puede un solo gateway Hermes** servir a varios espacios de trabajo de Slack?**

Sí — Hermes asigna cada team_id a su propio ID de usuario de WebClient y bot, para que un proceso de pasarela pueda autenticarse de forma independiente en cada espacio de trabajo. Este es un comportamiento documentado, no una solución alternativa.

Mi bot de Telegram** responde por mensajes privados**** pero ignora los mensajes del grupo. ¿Por qué?**

Por defecto, los bots de Telegram tienen activado el modo privacidad, lo que significa que solo ven mensajes que los mencionan explícitamente o responden a ellos. Desactiva el modo privacidad en BotFather (/setprivacy → desactiva) si quieres que el bot vea todos los mensajes de grupo. Alternativamente, simplemente @mention el bot.

¿Debería ejecutar el gateway** en mi portátil?**

No, por favor, no lo hagas. El objetivo de Hermes es que no está ligado a tu portátil — debería funcionar en una máquina de VPS de 5 dólares o similar siempre encendida. Si no, el bot se muere cada vez que cierras la tapa y la gente deja de confiar en él.

¿Configurar gateway** es lo mismo que configurar cron**** y perfiles?**

No, pero se acumulan. Una vez que la puerta de enlace es sólida, los trabajos cron se entregan de forma natural a tus plataformas configuradas y los perfiles de personalidad se propagan por todas las superficies. **Si haces bien la pasarela, el resto del ecosistema de agentes funciona en su mayor parte. Si te equivocas, todas las demás funciones heredan la rotura.

Esa es la versión honesta. Construye la base en CLI, superpon Telegram o Slack encima, asegura quién puede acceder y no te saltes los aburridos pasos de verificación — son el seguro más barato que comprarás este trimestre.