Cómo configurar Hermes Agent en Slack (Socket Mode)

Por qué tener Hermes Agent dentro de Slack

Si tu equipo ya vive en Slack, ahí es donde debería vivir también tu agente de IA. Las pestañas del navegador y los paneles aislados pierden el contexto que los canales, los hilos y los mensajes directos te dan gratis: quién pregunta, de qué se estaba hablando hace cinco minutos y dónde tiene sentido que aterrice la respuesta.

Hermes Agent ofrece soporte de primera clase para Slack a través de Socket Mode, así que el runtime puede vivir en tu portátil, en un VPS de 5 USD al mes o detrás del firewall corporativo y aun así enviar y recibir mensajes en tiempo real. No hace falta exponer un webhook público, ni montar un proxy inverso, ni abrir un puerto entrante. El agente conecta hacia fuera contra Slack, mantiene un WebSocket abierto y entrega cada mensaje y cada respuesta por ese mismo canal.

Esta guía recorre la configuración completa de principio a fin: crear la app de Slack a partir del manifiesto incluido, generar los dos tokens, conectar el canal home y la lista de permitidos, arrancar el gateway y los fallos típicos que muerden en el primer despliegue.

Lo que necesitas antes de empezar

Un despliegue limpio de Slack necesita cinco piezas:

Un workspace donde tengas permiso para instalar apps. La mayoría de los workspaces exigen que un admin apruebe la instalación por defecto - revisa Settings & administration → Workspace settings → Permissions si no eres admin.
Una instalación de Hermes Agent funcionando. La guía de Hermes Agent en Docker cubre la forma más limpia de levantarlo; si estás en Windows, el setup de WSL2 es el equivalente.
Una API key de un proveedor de modelos. Anthropic, OpenAI, OpenRouter y cualquier endpoint compatible con OpenAI sirven. El runtime la usa para responder de verdad a los mensajes.
Tu Slack user ID numérico para la lista de permitidos (más abajo).
Unos 15 minutos para la primera instalación. Los redespliegues posteriores tardan menos de un minuto.

Paso 1 - Generar el manifiesto de la app de Slack

Las apps de Slack se definen mediante un manifiesto YAML que declara permisos, suscripciones a eventos, slash commands y Socket Mode de una sola vez. Hermes incluye un manifiesto pensado para su handler nativo de Slack, así que no tienes que armar la lista de scopes a mano:

hermes slack manifest --write ./hermes-slack-manifest.yaml

Abre https://api.slack.com/apps, haz clic en Create New App, elige From an app manifest, selecciona tu workspace y pega el contenido de hermes-slack-manifest.yaml. Slack te muestra exactamente lo que se va a crear. Confirma.

El manifiesto activa Socket Mode, declara cada evento al que Hermes se suscribe (app_mention, message.im, message.channels, message.groups, message.mpim), registra los slash commands integrados y pide los scopes de bot que el runtime usa de verdad:

app_mentions:read - escuchar cuando alguien menciona al bot en un canal.
chat:write - enviar respuestas y abrir hilos.
im:history, im:read, im:write - conversaciones por mensaje directo.
channels:history, groups:history, mpim:history - leer contexto en canales públicos, canales privados y grupos a los que se invite al bot.
users:read - resolver IDs de usuario en nombres legibles para la UI de la lista de permitidos y los logs de auditoría.
commands - registrar la superficie del slash command /hermes.

Editar el manifiesto después de la instalación está bien. Añadir scopes después de la instalación es la operación que más fallos silenciosos provoca - mira la sección de troubleshooting más abajo.

Paso 2 - Generar el bot token y el app-level token

Slack emite dos tokens distintos para una app en Socket Mode, y Hermes necesita ambos:

Bot token (xoxb-…)

En la configuración de la app, ve a OAuth & Permissions → Install to Workspace. Aprueba los scopes del manifiesto. Slack emite un token xoxb-…. Cópialo.

