Configuración de Hermes Agent en Telegram: Problemas Frecuentes y Soluciones

Telegram Es Donde la Mayoría de los Despliegues de Hermes Se Traban

El quickstart de Hermes es rápido. La configuración de Telegram es donde la mayoría de los usuarios se encuentran con problemas. No es que el proceso sea complicado, es que cada paso tiene varias formas de salir mal, y cuando múltiples cosas fallan silenciosamente, es difícil saber dónde mirar.

Esta guía cubre los problemas más comunes en el orden en que suelen aparecer.

Obtener el Token del Bot de Telegram

El token viene de BotFather, la interfaz oficial de gestión de bots de Telegram. Este paso parece simple pero tiene algunos modos de falla.

Cómo hacerlo bien:

1. Abrí Telegram y buscá @BotFather.
2. Enviá /newbot.
3. BotFather te pide un nombre (nombre de visualización) y un nombre de usuario (debe terminar en bot).
4. Después de la creación, BotFather te envía un mensaje con el token. Se ve como 7123456789:ABCDef....
5. Copiá el token completo incluyendo el colon y todo lo que viene después.

Errores comunes:

• Copiar solo el ID numérico: el token es el string completo después del colon, no solo el número antes de él.
• Usar un bot de prueba de un entorno de desarrollo: si creaste un bot hace meses y no recordás qué token corresponde a qué bot, BotFather puede mostrarte los bots existentes con /mybots. Desde ahí podés revocar y regenerar tokens.
• Espacios o saltos de línea en el token pegado: algunos flujos de copia agregan espacios en blanco. Pegalo primero en un editor de texto plano para verificar que el token esté limpio antes de usarlo.

La Configuración de TELEGRAM_ALLOWED_USERS

Esta es la parte más mal configurada de un despliegue de Hermes en Telegram.

Hermes requiere que especifiques qué user IDs de Telegram tienen permitido enviar mensajes al bot. Sin esto, el bot no responderá a nadie. Con un valor incorrecto, el bot no te responderá a vos aunque parezca estar corriendo.

Lo que necesitás:

Un user ID de Telegram es un número, no un nombre de usuario. @username no es lo que Hermes quiere. Necesitás el ID numérico, que se ve como 123456789.

Cómo obtener tu user ID de Telegram:

Abrí Telegram, buscá @userinfobot y enviá /start. Te responderá con tu user ID.

Cómo configurarlo:

En config.yaml:

telegram_allowed_users: "123456789"

Para múltiples usuarios, usá una lista separada por comas:

telegram_allowed_users: "123456789,987654321"

Nota de Hermify: En el flujo de onboarding de Hermify, ingresás tu user ID de Telegram (o una lista separada por comas) en el formulario de credenciales. Este campo es separado del campo del token del bot. Ambos son obligatorios.

Problema: El Bot No Responde para Nada

Si le mandás un mensaje a tu bot y no pasa nada, revisá esta checklist:

1. ¿Está corriendo el gateway de Hermes?

hermes gateway status

Si el gateway no está corriendo, el bot no tiene ningún listener. Inicialo:

hermes gateway start

2. ¿Está tu user ID en la lista de permitidos?

Verificá dos veces la configuración de telegram_allowed_users. Esta es la causa más común de un bot silencioso. El proceso está corriendo, el gateway está conectado, pero Hermes está ignorando deliberadamente tus mensajes porque tu ID no está en la lista.

3. ¿El token del bot expiró o fue revocado?

BotFather te permite revocar tokens. Si regeneraste el token después de agregarlo a Hermes, el token viejo ya no funciona. Revisá BotFather con /mybots, seleccioná tu bot, andá a API Token y verificá que el token en tu configuración coincida.

4. ¿Está el bot en un chat diferente?

Los bots de Telegram responden al chat específico donde reciben mensajes. Si agregaste previamente el bot a un grupo y Hermes está configurado para responder mensajes de grupos de manera diferente, puede que necesites iniciar la conversación en un chat directo (DM) con el bot.

Problema: Error "Unauthorized" en los Logs

Este error significa que el token es inválido o fue revocado. La solución siempre es regenerar el token en BotFather y actualizar tu configuración de Hermes con el nuevo valor.

En BotFather:

