Hermes Agent no responde en Telegram: soluciones rápidas

El bot funcionaba y de repente no

Envías un mensaje. No llega nada. El bot sigue en tu chat, su avatar sigue ahí, pero la respuesta no aparece. Es el problema más común de Hermes Agent en Telegram, y el motivo por el que la gente se pasa una hora con él es casi siempre el mismo: empiezan a intentar arreglos antes de saber qué capa se ha roto.

Hermes en Telegram son en realidad tres cosas apiladas. El proceso agente de Hermes (razonamiento y herramientas). El gateway de Hermes (long-polling contra Telegram). Y el propio Telegram (config de BotFather, allowed users, modo privado). Cuando el bot se queda mudo, el fallo está exactamente en una de esas capas, y el camino más rápido de vuelta es aislar cuál antes de tocar nada.

Esta guía recorre las comprobaciones en el orden que caza más rápido las causas más habituales. Si ya seguiste la guía general de troubleshooting de Telegram, esta es la versión corta y basada en síntomas para el caso concreto de "no responde nada".

Comprobación 1: ¿tu user ID está de verdad en la lista permitida?

Nueve de cada diez veces es esto. Hermes no responderá a nadie cuyo ID numérico de Telegram no esté en telegram_allowed_users. El bot recibe el mensaje, el gateway lo enruta, y Hermes lo descarta en silencio. Desde tu lado se parece exactamente a un bot muerto.

Dos cosas suelen salir mal aquí:

Pusiste @usuario en lugar del ID numérico. @usuario no es lo que Hermes quiere. Envía /start a @userinfobot en Telegram, copia el número que te responda y usa ese.
Añadiste un usuario nuevo después del último reinicio y no recargaste la config. Hermes lee telegram_allowed_users al arrancar. Cámbialo y reinicia el gateway.

La config vive en config.yaml:

telegram_allowed_users: "123456789,987654321"

Si estás en Hermify, el campo equivalente está en el formulario de credenciales del dashboard.

Comprobación 2: demuestra que el gateway está corriendo

Antes de culpar a Telegram, demuestra que el gateway está arriba.

hermes gateway status

Si no está corriendo, ese es tu problema. Arráncalo:

hermes gateway start

Si está corriendo pero el bot sigue mudo, sigue el log mientras envías un mensaje de prueba:

tail -f ~/.hermes/logs/agent.log

Buscas una de tres cosas. Una línea "message received" significa que el gateway hace su trabajo y es Hermes quien descarta el mensaje en silencio (vuelve a la Comprobación 1). Una línea "409 Conflict" significa que dos procesos hacen polling con el mismo token (ver Comprobación 4). Nada de nada significa que el gateway no llega a Telegram (ver Comprobación 5).

Comprobación 3: ¿el bot token sigue siendo válido?

BotFather deja revocar tokens y es fácil revocar uno de un bot de prueba viejo, olvidarte y preguntarte por qué nada funciona.

Abre Telegram, escribe a @BotFather, envía /mybots, elige tu bot, toca API Token y compara la cadena que muestra con la que tienes en la config de Hermes. Deben coincidir carácter a carácter. Si no coinciden, o pegas la actual en Hermes y reinicias, o pulsas Revoke current token en BotFather para generar una nueva y pegas esa.

Un token inválido aparece como un error "Unauthorized" en el log de Hermes al arrancar. Si ves ese error, siempre es el token.

Comprobación 4: ¿hay dos procesos haciendo polling del mismo bot?

La Bot API de Telegram permite exactamente un consumidor de long-poll por token de bot. Si dos procesos llaman a getUpdates a la vez, Telegram devuelve "409 Conflict: terminated by other getUpdates request" y las actualizaciones empiezan a irse al proceso que gane cada ciclo, o a ninguno. Desde tu lado, el bot parece que se salta un mensaje sí y otro también.

La forma más común de que pase esto no es exótica:

Una unit de systemd corre Hermes y además arrancaste otra sesión de Hermes a mano en tmux.
Estás probando un bot de dev en tu portátil pero la instancia de producción usa el mismo token.
Levantaste un worker en segundo plano y olvidaste que el contenedor viejo sigue arriba.

Encuentra al duplicado:

ps aux | grep -E 'telegram|hermes' | grep -v grep

Mata al que no querías conservar y reinicia el que queda. Los 409 desaparecen en segundos porque Telegram libera la sesión de long-poll obsoleta en cuanto el cliente perdedor se desconecta.

Comprobación 5: en grupos, el silencio suele ser el modo privado

