Hermes Agent en Telegram: corre tus agentes desde una nota de voz

Un board es donde decides. Un chat es donde operas. Corre los dos a través del mismo agente y el que nunca duerme se va a tragar al que se supone que piensa, a menos que los mantengas como dos superficies distintas a propósito.

Corro el gateway de Telegram de Hermes Agent como mi asistente personal. Le hablo por voz, casi siempre lejos del teclado, y abre issues en mi propio board de Paperclip sin que yo abra la web app. Esto es de lo que está hecho realmente ese gateway, verificado contra el código, y la regla con la que lo corro: el chat es donde operas, no donde decides.

Hermes Agent en Telegram: qué hace realmente el gateway

La integración de Telegram de Hermes Agent es uno de 22 plugins de plataforma, construido sobre python-telegram-bot, que convierte un chat de Telegram en una superficie para el mismo agente que ya corre tu shell, tu memoria y tus herramientas MCP. Creas el bot a través de @BotFather, pegas el token en ~/.hermes/.env como TELEGRAM_BOT_TOKEN, y el gateway se conecta por long polling (el default, saliente desde tu servidor) o por webhook (entrante, para plataformas cloud que necesitan dormir entre mensajes y despertar solas con tráfico).

Nada de esto es plomería exclusiva de Telegram pegada a un chatbot. El gateway es el mismo proceso que habla con más de 25 plataformas de mensajería, y Telegram recibe el set completo de features: threads y forum topics, ediciones de mensaje en streaming, media nativa, teclados inline, slash commands y un transporte de red de respaldo para cuando la conexión principal no anda bien.

Lo que Telegram toca en un perfil de Hermes

• ~/.hermes/// HERMES_HOME
  • .envsecreto// TELEGRAM_BOT_TOKEN, TELEGRAM_ALLOWED_USERS
  • config.yaml
    • platforms.telegram.extra// menciones, threads, proxy, estado
    • stt// notas de voz de entrada
    • tts// burbujas de voz de salida
    • mcp_servers// el board, conectado como cliente
  • pairing/// chmod 0600, una fila por usuario aprobado

Pairing, allowlists y la sesión de grupo compartida

Solo dos cosas decides a quién le responde el bot: un ID numérico de usuario de Telegram en el allowlist, o un código de pairing que aprobaste. TELEGRAM_ALLOWED_USERS es una lista estática, separada por comas, de IDs, leída al arrancar. El camino más útil para cualquiera que no sea tú es el DM pairing: a un remitente no aprobado le llega un código de un solo uso, te lo reenvía por cualquier canal, y tú corres hermes pairing approve telegram <code> sin reiniciar el gateway. Los códigos expiran después de una hora, una plataforma acepta como máximo tres códigos pendientes a la vez, cinco intentos de aprobación fallidos disparan un bloqueo de una hora, y los registros de pairing en disco son chmod 0600. TELEGRAM_ALLOW_ALL_USERS existe y está documentado como solo para dev, porque el bot tiene acceso a shell.

Los grupos agregan una capa que casi todos entienden mal una vez: el modo de privacidad de Telegram viene activado por defecto, así que un bot en un grupo solo ve slash commands, respuestas a sus propios mensajes y eventos de servicio, nunca la charla normal, hasta que apagas la privacidad en BotFather y sacas y vuelves a agregar al bot (Telegram cachea el setting viejo en las membresías existentes). Con telegram.require_mention: true, Hermes solo responde a un /command, una respuesta, un @mention o un patrón de wake-word configurado. Agrega observe_unmentioned_group_messages: true encima de un chat en el allowlist y el bot lee sin responder: las líneas sin mención se agregan a la transcripción compartida de la sesión del chat o del topic como contexto, cada una etiquetada con el nombre y el ID del remitente y con su propia instrucción por turno que le dice al modelo que esas líneas son contexto, no comandos. Una mención después trae toda esa transcripción. Eso es lo más parecido a una sesión de grupo que tiene Hermes: una transcripción por chat o topic, compartida por quien esté en el allowlist.

Aprobar un comando riesgoso desde el chat

