Conectar Hermes Agent con Telegram y acceder de forma remota
Puedes controlar de forma remota Hermes Agent a través de Telegram, independientemente del dispositivo que utilices. El agente sigue alojado en tu propio equipo o servidor y el acceso se realiza mediante un bot de Telegram. Para protegerlo, puedes autorizar únicamente determinados ID de usuario. Si quieres que esté disponible de forma permanente, puedes ejecutar la pasarela en un servidor Linux o VPS.
Resumen
- La pasarela de mensajería conecta tu Hermes Agent alojado en tu propio equipo o servidor con Telegram, que solo actúa como interfaz.
- Crea un bot con BotFather y copia su token secreto.
- Averigua tu ID numérico de usuario de Telegram y añádelo a los usuarios autorizados.
- Configura la pasarela con
hermes gateway setupy pruébala conhermes gateway run. - Instala la pasarela como servicio en segundo plano; si el bot no responde,
hermes doctorte ayuda a diagnosticar el problema. - Para tener Hermes disponible las 24 horas, ejecútalo en un servidor Linux o VPS. Normalmente no es necesario abrir ningún puerto público.
¿Cómo funciona la conexión entre Hermes Agent y Telegram?
La pasarela de mensajería de Hermes Agent es la interfaz nativa que permite conectar Hermes Agent alojado en tu propio equipo o servidor con plataformas de chat externas como Telegram. La pasarela recibe los mensajes, los asigna a una sesión y los envía al agente. Después, devuelve las respuestas al chat de Telegram correspondiente.
De este modo, puedes comunicarte con Hermes Agent desde la app de Telegram en tu smartphone, tablet u otro ordenador. El agente de IA continúa ejecutándose en tu propio ordenador o servidor, mientras que Telegram funciona como interfaz de acceso para enviar mensajes y recibir las respuestas.
Para configurar la conexión necesitas tres elementos: un bot de Telegram, el token secreto del bot y tu ID de usuario de Telegram para autorizar el acceso. Después, solo tienes que iniciar la pasarela de mensajería de Hermes. Si quieres mantenerla disponible de forma permanente, también puedes configurarla como servicio en segundo plano en un servidor Linux.
- Listo para Hermes: acceso root, optimizado para SSH, operativo en minutos
- Rápido de forma constante: SSD NVMe y 1 Gbit/s, sin limitaciones
- Seguro: integraciones API personalizadas y compatibilidad con Docker
Requisitos para conectar Hermes Agent con Telegram
Antes de empezar, Hermes Agent debe estar instalado y funcionar correctamente. Para comprobarlo, abre un terminal e inicia Hermes sin Telegram:
hermesbashHaz una pregunta sencilla y comprueba que el agente responde.
Además, necesitas:
- una cuenta de Telegram
- acceso al terminal del equipo en el que se ejecuta Hermes
- un proveedor de modelos ya configurado
- conexión a Internet en el sistema donde se ejecuta Hermes
Crear un bot de Telegram con BotFather
Un bot de Telegram es una cuenta especial gestionada por software en lugar de por una persona. Para crear y administrar bots, Telegram ofrece el bot oficial @BotFather. Abre Telegram, busca la cuenta @BotFather y asegúrate de seleccionar el bot oficial. A continuación, envíale este comando:
/newbottextBotFather te guiará durante el proceso de creación:
- Elegir el nombre del bot: primero, BotFather te pedirá un nombre para el bot. Este será el nombre que aparecerá posteriormente en los chats de Telegram. No tiene que ser único y puedes cambiarlo más adelante.
- Elegir un nombre de usuario único: a continuación, tendrás que asignar al bot un nombre de usuario único en Telegram. Debe terminar en
bot, por ejemplo,mi_hermes_agent_bot. Si el nombre que quieres utilizar ya está ocupado, tendrás que elegir otra variante. - Copiar el token del bot: una vez creado el bot, BotFather te proporcionará un token para acceder a la API de Telegram. Hermes utiliza este token para autenticar el bot ante la API, por lo que debes tratarlo como una contraseña.
No publiques el token ni lo incluyas en capturas de pantalla, documentos públicos, publicaciones en foros o repositorios de Git de acceso público. Cualquier persona que conozca el token puede controlar el bot a través de la API de bots de Telegram. Si lo expones por error, puedes revocarlo desde BotFather con el comando /revoke y generar uno nuevo.
¿Cómo encontrar tu ID de usuario de Telegram?
Además del token, Hermes necesita tu ID de usuario de Telegram. Se trata de un identificador numérico único que no debes confundir con el nombre que aparece en tu perfil ni con tu nombre de usuario. Mientras que el nombre de usuario puede cambiar, Hermes utiliza este ID numérico para controlar quién puede acceder al bot.
Para averiguar tu ID, puedes abrir en Telegram un bot externo como @userinfobot e iniciar el chat o enviarle cualquier mensaje. El bot te mostrará distintos datos de tu cuenta. Copia el número correspondiente a tu ID de usuario.
Datos necesarios para configurar Telegram
| Dato de configuración | Contenido | Procedencia |
|---|---|---|
TELEGRAM_BOT_TOKEN |
Token secreto de tu bot de Telegram | Lo proporciona el bot oficial @BotFather después de ejecutar /newbot |
TELEGRAM_ALLOWED_USERS |
Tu ID numérico de usuario de Telegram | Puede consultarse, por ejemplo, mediante @userinfobot |
| Nombre de usuario del bot | Nombre público y único del bot, que termina en bot |
Se establece al crear el bot con @BotFather |
Para una instalación personal de Hermes, normalmente basta con añadir tu propio ID de usuario. Si más adelante quieres permitir el acceso a varias personas, puedes añadir sus ID separados por comas.
Configurar la pasarela de Hermes Agent desde la CLI
Hermes incluye un asistente interactivo que te guía paso a paso por la configuración de Telegram desde la línea de comandos. Abre un terminal en el equipo donde tengas instalado Hermes Agent y ejecuta:
hermes gateway setupbashEl asistente mostrará las plataformas de mensajería compatibles. Selecciona Telegram con las teclas de dirección y confirma con Intro. Después, introduce los siguientes datos:
- la plataforma que quieres utilizar
- el token del bot de Telegram
- los ID de usuario de Telegram autorizados
Introduce como token el valor que te ha proporcionado BotFather y, en el campo de usuarios autorizados, añade el ID numérico de Telegram que has obtenido anteriormente. El asistente guardará estos datos en la configuración de Hermes. El token permite conectar Hermes con el bot de Telegram que has creado.
El ID de usuario como control de acceso
Dependiendo de su configuración, Hermes Agent puede acceder a archivos, ejecutar programas y comandos del terminal, y utilizar otras herramientas. Por este motivo, permitir el acceso público al bot supone un riesgo considerablemente mayor que en el caso de un chatbot convencional de preguntas y respuestas.
Hermes aplica por defecto una política restrictiva: los usuarios que no estén autorizados no pueden ejecutar tareas a través del agente. En los mensajes directos, y según la configuración utilizada, un usuario desconocido puede recibir un código de emparejamiento para solicitar acceso, pero no obtiene acceso al agente hasta que se le autoriza.
Si utilizas el bot únicamente de forma privada, limitar el acceso mediante una lista fija de ID de usuario es una opción sencilla y fácil de controlar.
No confíes únicamente en la protección predeterminada. Envía un mensaje al bot desde una cuenta de Telegram que no esté autorizada y comprueba que no pueda ejecutar tareas con Hermes.
Evita configurar GATEWAY_ALLOW_ALL_USERS=true si Hermes tiene acceso al sistema o al terminal. Esta opción elimina la restricción global de acceso y permite que cualquier usuario que pueda contactar con el bot interactúe con el agente.
Autorizar el acceso a varias personas
Si quieres permitir que varias personas de confianza utilicen el mismo bot, introduce sus ID de Telegram separados por comas:
TELEGRAM_ALLOWED_USERS=123456789,987654321,555555555bashDe forma predeterminada, todas las personas incluidas en esta lista pueden acceder al mismo agente y a las herramientas que tenga disponibles. Por tanto, añade únicamente los ID de personas que deban tener acceso al sistema. Hermes mantiene separadas las conversaciones de los distintos usuarios de Telegram, aunque todos ellos acceden a las funciones y herramientas disponibles en el mismo agente.
Activar la pasarela de Telegram y comprobar la conexión
Una vez terminada la configuración, conviene iniciar primero la pasarela directamente desde el terminal para comprobar que funciona correctamente. Ejecuta:
hermes gateway runbashLa pasarela se ejecutará en primer plano, por lo que podrás ver directamente en el terminal los mensajes de estado y los posibles errores. Mantén esta ventana abierta durante la prueba. Si la conexión se establece correctamente, debería aparecer un mensaje indicando que el adaptador de Telegram está conectado.
A continuación, abre en Telegram el bot que has creado y envíale un mensaje. Realiza estas pruebas una a una:
- Comprobar el estado: envía
/status. Hermes debería mostrar información sobre la sesión actual. - Hacer una pregunta: envía al agente una consulta como «¿Qué herramientas del sistema tienes disponibles actualmente? Indica solo sus nombres y no ejecutes ninguna». Así puedes comprobar que Hermes recibe el mensaje, lo procesa y devuelve la respuesta a través de Telegram.
- Iniciar una nueva conversación: envía
/new. Este comando inicia una nueva sesión sin el contexto de la conversación anterior. Si el bot responde correctamente a estas pruebas, la comunicación entre Telegram y Hermes funciona en ambos sentidos.
Cuando termines, detén la pasarela en el terminal con la combinación de teclas Ctrl+C.
Ejecutar la pasarela en segundo plano
Para no tener que mantener una ventana del terminal abierta, puedes instalar la pasarela como servicio en segundo plano:
hermes gateway installbashUna vez instalada, puedes controlarla con los siguientes comandos:
hermes gateway start
hermes gateway stop
hermes gateway statusbashSi modificas la configuración de Telegram, es recomendable reiniciar la pasarela:
hermes gateway stop
hermes gateway startbashTambién puedes reiniciarla directamente con:
hermes gateway restartbashEl comando hermes gateway start inicia el servicio en segundo plano que has instalado previamente. Si todavía no lo has instalado, ejecuta primero hermes gateway install. En cambio, hermes gateway run sirve para iniciar la pasarela en primer plano, por ejemplo, para realizar pruebas y ver directamente los mensajes de estado.
Si utilizas un servidor Linux o VPS y quieres que la pasarela siga funcionando después de cerrar la sesión, puedes habilitar el servicio de usuario para que permanezca activo:
sudo loginctl enable-linger $USERbashA continuación, comprueba el estado de la pasarela:
hermes gateway statusbashPor último, vuelve a enviar un mensaje al bot de Telegram. Debería responder aunque ya no tengas abierta una ventana del terminal con Hermes.
¿Qué hacer si el bot de Telegram no responde?
Como primer paso para diagnosticar el problema, ejecuta:
hermes doctorbashHermes comprobará, entre otros aspectos, la instalación, los principales valores de configuración y las dependencias necesarias. Si detecta algún problema, mostrará información en el terminal junto con posibles soluciones. Hermes también puede intentar corregir automáticamente algunos errores con:
hermes doctor --fixbashA continuación, comprueba si la pasarela está en funcionamiento. Si el bot sigue sin responder, revisa estos puntos uno por uno:
- ¿El token del bot está completo y no contiene espacios adicionales?
- ¿El ID numérico de usuario es correcto?
- ¿Has introducido el ID de usuario y no el nombre de usuario de Telegram?
- ¿La pasarela aparece activa al ejecutar
hermes gateway status? - ¿Hermes funciona directamente desde el terminal sin Telegram?
- ¿El equipo tiene conexión a Internet?
Para ver directamente los posibles errores, puedes detener el servicio en segundo plano e iniciar de nuevo la pasarela en el terminal:
hermes gateway stop
hermes gateway runbashDe este modo, los errores que se produzcan al establecer la conexión aparecerán directamente en el terminal.
Mantener Hermes Agent disponible las 24 horas con Telegram
Si ejecutas Hermes en un portátil u ordenador de sobremesa, el bot de Telegram solo estará disponible mientras el equipo esté encendido, conectado a Internet y la pasarela esté activa. Si apagas el dispositivo o entra en modo de suspensión, Hermes dejará de poder procesar los mensajes de Telegram.
Si quieres mantenerlo disponible las 24 horas, puedes instalar Hermes en un servidor Linux o en un servidor privado virtual (VPS). Un VPS es un ordenador virtual alojado en un centro de datos y disponible de forma permanente. Por lo general, puedes acceder a su terminal mediante una conexión SSH cifrada.
Trasladar Hermes a un servidor paso a paso
Primero, instala Hermes en el servidor Linux y configura allí el proveedor de modelos. A continuación, inicia un chat normal con Hermes para comprobar que funciona correctamente. Después, vuelve a ejecutar el asistente de configuración de la pasarela:
hermes gateway setupbashPuedes utilizar el mismo token del bot de Telegram y el mismo ID de usuario autorizado. Sin embargo, antes de iniciar el bot de forma permanente en el servidor, detén la pasarela que se ejecuta en tu equipo local. Así evitarás que dos instalaciones de Hermes intenten utilizar el mismo bot al mismo tiempo.
En un servidor Linux que esté siempre encendido, puedes instalar la pasarela como servicio del sistema para que se inicie automáticamente al arrancar el servidor:
sudo hermes gateway install --system
sudo hermes gateway start --systembashPara comprobar su estado, utiliza:
sudo hermes gateway status --systembashPuedes consultar los mensajes del registro en tiempo real con:
journalctl -u hermes-gateway -fbashsystemd mantiene la pasarela ejecutándose en segundo plano y permite que vuelva a iniciarse automáticamente después de reiniciar el servidor. Hermes distingue entre un servicio de usuario, pensado principalmente para ordenadores personales y de desarrollo, y un servicio del sistema para servidores que funcionan de forma permanente y sin interfaz gráfica.
En un VPS, evita ejecutar Hermes con permisos de administrador si no es necesario. Siempre que sea posible, utiliza un usuario de Linux específico sin acceso root ilimitado.
Ejecutar Hermes con Docker como alternativa
Docker permite ejecutar aplicaciones en contenedores aislados del sistema host. Esto facilita la ejecución permanente de Hermes y puede limitar el acceso directo de los procesos del agente al sistema del servidor, aunque el grado de aislamiento depende de cómo configures el contenedor y los volúmenes.
Después de completar la configuración inicial, puedes iniciar el contenedor oficial de Hermes en segundo plano, por ejemplo, con:
docker run -d \
--name hermes \
--restart unless-stopped \
-v ~/.hermes:/opt/data \
nousresearch/hermes-agent gateway runbashLa opción --restart unless-stopped hace que Docker vuelva a iniciar el contenedor después de un fallo o un reinicio del servidor, siempre que no lo hayas detenido expresamente. El directorio ~/.hermes montado en /opt/data permite conservar fuera del contenedor los datos de Hermes, como la configuración, las sesiones y las credenciales.
Docker no es necesario para conectar Hermes con Telegram. Si estás empezando, suele resultar más sencillo utilizar una instalación normal de Hermes junto con el servicio systemd que genera el propio programa.
Proteger la pasarela de Telegram en el servidor
Para conectar Hermes con Telegram, normalmente no es necesario abrir ningún puerto público en el servidor. De forma predeterminada, la pasarela utiliza long polling: Hermes establece una conexión saliente con los servidores de Telegram y consulta periódicamente si hay mensajes nuevos. Por tanto, Telegram no necesita acceder directamente al servidor desde Internet.
Si utilizas Telegram como única interfaz de acceso, no conviene exponer públicamente el puerto interno de la API de Hermes. Cada puerto adicional abierto hace que un servicio del servidor sea accesible desde Internet y puede aumentar la superficie de ataque.
Comprobaciones de seguridad para un funcionamiento continuo
Antes de ejecutar la pasarela de forma permanente, comprueba lo siguiente:
- El token del bot de Telegram está almacenado únicamente en la configuración protegida de Hermes.
TELEGRAM_ALLOWED_USERScontiene solo los ID numéricos de las personas autorizadas expresamente.GATEWAY_ALLOW_ALL_USERSno está activado.- Hermes no se ejecuta con permisos root o de administrador si no es necesario.
- Los puertos del servidor y de la API que no sean necesarios permanecen cerrados.
- Las credenciales no se almacenan en repositorios públicos de Git ni en archivos de registro accesibles públicamente.
- El sistema operativo y Hermes Agent se mantienen actualizados.
- Siempre que sea posible, las herramientas con un acceso amplio a archivos o al terminal se ejecutan en un entorno aislado.
Para instalaciones de producción, puedes utilizar, por ejemplo, un backend de terminal aislado basado en Docker. De este modo, los comandos ejecutados por el agente se ejecutan dentro de un contenedor en lugar de hacerlo directamente en el sistema del servidor. Este aislamiento no sustituye a la lista de usuarios autorizados de Telegram ni a la protección del token del bot, sino que añade una capa de seguridad adicional.
- NUEVO: Escala de forma flexible con VM-Cloning, Load Balancing, nuevas opciones de almacenamiento y más.
- Tráfico ilimitado, > 99,99 % de disponibilidad
- Atención 24/7 con asesor personal
Conclusión
Para conectar Hermes Agent con Telegram solo necesitas crear un bot mediante BotFather, obtener su token secreto y conocer tu ID numérico de usuario de Telegram. El comando hermes gateway setup te guía durante la configuración y permite restringir el acceso a los usuarios autorizados.
Después de realizar una primera prueba, puedes instalar la pasarela como servicio en segundo plano y mantenerla activa de forma permanente. Si ejecutas Hermes en un servidor Linux o VPS, podrás seguir accediendo al agente aunque tu propio ordenador esté apagado. Lo más importante es mantener en secreto el token del bot, autorizar únicamente los ID de usuario necesarios y, siempre que sea posible, aislar del sistema principal las herramientas del agente con acceso al terminal o a los archivos.