Si el bot funciona en un mensaje directo pero no en un grupo, casi siempre es el modo privado de bots de Telegram, no Hermes.

El modo privado está activado por defecto en todos los bots nuevos. Significa que el bot solo ve mensajes que le mencionan directamente, que responden a alguno de sus mensajes o que llegan como comandos. La conversación normal del grupo nunca llega a tu gateway de Hermes.

Dos formas de arreglarlo:

Haz al bot admin del grupo. Los bots admin lo ven todo, y es la opción menos sorprendente.
Desactiva el modo privado. En BotFather envía /setprivacy, elige el bot, marca Disable. Después saca al bot del grupo y vuélvelo a añadir. Los cambios de modo privado solo se aplican al volver a añadirlo.

Si tu bot está en un topic o hilo de foro, confirma también que la config de Hermes cubre ese thread concreto en allowed_chats y los IDs de topic. Un bot con permiso para hablar en el canal general seguirá mudo en un hilo de operaciones si ese ID de topic no está en la lista.

Comprobación 6: tu red está matando el long-poll

Si el bot responde una vez al empezar y luego se queda mudo exactamente el mismo tiempo cada vez antes de revivir, tu red está cerrando el long-poll inactivo antes de que Telegram le pueda entregar una actualización. Routers domésticos, VPS baratos y redes corporativas hacen esto mucho con timeouts de NAT.

Activa logs de debug y mira:

export HERMES_LOG_LEVEL=debug
hermes gateway restart

Entradas "connection reset" repetidas a un intervalo fijo confirman el diagnóstico. Acorta el timeout de polling de Hermes para que reconecte más a menudo que el idle timeout de tu red:

hermes config set messaging.telegram.poll_timeout 30

El valor por defecto es 60. Bájalo a 30 o menos y el problema del reset se va, porque cierras y reabres el long-poll antes de que a la red le dé tiempo de aburrirse. Es la misma causa raíz que hay detrás de muchos "funciona en local, se rompe tras el deploy" en infraestructura barata.

Comprobación 7: el loop del agente se cayó en silencio por un error del proveedor

El gateway está arriba, el token está bien, la lista de permitidos es correcta, pero las respuestas siguen sin llegar. Busca en el log un error del proveedor del modelo cerca de la última respuesta que sí funcionó. Rate limits, cuotas agotadas y respuestas 5xx del proveedor del LLM pueden tumbar el loop del agente en algunas versiones de Hermes sin que se reinicie. El gateway sigue haciendo polling, recibe tu mensaje nuevo, se lo pasa y al otro lado no hay nadie que responda.

El arreglo es un reinicio más revisar el dashboard del proveedor por el problema subyacente. Si estás en el tier gratis de un proveedor y te has quedado sin cuota diaria a mitad de conversación, el bot va a parecer "no responde" hasta que la ventana de cuota rote. Sube a un plan de pago o cambia de proveedor desde la config de Hermes a otro backend y reinicia el gateway.

Un orden de diagnóstico de dos minutos que funciona

Cuando tienes prisa, sigue este orden y llegarás a la causa en menos de dos minutos en todos los casos reales que hemos visto:

hermes gateway status - ¿está arriba?
tail -f ~/.hermes/logs/agent.log - ¿un mensaje fresco llega siquiera a Hermes?
Si sí, revisa telegram_allowed_users.
Si no, busca "409 Conflict" (poller duplicado) o "Unauthorized" (token revocado) en el log.
Si nada de lo anterior y el bot solo está mudo en grupos, es el modo privado.
Si nada de lo anterior y se calla a intervalos regulares, es el idle timeout de tu red.
Si nada de lo anterior y se calló tras ir bien, es un crash aguas arriba del proveedor.

Sáltate el loop de debugging por completo

Cada comprobación de arriba existe porque Telegram, el gateway, Hermes y tu proveedor son cuatro piezas móviles que pueden fallar de forma independiente. Cuando todas viven en tu infraestructura, eres tú quien recibe el aviso cada vez que una falla.

Hermify es un Hermes Agent gestionado en Telegram. Tu bot token, la lista de allowed users y la clave del proveedor van al dashboard una sola vez. El gateway, los reinicios, la captura de logs y la lógica de reconexión corren por nuestra cuenta. Cuando algo aguas arriba se porta mal, la tarjeta de estado del dashboard te dice qué capa, y un clic la reinicia. No vuelves a abrir ~/.hermes/logs/agent.log si no quieres.

Empieza con Hermify y vuelve a poner el bot en marcha en alrededor de un minuto, con memoria que sigue siendo tuya.