Práctica con Hermes Agent: configura un asistente de IA para Telegram/Feishu/WeCom en todas las plataformas

Dificultad: media · Duración: ~20 minutos · Resultado: dominar la configuración clave para conectar Hermes en todas las plataformas

¿Te has preguntado alguna vez esto? Un mismo asistente de IA corriendo a la vez en Telegram, Feishu y WeCom, pero con un único despliegue. Hermes Agent puede hacerlo.

Se trata de un AI Agent de aprendizaje progresivo (self-improving) open source de Nous Research. Una de sus mayores ventajas es que trae incorporado un gateway de mensajería para todas las plataformas. Solo tienes que levantar un proceso en tu servidor para conectarte simultáneamente con 10+ plataformas, como Telegram, Discord, Slack, Feishu, WeCom, Signal y WhatsApp. El enrutamiento de mensajes es automático, la memoria se comparte entre plataformas, configuras una vez y queda habilitado de forma permanente.

En este artículo, conectaremos de una vez tres de las plataformas más usadas: Telegram, Feishu (Lark) y WeCom (Enterprise WeChat).

Público objetivo

Este artículo es para los siguientes desarrolladores:

Tienes una base razonable de Linux / línea de comandos y quieres autohospedar un AI Agent en un servidor
Necesitas integrar mensajería en múltiples plataformas como desarrollador independiente o equipo pequeño
Estás evaluando Hermes Agent como alternativa a OpenClaw

TIP

Si todavía no tienes una API Key para LLM, te recomiendo obtenerla en Defapi. En Defapi, la entrada de Claude Opus 4.6 cuesta $2.5 y la salida $12.5 por millón de tokens; es decir, la mitad del precio oficial. Ofrece una relación calidad-precio excelente. Los protocolos de interfaces admitidos se detallan en la documentación de Claude de Defapi.

Dependencias e entorno esenciales

Dependencia	Descripción
Python	3.11+ (el instalador se encarga de la instalación)
Sistema operativo	Linux (Ubuntu 22.04+), macOS o WSL2
Cuenta de la plataforma de mensajería	Token de Bot de Telegram / aplicación empresarial autoconstruida de Feishu / WeCom
LLM API Key	Recomendado: Defapi (Claude Opus 4.6 a mitad de precio)
Docker	Opcional; la versión v0.6.0 ya incluye soporte oficial para contenedores

WARNING

Windows nativo no está soportado. Instala WSL2 y realiza el trabajo dentro de la terminal de WSL2.

Estructura completa del proyecto

hermes-agent/
├── scripts/
│   └── install.sh              # Script de instalación en un solo paso
└── ~/.hermes/                   # Directorio principal de configuración (se genera automáticamente tras la instalación)
    ├── config.yaml              # Configuración central (modelos, conjunto de herramientas)
    ├── .env                     # API Keys (¡no se envía a Git!)
    ├── skills/                  # Directorio de skills
    ├── memory/                  # Memoria persistente
    ├── sessions/                # Historial de sesiones (búsqueda completa FTS5)
    └── gateway/                 # Configuración del gateway (YAML independiente por plataforma)
        ├── telegram.yaml
        ├── feishu.yaml
        └── wecom.yaml

Pasos guiados

Paso 1: Instalación de Hermes Agent en un solo paso

En Linux / macOS / WSL2, ejecuta el script de instalación oficial:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

El script instala automáticamente Python, Node.js y todas las dependencias; en todo el proceso no necesitas intervenir manualmente. Al terminar, recarga el shell:

source ~/.bashrc    # usuarios bash
source ~/.zshrc     # usuarios zsh

Verifica que la instalación se haya realizado correctamente:

hermes doctor

TIP

hermes doctor diagnostica automáticamente problemas del entorno: versión de Python, API Key, conectividad de red, dependencias de herramientas, etc. La primera vez, se recomienda encarecidamente ejecutarlo una vez antes.

Paso 2: Configura el proveedor LLM — conexión con Defapi

A continuación, tienes que decirle a Hermes dónde encontrar el modelo grande. Escribe tu API Key en el archivo .env:

hermes config set ANTHROPIC_API_KEY <tu-defapi-key>

Defapi es compatible con el protocolo de la interfaz v1/messages de Anthropic, así que Hermes puede conectarse directamente. También puedes seleccionar el modelo y el Provider de forma interactiva con el comando hermes model:

hermes model
# Selección interactiva:
# 1. Nous Portal
# 2. OpenRouter (200+ modelos)
# 3. OpenAI
# 4. Defapi / endpoint personalizado
# 5. Otros...

