# 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 setup` y pruébala con `hermes gateway run`.
- Instala la pasarela como servicio en segundo plano; si el bot no responde, `hermes doctor` te 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](https://www.ionos.es/digitalguide/paginas-web/desarrollo-web/agentes-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](https://www.ionos.es/digitalguide/online-marketing/vender-en-internet/que-es-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.

## 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:

```bash
hermes
```

Haz 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:

```text
/newbot
```

BotFather te guiará durante el proceso de creación:

1. **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.
2. **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.
3. **Copiar el token del bot**: una vez creado el bot, BotFather te proporcionará un token para acceder a la [API](https://www.ionos.es/digitalguide/paginas-web/desarrollo-web/application-programming-interface-api/) de Telegram. Hermes utiliza este token para autenticar el bot ante la API, por lo que debes tratarlo como una contraseña.

Nota No publiques el token ni lo incluyas en capturas de pantalla, documentos públicos, publicaciones en foros o [repositorios](https://www.ionos.es/digitalguide/servidores/know-how/repositorio/) 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

<table>
  <thead>
    <tr>
      <th><strong>Dato de configuración</strong></th>
      <th><strong>Contenido</strong></th>
      <th><strong>Procedencia</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>TELEGRAM_BOT_TOKEN</td>
      <td>Token secreto de tu bot de Telegram</td>
      <td>Lo proporciona el bot oficial @BotFather después de ejecutar /newbot</td>
    </tr>
    <tr>
      <td>TELEGRAM_ALLOWED_USERS</td>
      <td>Tu ID numérico de usuario de Telegram</td>
      <td>Puede consultarse, por ejemplo, mediante @userinfobot</td>
    </tr>
    <tr>
      <td>Nombre de usuario del bot</td>
      <td>Nombre público y único del bot, que termina en bot</td>
      <td>Se establece al crear el bot con @BotFather</td>
    </tr>
  </tbody>
</table>

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:

```bash
hermes gateway setup
```

El 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.

Nota 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:

```bash
TELEGRAM_ALLOWED_USERS=123456789,987654321,555555555
```

De 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:

```bash
hermes gateway run
```

La 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:

1. **Comprobar el estado**: envía `/status`. Hermes debería mostrar información sobre la sesión actual.
2. **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.
3. **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:

```bash
hermes gateway install
```

Una vez instalada, puedes controlarla con los siguientes comandos:

```bash
hermes gateway start
hermes gateway stop
hermes gateway status
```

Si modificas la configuración de Telegram, es recomendable reiniciar la pasarela:

```bash
hermes gateway stop
hermes gateway start
```

También puedes reiniciarla directamente con:

```bash
hermes gateway restart
```

El 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:

```bash
sudo loginctl enable-linger $USER
```

A continuación, comprueba el estado de la pasarela:

```bash
hermes gateway status
```

Por ú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:

```bash
hermes doctor
```

Hermes 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:

```bash
hermes doctor --fix
```

A 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:

```bash
hermes gateway stop
hermes gateway run
```

De 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:

```bash
hermes gateway setup
```

Puedes 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:

```bash
sudo hermes gateway install --system
sudo hermes gateway start --system
```

Para comprobar su estado, utiliza:

```bash
sudo hermes gateway status --system
```

Puedes consultar los mensajes del registro en tiempo real con:

```bash
journalctl -u hermes-gateway -f
```

systemd 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](https://www.ionos.es/digitalguide/servidores/know-how/docker-container/) 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:

```bash
docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent gateway run
```

La 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.

Consejo [Docker](https://www.ionos.es/digitalguide/servidores/know-how/que-es-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_USERS` contiene solo los ID numéricos de las personas autorizadas expresamente.
- `GATEWAY_ALLOW_ALL_USERS` no 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.

## 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](https://www.ionos.es/digitalguide/servidores/know-how/vps-que-es-un-servidor-virtual-privado/), 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.


This is a markdown version of: [https://www.ionos.es/digitalguide/servidores/configuracion/conectar-hermes-agent-con-telegram/](https://www.ionos.es/digitalguide/servidores/configuracion/conectar-hermes-agent-con-telegram/) for AI/LLM consumption.