1. Enviá /mybots.
2. Seleccioná tu bot.
3. Andá a API Token → Revoke current token.
4. Copiá el nuevo token.
5. Actualizá config.yaml o el formulario de credenciales del dashboard de Hermify.
6. Reiniciá Hermes (o el runtime de Hermify).

Problema: El Bot Responde Una Vez y Luego Se Silencia

Esto generalmente significa que el proceso de Hermes se detuvo o el gateway se desconectó. Causas comunes:

El proceso fue terminado. En despliegues locales o en hosting compartido económico, los procesos se matan cuando la memoria es escasa o cuando el host recicla contenedores. Revisá los logs del proceso para ver si hubo un crash o un evento OOM (out of memory).

La sesión WSL2 terminó. Si corrés Hermes dentro de WSL2, cerrar la terminal detiene el proceso. Consultá la guía de WSL2 para correr Hermes de forma persistente.

El loop de polling de Telegram tuvo timeout. El gateway de Hermes usa long-polling para recibir mensajes de Telegram. Ocasionalmente la conexión se cae y no se restablece automáticamente. Reiniciar el gateway (hermes gateway restart) soluciona esto.

Un error del modelo causó un crash. Si la API del LLM devolvió un error (límite de velocidad, agotamiento de cuota, respuesta incorrecta), algunas versiones de Hermes pueden salir de la sesión en vez de recuperarse. Revisá la salida de la terminal o los logs para ver si hay un mensaje de error reciente antes del silencio.

Problema: Los Mensajes Llegan pero el Agente Ignora el Contenido

Esto es diferente a un bot silencioso. El bot está recibiendo mensajes pero las respuestas del agente parecen incorrectas o vacías.

Causa más probable: la ventana de contexto del modelo está llena. Hermes lee tu MEMORY.md y el historial de conversaciones en cada prompt. Si el contexto combinado es demasiado largo para la ventana del modelo, el modelo recibe un prompt truncado y la calidad de las respuestas se degrada o se vuelve vacía.

Soluciones:

• Cambiá a un modelo con una ventana de contexto más grande (Claude y Gemini soportan 128k+).
• Recortá tu MEMORY.md manualmente si creció mucho.
• Usá hermes memory compact si está disponible en tu versión para resumir y comprimir la memoria.

Causa menos probable: problema de subcadena en la lista de usuarios permitidos. Si tu configuración de usuarios permitidos contiene 12345 y tu user ID real es 123456789, Hermes no hará la coincidencia correctamente. Verificá el ID numérico completo, no una versión truncada.

Problema: Funciona Bien Localmente pero Está Roto Después del Despliegue

La causa más común aquí es una discrepancia entre el entorno que probaste y el entorno del servidor.

Revisá estas cosas en orden:

1. El token es correcto en la configuración del servidor, no en la configuración local. Es fácil actualizar el archivo equivocado.
2. El servidor puede llegar a la API de Telegram. Algunos proveedores de hosting bloquean las conexiones salientes. Probá con curl https://api.telegram.org/bot<TU_TOKEN>/getMe desde el servidor.
3. El proceso de Hermes arrancó exitosamente. Revisá los logs del contenedor o del proceso para ver si hubo errores de inicio.
4. El directorio de memoria está montado. Si usás Docker, confirmá que el volumen de datos está adjunto. Un agente que arranca sin su directorio de datos se comportará de manera extraña.

Saltarse Todo Esto con Hosting Gestionado

La razón por la que la mayoría de la gente tiene problemas con la configuración de Telegram es que están gestionando el despliegue ellos mismos: lidiando con tokens, archivos de config, procesos y entornos de servidor simultáneamente.

Hermify está diseñado específicamente alrededor de este problema. El flujo de onboarding maneja el cableado de Telegram: vos proporcionás el token del bot y los user IDs permitidos una sola vez, y la plataforma los almacena cifrados, los inyecta en el runtime y gestiona el proceso del gateway.

Si el bot deja de responder en Hermify, no depurás el gateway: revisás la tarjeta de estado en el dashboard y activás un reinicio si es necesario. El loop operativo está basado en el dashboard, no en SSH.

Eso es lo principal que cambia el hosting gestionado de Telegram: no la configuración de Telegram en sí, sino quién es responsable de mantenerla saludable. Podés comparar este enfoque directamente con una configuración autogestionada en VPS en la comparación entre hosting y self-hosting.