Si usas Defapi, en el menú interactivo elige el endpoint personalizado (Custom) e introduce:

API Endpoint: https://api.defapi.org
Model: anthropic/claude-opus-4.6

WARNING

El archivo .env contiene tu API Key. No la envíes nunca a un repositorio Git. Si despliegas con Docker, debes inyectarla mediante variables de entorno o Docker Secrets, no escribirla directamente en el Dockerfile.

Paso 3: Conecta la primera plataforma — Telegram Bot

Esta es la plataforma más fácil de validar, porque la API de Bot de Telegram es pública y no requiere certificación empresarial.

3.1 Crea el Bot

En Telegram busca @BotFather, envía /newbot, ponle un nombre siguiendo las instrucciones y obtén el BOT_TOKEN. El formato es similar a 123456789:ABCdefGHIjklMNOpqrsTUVwxyz.

3.2 Configura el gateway de Hermes

hermes gateway setup
# Selecciona telegram para entrar a la configuración interactiva

O crea manualmente ~/.hermes/gateway/telegram.yaml:

platform: telegram
enabled: true
bot_token: "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"

# Control de acceso: solo usuarios específicos
allowed_users:
  - your_telegram_username

# Ajustes de seguridad
require_approval_for_dangerous_tools: true

3.3 Verificación

Después de iniciar el gateway, envía un mensaje al Bot:

hermes gateway start
# o ejecutarlo en segundo plano:
hermes gateway start --daemon

En Telegram, envía /new al Bot: debería responder con un mensaje de bienvenida. Envía un mensaje en chino, por ejemplo «你好», y comprueba si la IA responde.

TIP

Si el Bot no responde, revisa: hermes gateway status para ver el estado de ejecución, y hermes logs para consultar los logs más recientes. Causas comunes: el Bot Token está mal o el puerto ya está en uso.

Paso 4: Conecta Feishu (aplicación empresarial de Lark)

La integración con Feishu es un poco más compleja: necesitas crear una aplicación empresarial autoconstruida en la plataforma abierta de Feishu.

4.1 Crea la aplicación en la plataforma abierta de Feishu

Abre Feishu Open Platform y crea una aplicación empresarial autoconstruida
En «Credenciales e información base», obtén el App ID y el App Secret
Activa la capacidad de «Bot» (Robot)

4.2 Configura las suscripciones de eventos

En «Event Subscription» (Suscripción de eventos) de la aplicación:

Para la dirección URL de solicitud, completa: https://tu-dominio/gateway/feishu/webhook
Eventos: selecciona im.message.receive_v1 (recepción de mensajes)

WARNING

Feishu exige que la URL de callback sea accesible desde Internet mediante HTTPS. Si tu servidor no tiene un dominio público, puedes usar ngrok para un túnel temporal dentro de la red: ngrok http 8080. Luego coloca la URL HTTPS generada en Feishu.

4.3 Instala la aplicación en la empresa

En «Version Management & Release» (Gestión y publicación de versiones), crea y publica una versión; de lo contrario, el Bot no podrá recibir mensajes.

4.4 Configura el gateway de Hermes

hermes gateway setup
# Selecciona feishu y completa interactivamente App ID y App Secret

Edita manualmente ~/.hermes/gateway/feishu.yaml:

platform: feishu
enabled: true
app_id: "cli_xxxxxxxxxxxxxx"
app_secret: "xxxxxxxxxxxxxxxxxxxx"
verification_token: "tu_verification_token"

# Cifrado de mensajes (opcional, pero recomendado)
encrypt_key: "tu_encrypt_key"

# Grupos y usuarios permitidos
allowed_chats: []
require_mention: false

4.5 Verificación

En Feishu, envía /new al Bot y mira si responde. El formato de mensaje de Feishu es distinto al de Telegram; el Bot admite tarjetas de mensajes con texto enriquecido y Hermes se adapta automáticamente.

Paso 5: Conecta WeCom (Enterprise WeChat)

La forma de integración de WeCom es similar a Feishu: también se realiza mediante callbacks tipo Webhook.

5.1 Crea la aplicación en el panel de administración de WeCom

Inicia sesión en WeCom Admin
Ve a «Application Management» → «Create Application» → elige «Enterprise self-built»
Obtén AgentId, Secret y el CorpId de la empresa
Configura «IP confiables de la empresa» con la IP de tu servidor

5.2 Configura la recepción de mensajes

En la configuración de la aplicación, activa el modo «Receive Messages» (Recepción de mensajes):

Completa el URL: https://tu-dominio/gateway/wecom/webhook
Elige «Modo compatible» o «Modo de eventos»

5.3 Configura el gateway de Hermes

