Mattermost Hermes Agent — Chat autoalojado

Mattermost Hermes Agent — Chat autoalojado

Si tu equipo usa Mattermost, ya conoces su atractivo: se ve y se siente como Slack, pero el servidor —y los datos— se quedan en tu propia infraestructura. Hermes Agent se integra como un bot, conectándose a través de la API REST (v4) de Mattermost más un WebSocket para eventos en tiempo real, para que tu asistente pueda responder en mensajes directos y canales de equipo sin que nada salga de tu red.

No hay ninguna biblioteca adicional que instalar: el adaptador usa aiohttp, que ya viene con Hermes. Funciona tanto con Mattermost Team Edition (gratuita) como con Enterprise Edition.

Cómo se comporta Hermes en Mattermost

Dónde hablas con él	Qué ocurre
Mensajes directos	Hermes responde a cada mensaje — no hace falta @mention. Cada mensaje directo tiene su propia sesión.
Canales	Hermes responde cuando lo @mentionas. Sin mención, ignora el mensaje.
Hilos	Con MATTERMOST_REPLY_MODE=thread, las respuestas se anidan bajo tu mensaje y quedan aisladas del canal principal.
Canales compartidos	El historial de sesión está aislado por usuario de forma predeterminada, así que dos personas en un mismo canal no comparten transcripción.

Ese último comportamiento se controla con group_sessions_per_user en config.yaml:

group_sessions_per_user: true   # each person keeps their own context

Ponlo en false solo si quieres deliberadamente una conversación compartida para todo el canal. Una sesión compartida significa que todos comparten el crecimiento del contexto y los costos de tokens, y la tarea larga y cargada de herramientas de una persona puede inflar o interrumpir la ejecución de otra.

---

Paso 1: Habilitar cuentas de bot (lado del administrador)

Las cuentas de bot deben estar activadas en el servidor antes de que puedas crear una:

1. Inicia sesión en Mattermost como System Admin.
2. Ve a System Console → Integrations → Bot Accounts.
3. Pon Enable Bot Account Creation en true y haz clic en Save.

¿No tienes acceso de administrador? Pídele a tu administrador de Mattermost que habilite las cuentas de bot y cree una para ti.

Paso 2: Crear la cuenta de bot

1. Haz clic en el menú ☰ (arriba a la izquierda) → Integrations → Bot Accounts → Add Bot Account.
2. Rellena los detalles: Username como hermes, Display Name como Hermes Agent, y un Role — Member es suficiente.
3. Haz clic en Create Bot Account y luego copia el token inmediatamente — solo se muestra una vez. Si lo pierdes, tendrás que regenerarlo desde la configuración de la cuenta de bot.

⚠️ Nunca compartas el token ni lo subas a Git. Cualquiera que lo tenga tiene control total del bot.

¿Prefieres que el agente publique como tu propio usuario en lugar de un bot separado? Crea un personal access token en Profile → Security → Personal Access Tokens → Create Token.

Paso 3: Invitar al bot a los canales

El bot solo responde en los canales a los que pertenece:

1. Abre el canal → haz clic en el nombre del canal → Add Members.
2. Busca el nombre de usuario del bot (por ejemplo hermes) y añádelo.

Para mensajes directos, simplemente abre un mensaje directo con el bot — no hace falta invitación.

Paso 4: Encontrar tu User ID de Mattermost

Hermes usa tu User ID — no tu nombre de usuario — para decidir quién puede hablar con el bot:

1. Haz clic en tu avatar (esquina superior izquierda) → Profile.
2. El diálogo muestra tu User ID: una cadena alfanumérica de 26 caracteres como 3uo8dkh1p7g1mfk49ear5fzs5c. Haz clic en ella para copiarla.

También puedes leerlo desde la API:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-mattermost-server/api/v4/users/me | jq .id

Tu User ID no es el @username que ves en los mensajes. Pegar el nombre de usuario es la razón más común de que un bot se quede en silencio.

Paso 5: Configurar Hermes