Cuando Hermes quiere correr un comando marcado como riesgoso, publica una card con teclado inline en el mismo chat, con cuatro botones: aprobar una vez, aprobar para la sesión, permitir siempre, o denegar. El header de la card es literal: “Hermes quiere correr un comando que necesita tu OK”, con una línea abajo que dice por qué se marcó. El silencio es un no seguro: el timeout de aprobación por defecto es 300 segundos, y la card te lo dice antes de expirar. Esta card se renderiza igual en cada superficie de mensajería, Telegram incluido, a través de un módulo compartido, así el texto nunca cambia entre plataformas.

Esa es la parte de “operar desde el chat” que realmente importa. Un feed de notificaciones te dice qué pasó. Una card de aprobación te deja decidir si pasa, desde el mismo thread en el que ya estabas, sin cambiar a una terminal.

Notas de voz: de voz a texto sin salir del chat

Una nota de voz que mandas por Telegram se transcribe automáticamente con el provider de speech-to-text que configuraste, y después se inyecta en la conversación como texto. stt es una sección de primer nivel en config.yaml, no un setting específico de Telegram, así que el mismo provider también maneja tus notas de voz en Discord, Signal o WhatsApp:

stt:
  enabled: true
  provider: "local" # "local" (free) | "groq" | "openai" | "mistral" | "xai"

tts:
  provider: "edge" # "edge" (free) | "elevenlabs" | "openai" | ...

Vale la pena conocer tres por nombre: local corre faster-whisper en la máquina que hostea Hermes y no necesita ninguna API key, groq llama a Groq Whisper y lee GROQ_API_KEY, openai llama a OpenAI Whisper y lee VOICE_TOOLS_OPENAI_KEY. Poner stt.enabled: false se salta la transcripción por completo: el gateway igual cachea el archivo de audio y le pasa al agente su ruta en cambio, útil si quieres un pipeline propio (diarización, otro modelo) en vez del de Hermes.

Las respuestas vuelven de la misma forma. El output de TTS se entrega como una burbuja de voz nativa de Telegram, la redonda que se reproduce inline, cuando el provider es OpenAI o ElevenLabs (los dos producen Opus directamente). Edge TTS, el default gratuito, saca MP3 y necesita ffmpeg en el host para convertirlo a Opus para la burbuja; sin ffmpeg igual lo manda, solo que como un archivo de audio normal.

El bot token es un secreto. Trátalo como uno

TELEGRAM_BOT_TOKEN está marcado como password: true en el propio manifest del plugin, y por una razón que va más allá de la convención: cualquiera que lo tenga puede leer cada mensaje que tu bot pueda ver y enviar mensajes como si fuera él. Hermes trae un camino de redacción dedicado para ese string exacto, construido en agent/redact.py, que saca el token de cualquier URL api.telegram.org/bot<TOKEN>/... antes de que llegue a una línea de log.

Esa redacción tuvo huecos, y los propios tests de regresión del proyecto los documentan: cuatro call sites en el adapter de Telegram construían su texto de error directo desde la excepción cruda en vez de la versión redactada, y el peor de los cuatro dejaba la URL sin redactar en un archivo de estado que mira el dashboard, no solo en un log. Un fix cerró los cuatro. Lo menciono porque yo mismo me topé con la versión general de este bug: un dump de config.yaml dentro de una sesión de Hermes escribió mis API tokens directo en el log de la sesión una vez, y los roté. El código de redacción es una mitigación, no una garantía. Si un token puede imprimirse, asume que en algún momento lo va a hacer, y mantén a cada uno a un /revoke de distancia de estar muerto.

Cómo lo corro yo: el board decide, el chat opera

Tres capas, un harness

1. 1

   Paperclip

   El board. Trabajo estratégico y táctico: los heads corren sus ciclos, los especialistas entregan contra una barra de aceptación, los heads juzgan lo que vuelve, y yo decido en el gate. Acá es donde decido.

   +
2. 2

   Telegram

   El chat. Trabajo operativo: haz esto ahora, aprueba este comando, transcribe esta nota de voz. Acá es donde opero, casi siempre lejos del teclado.

   +
3. 3

   Hermes

   La memoria. El mismo harness, los mismos modelos, los mismos MCP servers, los mismos skills, consultados por las dos capas de arriba.

El board es donde decido. El chat es donde opero. La memoria del agente es lo que leen los dos.