# ~/.hermes/gateway/wecom.yaml
platform: wecom
enabled: true
corp_id: "wwxxxxxxxxxxxxxx"
agent_id: "1000001"
corp_secret: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
encrypt_mode: "safe"    # El modo seguro requiere configurar encoding_aes_key
encoding_aes_key: "tu_clave_aes_de_32_caracteres"

5.4 Verificación

En WeCom, localiza tu aplicación y envía un mensaje de prueba.

TIP

WeCom es estricto con los requisitos de la lista blanca de IP. Si despliegas en un servidor en la nube (por ejemplo, DigitalOcean o Hetzner), asegúrate de agregar la IP pública del servidor en la lista de IP confiables del panel de administración; de lo contrario, WeCom rechazará directamente los mensajes.

Paso 6: Inicia el gateway: ejecuta tres plataformas una sola vez

Después de completar la configuración de todas las plataformas, inicia el gateway con un comando:

hermes gateway start

Hermes cargará automáticamente todas las configuraciones de plataformas habilitadas dentro de ~/.hermes/gateway/ y arrancará en paralelo todos los adaptadores. Si alguna plataforma falla al iniciar (por ejemplo, Token incorrecto), no afectará al funcionamiento normal de las demás.

Usa hermes gateway status para ver el estado de ejecución de cada plataforma:

Platform  Status   Users   Messages
telegram  ● online   3         142
feishu    ● online   7          89
wecom     ● online   2          15

Para detener el gateway con Ctrl+C, o ejecútalo en segundo plano con --daemon:

hermes gateway start --daemon

Paso 7: Verificación de mensajes en múltiples plataformas

Ahora puedes enviar mensajes desde cada una de las tres plataformas al Bot para probar:

# Telegram
/new
你好，介绍一下你自己

# Feishu
/new
你是谁？

# WeCom
/new
有什么我能帮你的？

Las respuestas en los tres extremos son completamente一致as y la memoria se comparte: lo que dices en Telegram, Feishu y WeCom también lo saben. Ese es el valor más esencial de Hermes: una sola configuración, experiencia unificada en todas las plataformas.

TIP

Si quieres que cada plataforma ejecute una instancia distinta del Agent (modelo diferente, conjunto de habilidades diferente), puedes usar la nueva función Profiles de Hermes v0.6.0: hermes -p telegram profile create. Luego configura modelos y plataformas diferentes en cada profile. Los profiles están completamente aislados entre sí, sin interferencias.

Solución de problemas frecuente

1. El Bot de Telegram no recibe mensajes

Síntomas: El Bot no responde en absoluto y al revisar los logs no aparece ningún registro.

Pasos de diagnóstico:

# 1. Verifica que el Token sea correcto
hermes config get telegram.bot_token

# 2. Confirma que el puerto no esté ocupado
ss -tlnp | grep 8080

# 3. Si usaste modo webhook, revisa la configuración de la API de Bot de Telegram
# La Webhook URL debe ser accesible públicamente; para desarrollo local usa ngrok
ngrok http 8080

# 4. Reinicia el webhook (a veces el Bot queda atascado en el webhook antiguo)
curl -X POST "https://api.telegram.org/bot<YOUR_TOKEN>/deleteWebhook"

2. La verificación del callback en Feishu falla

Síntomas: En la plataforma abierta de Feishu aparece «Validación de callback URL fallida».

Pasos de diagnóstico:

# 1. Confirma que la URL pública es accesible
curl -X GET "https://your-domain.com/gateway/feishu/webhook"

# 2. Revisa la verificación de la firma de Feishu
# Feishu usa cifrado AES; encrypt_key debe coincidir con la configuración del backend
# Consulta los logs de Hermes:
hermes logs --platform feishu

WARNING

El modo de cifrado de Feishu (encrypt_mode) debe coincidir con la configuración del backend. Si en el backend seleccionaste «modo seguro», en la configuración de Hermes también debes poner encrypt_mode: safe y la encoding_aes_key correspondiente.

3. Mensajes de WeCom no generan respuesta

Síntomas: Enviar mensajes no obtiene ninguna respuesta y no hay registros en los logs.

Pasos de diagnóstico:

# 1. Confirma que CorpId / AgentId / Secret están bien
# 2. Lo más importante: revisa la lista blanca de IP
# WeCom requiere que la IP del servidor que llama a la API esté dentro de la lista de IPs confiables

# 3. Prueba para obtener AccessToken
curl "https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=wwxxx&corpsecret=secret"

# Si devuelve "errmsg": "ip not in whitelist", significa que la IP no fue agregada

4. El modelo no responde