Ejecuta la configuración guiada y elige Mattermost cuando se te pida — te pregunta por la URL del servidor, el token del bot y tu User ID:

hermes gateway setup

O configúralo a mano en ~/.hermes/.env:

# Required
MATTERMOST_URL=https://mm.example.com
MATTERMOST_TOKEN=your-bot-token
MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c

# Multiple allowed users (comma-separated)
# MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c,8fk2jd9s0a7bncm1xqw4tp6r3e

# Optional: reply in a thread instead of flat messages (default: off)
# MATTERMOST_REPLY_MODE=thread

# Optional: respond without an @mention (default: true = mention required)
# MATTERMOST_REQUIRE_MENTION=false

# Optional: channels where no @mention is needed (comma-separated channel IDs)
# MATTERMOST_FREE_RESPONSE_CHANNELS=channel_id_1,channel_id_2

Luego inicia el gateway:

hermes gateway

El bot se conecta a tu servidor de Mattermost en unos segundos. Envíale un mensaje directo, o @mentionalo en un canal donde se haya añadido, para probar.

Paso 6: Interruptores de comportamiento opcionales

Ajuste	Qué hace
MATTERMOST_REPLY_MODE	off (predeterminado) publica mensajes planos; thread anida las respuestas bajo tu mensaje y mantiene ordenados los canales concurridos.
MATTERMOST_REQUIRE_MENTION	true de forma predeterminada. Ponlo en false para responder a todos los mensajes del canal (los mensajes directos siempre funcionan).
MATTERMOST_FREE_RESPONSE_CHANNELS	IDs de canal que se saltan el requisito de mención incluso cuando las menciones son obligatorias.
MATTERMOST_HOME_CHANNEL	Dónde van los mensajes proactivos — salida de cron, recordatorios, notificaciones. O escribe /sethome en un canal.
mattermost.allowed_channels	Restringe el bot a una lista de IDs de canal; los mensajes de cualquier otro sitio se descartan. Los mensajes directos están exentos.
mattermost.channel_prompts	Inyecta un system prompt efímero por canal — se aplica en cada turno, nunca se guarda en el historial de la transcripción.

Cuando se @mentiona al bot, la mención se elimina del mensaje antes de procesarlo, así que @hermes summarize this thread llega como una instrucción limpia.

Solución de problemas

Síntoma	Causa probable	Solución
El bot te ignora en los canales	No está en el canal, o tu User ID no está en MATTERMOST_ALLOWED_USERS	Añade el bot al canal, verifica el User ID de 26 caracteres, reinicia el gateway
El bot no puede publicar	Token inválido, o el bot carece de permiso en ese canal	Revisa MATTERMOST_TOKEN, confirma que la cuenta está activa y es miembro del canal
Desconexiones constantes	Caídas del WebSocket, reinicios del servidor, o problemas de proxy/firewall	El adaptador se reconecta con retroceso exponencial (2s → 60s); para nginx, asegúrate de que las cabeceras de upgrade de WebSocket estén configuradas
No pasa absolutamente nada	El gateway no está en ejecución, o la URL/token son incorrectos	Revisa la salida de hermes gateway, y que MATTERMOST_URL incluya https:// sin barra final

Prueba un token directamente con:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-server/api/v4/users/me

Asegurar el bot

Configura siempre MATTERMOST_ALLOWED_USERS. Sin él, el gateway deniega a todos los usuarios de forma predeterminada como medida de seguridad — y los usuarios autorizados obtienen acceso completo a las capacidades del agente, incluido el uso de herramientas y el acceso al sistema, así que mantén la lista reducida. Para una visión más amplia de cómo reforzar un despliegue, consulta la guía oficial de seguridad.

---

¿Qué sigue?

Una vez que el gateway está en marcha, Mattermost se comporta como cualquier otro canal de Hermes: comandos slash, subida de archivos, notas de voz, salida de cron entregada a tu canal de inicio — todo en infraestructura que tú controlas. Si prefieres usar la opción alojada, la integración con Slack cubre la ruta de Socket Mode; si ejecutas gateways en varias máquinas, Hermes Relay las conecta.