El board de Paperclip está conectado a mi Hermes orientado a Telegram como un MCP server, el oficial @paperclipai/mcp-server, que expone cuarenta y una herramientas sobre la API del board. Vive en el mismo bloque mcp_servers de config.yaml que Hermes usa para cualquier otro MCP server, con la URL de Paperclip y una API key pasada en su entorno.

Di una frase como “escribe un script sobre el tema X” en Telegram, por voz o por texto, y esa frase se vuelve un issue de Paperclip, a través de una de esas cuarenta y una herramientas. No es Hermes el que hace el trabajo. Es Hermes archivando el trabajo donde mi empresa de agentes lo va a tomar con su propio horario. Operar y decidir se quedan en dos lugares distintos, a propósito.

Antes de construirlo así, exploré un diseño distinto: un cron job dentro de Paperclip que leyera periódicamente los exports de sesión propios de Hermes y los plegara en la memoria de Paperclip, una proyección de read-model en vez de un puente en vivo. Se quedó en exploración. Nunca lo construí. Lo que terminé lanzando fue más simple y push-based: Telegram le habla al board directamente, a través de un MCP server, en el momento en que lo pido.

En mi trabajo, un Hermes separado corre con un cron job en vez de un chat: un briefing diario que lee las fuentes MCP de la empresa y me escribe, sin ninguna superficie de chat. El chat no es la única forma de operar un agente. Es la forma que te deja interrumpirlo.

Hermes Agent vs OpenClaw en Telegram

En Telegram específicamente, Hermes Agent y OpenClaw lo traen los dos como un canal de primera clase con profundidad real de features, pero no se ponen de acuerdo en quién arranca la conversación. Hermes solo habla por Telegram cuando le escribes o cuando dispara un cron job. El heartbeat de OpenClaw despierta al agente con un timer, cada 30 minutos por defecto (una hora con Anthropic OAuth), y lo deja decidir si algo merece un mensaje para ti, sin que se lo pidan.

Dónde difieren los dos en un setup chat-first

Los dos corren bien en Telegram. La diferencia real es quién arranca la conversación.

	Hermes Agent	OpenClaw
Detrás	Nous Research, un model lab	OpenClaw Foundation, una 501(c)(3)
Despierta solo	Solo cron jobs, sin heartbeat ambiente	Heartbeat cada 30 minutos por defecto
Costo de despertar ambiente	Ninguno: nada dispara sin un trigger	Unos 100k tokens por beat, 2k a 5k con isolatedSession
Memoria en la superficie de chat	MEMORY.md, USER.md, búsqueda full-text de sesiones	MEMORY.md, USER.md, notas diarias, consolidación dreaming

Si quieres que el bot arranque la conversación solo, el heartbeat de OpenClaw hace eso nativamente, a un costo de tokens que ajustas con isolatedSession. Si un orquestador o un cron job ya es tu heartbeat, como el mío, esa feature es overhead puro. La comparación más larga, leída desde los dos codebases, está en Hermes Agent vs OpenClaw.

Hermes Agent en iMessage: mismo gateway, otro bridge

Hermes Agent llega a iMessage a través de BlueBubbles, un servidor macOS open source separado que conecta iMessage con cualquier dispositivo. Es el mismo agente, la misma memoria, las mismas cards de aprobación, detrás de un bridge distinto con un requisito duro que Telegram no tiene: un Mac siempre encendido, con sesión iniciada en Messages.app, corriendo BlueBubbles Server. Apuntas a Hermes ahí con una URL de servidor y una contraseña, igual que lo apuntas a un bot token de Telegram, y el gateway lo trata como un adapter de plataforma más.

Si tu superficie de operación tiene que ser un número de teléfono al que tu familia ya le escribe, esta es la razón honesta para aceptar la dependencia de un Mac. Si no tiene que serlo, Telegram solo te pide un bot gratis y un VPS, nada más.

Hermes Agent en WhatsApp: el bridge que te puede banear

Si tu app de chat de todos los días es WhatsApp, como la de la mayoría en Latinoamérica y España, esta es la sección que de verdad te importa.