App-level token (xapp-…)

Ve a Basic Information → App-Level Tokens → Generate Token and Scopes. Dale un nombre (por ejemplo, hermes-socket), añade el scope connections:write y pulsa Generate. Slack emite un token xapp-…. Cópialo.

Los dos tokens hacen cosas distintas. El bot token autentica las llamadas a la API de Slack (enviar un mensaje, leer el historial de un canal). El app token autentica el propio WebSocket de Socket Mode - sin él, el runtime arranca pero nunca se conecta a Slack y el bot se queda mudo para siempre.

Paso 3 - Encuentra tu Slack user ID numérico

Hermes Agent solo responderá a los IDs de usuario que aparezcan en SLACK_ALLOWED_USERS. Es el control de seguridad más importante de toda la configuración, y espera IDs numéricos, no @handles ni nombres visibles.

En Slack, haz clic en tu avatar → Profile → menú con tres puntos (⋮) → Copy member ID. El ID se ve así: U01ABCD2EFG. Repite el proceso por cada compañero de equipo al que quieras autorizar.

Saltarse la lista de permitidos equivale a publicar tu API key del proveedor de modelos a cualquiera del workspace. Si una instancia de Hermes está accesible desde un workspace de Slack abierto y la lista está vacía, cada mensaje en cada canal donde hayas invitado al bot quemará tus tokens.

Paso 4 - Configura el runtime de Hermes

Abre ~/.hermes/.env (o el .env que lea tu contenedor) y añade:

SLACK_BOT_TOKEN=xoxb-...tu-bot-token...
SLACK_APP_TOKEN=xapp-...tu-app-token...
SLACK_ALLOWED_USERS=U01ABCD2EFG,U02HIJK3LMN
SLACK_HOME_CHANNEL=C04XYZ123AB

Una nota sobre cada variable:

SLACK_BOT_TOKEN - el token xoxb-… del Paso 2.
SLACK_APP_TOKEN - el token xapp-…. Olvidarlo es el fallo más habitual y no produce ningún mensaje de error - el gateway simplemente nunca abre el WebSocket.
SLACK_ALLOWED_USERS - lista separada por comas de IDs numéricos. El bot ignora a todos los demás, incluidos admins y bots.
SLACK_HOME_CHANNEL (opcional) - el ID del canal para mensajes proactivos, resúmenes programados y notificaciones disparadas por skills. Haz clic derecho en el canal en Slack → View channel details → copia el ID que aparece abajo. Si lo dejas vacío, los mensajes proactivos van al DM del bot con el primer usuario permitido.

chmod 600 ~/.hermes/.env después de guardar. Ambos tokens dan acceso de escritura a tu workspace; trátalos como claves SSH.

Una terminal mostrando el archivo .env de Hermes con SLACK_BOT_TOKEN, SLACK_APP_TOKEN, SLACK_ALLOWED_USERS y SLACK_HOME_CHANNEL rellenos, y los permisos del archivo en 600

Paso 5 - Arranca el gateway

Reinicia el gateway para que recoja el nuevo entorno:

hermes gateway restart

O, con Docker Compose:

docker compose restart gateway

Sigue los logs y vigila el handshake con Slack:

hermes gateway logs --follow

Estás buscando dos líneas, en este orden:

slack: connecting to Socket Mode
slack: connected as @tu-bot-name (workspace: tu-workspace)

Si ves solo la primera y nada más, el token xapp-… está mal, falta o no tiene el scope connections:write. Si no ves ninguna, el gateway no está leyendo el nuevo .env - confirma la ruta del archivo que el runtime usa.

Paso 6 - Invita al bot y manda el primer mensaje

En cualquier canal donde quieras que participe el bot:

/invite @tu-bot-name

El bot solo ve mensajes en los canales en los que lo hayan invitado. Es una restricción del lado de Slack, no de Hermes - aunque tenga channels:history concedido, lee cero historial hasta que lo invitas con /invite.