Síntomas: El Bot recibe el mensaje, pero la IA no responde; se queda mostrando «thinking».

Pasos de diagnóstico:

# 1. Prueba si la API Key es válida
curl -X POST "https://api.defapi.org/api/v1/messages" \
  -H "Authorization: Bearer <your-key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"anthropic/claude-opus-4.6","messages":[{"role":"user","content":"hi"}],"max_tokens":10}'

# 2. Revisa la configuración del modelo
hermes config get model

# 3. Revisa fallback_providers (recomendado)
# En ~/.hermes/config.yaml, agrega un Provider de respaldo:
fallback_providers:
  - provider: openrouter
    api_key: "${OPENROUTER_API_KEY}"

TIP

Se recomienda configurar al menos un Provider de respaldo además de Defapi. Hermes v0.6.0 soporta fallback_providers en cadena: cuando el Provider principal haga timeout o devuelva un error, cambia automáticamente al respaldo para evitar que el Agent se caiga.

5. Error al ejecutar herramientas

Síntomas: El Bot responde diciendo que no puede ejecutar alguna operación.

Pasos de diagnóstico:

# 1. Revisa el conjunto de herramientas actualmente habilitado
hermes tools

# 2. Habilita las herramientas necesarias
hermes tools enable web_search
hermes tools enable terminal

# 3. Los comandos peligrosos requieren confirmación manual
# Revisa la configuración:
hermes config get approval_required
# Si se establece en true, todos los comandos peligrosos requerirán tu aprobación manual

6. Conflictos por concurrencia en múltiples plataformas

Síntomas: Un plataforma recibe mensajes, pero las otras plataformas no responden.

Pasos de diagnóstico:

El mecanismo de token-lock de Hermes v0.6.0 puede evitar que dos instancias de plataformas usen el mismo Bot Token y entren en conflicto. Sin embargo, si ejecutas en varias máquinas múltiples instancias del mismo Bot, aparecerá este problema.

# Confirma que solo hay una instancia del gateway Hermes en ejecución
ps aux | grep hermes
pkill -f hermes-agent

# Luego reinicia
hermes gateway start

TIP

Con Profiles puedes hacer que cada plataforma ejecute una instancia completamente independiente de Hermes: cada profile tiene su propio directorio de configuración, memoria y sesiones. Los profiles están aislados entre sí por completo; es ideal para que distintos miembros del equipo usen sus propios Bots.

Lectura adicional / direcciones avanzadas

Migrar desde OpenClaw

Si ya usas OpenClaw, Hermes ofrece una herramienta de migración oficial que puede importar automáticamente SOUL.md, MEMORY.md, Skills, API Keys y la configuración de las plataformas de mensajería:

hermes claw migrate              # migración completa interactiva
hermes claw migrate --dry-run    # primero, previsualiza
hermes claw migrate --preset user-data  # no migra información sensible

Modo MCP Server

Hermes v0.6.0 incorpora la capacidad MCP Server. Puedes exponer las herramientas de Hermes hacia el exterior con un solo comando:

hermes mcp serve
# Soporta dos protocolos de transporte: stdio y Streamable HTTP

Después de conectarte, IDEs como Cursor, VS Code o Zed podrán llamar a todas las herramientas de Hermes y sus capacidades de conversación mediante el protocolo MCP.

Sistema de skills personalizado

El sistema de Skills de Hermes permite crear skills automáticamente a partir de descripciones en lenguaje natural. También puedes escribirlas manualmente:

# Ver skills existentes
hermes skills

# Explorar Skills Hub (mercado de skills de la comunidad)
/skills

# Instalar skills comunitarias desde agentskills.io

Tareas programadas (Cron)

Usa lenguaje natural para definir tareas programadas: Hermes las ejecuta automáticamente y envía los resultados a cualquier plataforma.

# Todos los días a las 8 a.m., envía un informe del tiempo a Telegram
/cron "Every day at 8am, summarize today's weather and send to me" --platform telegram

Conclusión

El diseño del gateway de Hermes Agent para todas las plataformas es muy elegante. Solo necesitas mantener una configuración para que la misma instancia del Agent funcione en cualquier plataforma de mensajería. La memoria se comparte entre plataformas, lo configuras una vez y listo; además, el uso de recursos es mucho menor que ejecutar varios Bots independientes.

Si todavía usas OpenClaw, o estás buscando un AI Agent open source que realmente dé la talla, vale la pena que Hermes pruebe en 20 minutos. Combinado con el Claude Opus 4.6 con descuento de Defapi, el coste mensual puede reducirse al 50% de antes, mientras que la experiencia no se ve afectada en absoluto.