La integración de WhatsApp por defecto de Hermes Agent es Baileys, un bridge no oficial que emula una sesión de WhatsApp Web. Sin cuenta de developer de Meta, sin verificación de negocio, y un riesgo real (aunque chico) de que WhatsApp marque el número. Hermes documenta dos modos: un número de bot dedicado (menor riesgo, más limpio para varios usuarios) o tu propio número en un self-chat (el más rápido de configurar, el peor para cualquier cosa más allá de pruebas). Para cualquiera que corra esto como algo más que un experimento personal, Hermes también incluye el camino oficial, la WhatsApp Business Cloud API, que cambia velocidad de setup por una cuenta de Meta Business, un webhook público, y cero riesgo de ban.

Telegram no tiene una división equivalente. Hay un bot, un token, una API oficial, que es parte de por qué es la superficie que yo corro.

Antes de que Telegram sea tu superficie de operación

• ✓Obligatorio:
  Tienes un board en otro lado que ya decide.Telegram es para operar, no para planear. Si solo tienes un chat, tienes una lista de tareas con pasos extra.
• ✓Obligatorio:
  Estás en un allowlist o con DM pairing, no con TELEGRAM_ALLOW_ALL_USERS.Un bot con acceso a shell y sin allowlist es una terminal pública con un nombre simpático.
• ✓Obligatorio:
  Leíste las cuatro opciones de la card de aprobación antes de necesitarlas.Una vez, sesión, siempre, denegar. Saber la diferencia antes de una solicitud de aprobación a las 2am es mejor que leerla recién en ese momento.
• ✓Obligatorio:
  Elegiste un provider de STT a propósito.Local no necesita ninguna key y corre en tu propia máquina. Groq y OpenAI necesitan una API key y cobran por uso. Decide antes de la primera nota de voz, no después.
• ✓Obligatorio:
  El bot token vive en .env, no en un mensaje que le pediste al agente que leyera en voz alta.La redacción existe y ha tenido huecos. Rótalo ante cualquier sospecha, el mismo día.

Hermes Agent en Telegram, respuestas rápidas

¿Cómo conecto Hermes Agent a Telegram?+

Crea un bot con @BotFather, pon el token en TELEGRAM_BOT_TOKEN dentro de ~/.hermes/.env, agrega tu ID numérico de usuario de Telegram a TELEGRAM_ALLOWED_USERS, y arranca el gateway. python-telegram-bot maneja la conexión, por long polling a menos que configures un webhook.

¿OpenClaw es mejor que Hermes Agent en Telegram?+

Difieren en quién arranca la conversación, no en profundidad de canal. El heartbeat de OpenClaw puede escribirte primero, con un timer. Hermes solo habla por Telegram cuando le escribes o cuando dispara un cron job. Elige el que coincida con si quieres un asistente ambiente o uno reactivo.

¿Hermes Agent soporta mensajes de voz en Telegram?+

Sí. Las notas de voz entrantes se transcriben con el provider de stt en config.yaml (local, gratis; groq, necesita GROQ_API_KEY; openai, necesita VOICE_TOOLS_OPENAI_KEY) y se inyectan como texto.

Las respuestas pueden volver como burbujas de voz nativas a través de tts, usando OpenAI, ElevenLabs o el provider gratuito Edge TTS (el último necesita ffmpeg instalado para producir la burbuja redonda en vez de un archivo de audio plano).

¿Hermes Agent también funciona con WhatsApp o iMessage?+

Sí, como adapters de plataforma separados con el mismo sistema de memoria y aprobación detrás. iMessage pasa por BlueBubbles y necesita un Mac siempre encendido. El camino por defecto de WhatsApp es un bridge no oficial con un riesgo chico de ban; existe un camino con la WhatsApp Business Cloud API para quien necesite la ruta oficial en cambio.

¿Mi bot token de Telegram está seguro con Hermes Agent?+

Hermes lo marca como secreto y tiene código dedicado para sacarlo de las líneas de log y del texto de error. Esa redacción tuvo huecos documentados en el pasado, ya arreglados. Trata el token como cualquier otra credencial: mantenlo fuera de archivos .env que otros puedan leer, y rótalo en el momento en que sospeches que se imprimió en algún lado.

¿Qué pasa si no apruebo un comando riesgoso en Telegram?+

No corre nada. La card de aprobación expira a los cinco minutos por defecto, y la card misma lo dice: el silencio es un no seguro, no un sí por defecto.