Mándale un DM al bot, o menciónalo (@) en el canal. Hermes responde en la misma conversación, con toda su memoria persistente y sus skills intactas. A partir de aquí, todas las capacidades de Hermes - memoria persistente, tareas programadas, skills personalizadas - funcionan exactamente igual que en la superficie de Telegram.

Un canal de Slack mostrando un hilo entre un usuario y el bot Hermes, con el bot respondiendo en contexto y un pequeño indicador verde junto al nombre del bot

Los fallos que muerden primero

Cinco errores explican casi cada hilo de soporte del estilo "la integración con Slack está rota":

Olvidar el token xapp-…. Socket Mode no se conecta sin él, y el panel de Slack no te avisa. La solución es una línea en el .env y reiniciar.

Añadir scopes después de instalar sin reinstalar. Los nuevos scopes aparecen en la página de OAuth pero no se conceden de verdad al bot hasta que pulsas Reinstall to Workspace. El bot se queda con el set de scopes anterior en silencio. Si los logs del runtime muestran errores missing_scope, esta es la causa.

El bot no está invitado al canal. Un bot con channels:history sigue leyendo cero historial hasta que se le invita. Responderá a los DMs al instante pero permanecerá callado en los canales hasta que ejecutes /invite @tu-bot-name.

SLACK_ALLOWED_USERS vacío. El comportamiento por defecto es ignorar a todo el mundo. Es un default seguro intencionado, pero hace que el bot parezca roto a quien lo prueba por primera vez sin acordarse de añadir su propio ID.

Dos procesos del gateway contra el mismo volumen de datos. Si arrancas un gateway en modo Slack y otro en modo Telegram contra el mismo directorio /data, el orden de los mensajes y las escrituras de memoria se corrompen entre sí en cuestión de minutos. Si quieres ambas superficies, ejecuta un único gateway con los bloques SLACK_* y TELEGRAM_* en el .env - el runtime multiplexa ambas de forma nativa.

Si el problema parece de Slack pero los síntomas son más generales, la guía de troubleshooting de Telegram cubre los problemas de gateway y de proveedor con más profundidad - la mayoría son agnósticos de la superficie.

Slack y Telegram, lado a lado

Aspecto	Slack	Telegram
Tiempo de setup	15 min (manifiesto + 2 tokens)	5 min (un token de BotFather)
Accesibilidad	Detrás del firewall (WebSocket de Socket Mode)	Detrás del firewall (long-poll)
Campo de allowlist	`SLACK_ALLOWED_USERS` (IDs numéricos)	`TELEGRAM_ALLOWED_USERS` (IDs numéricos)
Mejor para	Flujos de equipo, contexto de canal, hilos	Uso personal, mobile-first, modo voz
Hilos	Nativos	Solo respuestas con cita
Archivos	Subidas y previews integradas	Subidas y previews integradas

Las dos superficies no son excluyentes. El mismo runtime de Hermes puede entregar mensajes a las dos a la vez - útil cuando el mismo agente sirve un chat personal de Telegram y un canal de Slack del equipo desde la misma memoria.

Sáltate la fontanería de Slack

Los pasos de Slack en sí son sencillos, pero sigues siendo dueño del host: backups, TLS para el dashboard, rotación de logs y la cadencia de actualizaciones. Para una instalación personal está bien. Para un equipo que quiere el bot vivo en minutos y cero carga operacional después, Hermify provisiona un runtime gestionado de Hermes, encripta tus tokens de Slack en reposo, expone la lista de permitidos en una UI en lugar de un .env y mantiene la conexión de Socket Mode sana en un servidor persistente.

Tú aportas el workspace de Slack y una API key de proveedor; la plataforma se encarga de todo lo de abajo. Si estás evaluando ese trade-off, la comparativa entre self-hosting y gestionado repasa los números de coste y mantenimiento.