Cómo configurar Hermes Slack en ZimaOS y solucionar errores de la puerta de enlace

Hermes Agent puede conectarse a Slack sin exponer un punto de conexión de webhook público porque su integración actual con Slack utiliza Socket Mode. El informe de la comunidad en el que se basa esta página completó correctamente la mayor parte de esa configuración: el usuario creó una aplicación de Slack, obtuvo un xoxb- un token de bot y un xapp- un token de nivel de aplicación, ejecutó hermes gateway setup dentro del contenedor de Hermes en ZimaOS y añadió el bot a un canal de Slack.

El fallo ocurrió cuando Hermes intentó reiniciar su puerta de enlace. La CLI devolvió PermissionError: [Errno 13] Permission denied: '/opt/data/gateway.lock', y aunque la aplicación aparecía en Slack, @Hermes La mención no produjo ninguna respuesta. La documentación actual de ZimaSpace identifica explícitamente /opt/data los errores de permisos como un problema de propiedad de Hermes que puede producirse después de que las operaciones de la puerta de enlace se hayan ejecutado anteriormente como root. La documentación actual de Hermes para Slack también añade varios requisitos de configuración que es más seguro verificar que intentar adivinar los permisos.

Qué ocurrió en el informe sobre Hermes y Slack en ZimaOS

La publicación de la comunidad de mayo de 2026 utilizó una instalación limpia de Hermes en ZimaOS y un espacio de trabajo nuevo de Slack. El usuario creó una aplicación de Slack con Socket Mode activado, copió los dos tipos de token necesarios y configuró Slack mediante el asistente de la puerta de enlace de Hermes.

La secuencia clave fue:

1. Crea una aplicación de Slack y activa Socket Mode.
2. Obtén un token OAuth de usuario de bot que comience por xoxb-.
3. Obtén un token de nivel de aplicación que comience por xapp-.
4. Ejecuta hermes gateway setup dentro del contenedor de Hermes.
5. Selecciona Slack e introduce los dos tokens.
6. Acepta la solicitud para reiniciar la puerta de enlace.

El reinicio falló con:

PermissionError: [Errno 13] Permission denied: '/opt/data/gateway.lock'

A continuación, el usuario reinició la puerta de enlace desde la interfaz web de Hermes, invitó @Hermes en un canal de Slack y comprobó que Slack confirmara que la aplicación se había añadido. Sin embargo, una mención en un canal seguía sin recibir respuesta. Esto significa que podía haber dos capas que solucionar: el proceso de puerta de enlace del lado de ZimaOS y la configuración de eventos del lado de Slack.

Usa el manifiesto actual de Slack de Hermes en lugar de reconstruir manualmente todos los permisos

La documentación actual de Hermes recomienda generar un manifiesto para la aplicación de Slack. Esto es más seguro que recrear manualmente de memoria todos los permisos de OAuth, comandos de barra, suscripciones a eventos y configuraciones de Socket Mode.

Dentro de un entorno Hermes actual, genera el manifiesto con:

hermes slack manifest --agent-view --write

El archivo generado se escribe en:

~/.hermes/slack-manifest.json

Después, crea una nueva aplicación de Slack a partir de ese manifiesto en la interfaz de administración de aplicaciones de Slack. La documentación actual de Hermes explica que el manifiesto declara conjuntamente los comandos integrados, los ámbitos necesarios, las suscripciones a eventos y la configuración del modo Socket.

Para consultar el procedimiento actual del proyecto original, visita la guía de configuración de Slack de Hermes Agent.

Los dos tokens de Slack que necesita Hermes

Hermes utiliza dos credenciales de Slack diferentes, y no son intercambiables:

• Token del bot: comienza por xoxb- y se convierte en SLACK_BOT_TOKEN.
• Token a nivel de aplicación: comienza por xapp-, debe admitir el modo Socket y se convierte en SLACK_APP_TOKEN.

Un archivo de entorno actual de Hermes puede contener:

SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_APP_TOKEN=xapp-your-app-token
SLACK_ALLOWED_USERS=U01ABC2DEF3

SLACK_ALLOWED_USERS usa los ID de miembro de Slack, no los nombres visibles. Si los tokens son correctos, pero el usuario solicitante no tiene autorización, Hermes puede seguir apareciendo como conectado, aunque se niegue a procesar los mensajes de ese usuario.

Nunca publiques xoxb- o xapp- valores en una publicación de la comunidad, una captura de pantalla, un repositorio de Git o un registro de soporte. Revoca y vuelve a generar un token si ha quedado expuesto.

Las menciones en canales requieren los eventos de Slack correctos

Que un bot sea visible en un canal no demuestra que Slack esté entregando eventos de mensajes a Hermes. La documentación actual de Hermes señala las suscripciones a eventos como una causa frecuente de fallos.

En una aplicación de Slack configurada manualmente, verifica los eventos necesarios para la versión actual de Hermes. La documentación actual incluye eventos como:

• app_mention para mensajes directos @Hermes menciones.
• message.channels para los mensajes en canales públicos donde el bot sea miembro.
• message.groups cuando se necesite compatibilidad con canales privados.
• message.im para los mensajes directos.

Si cambias los ámbitos o las suscripciones a eventos después de instalar la aplicación de Slack, vuelve a instalarla en el espacio de trabajo cuando Slack te lo solicite. De lo contrario, la configuración mostrada y los permisos concedidos realmente al bot instalado pueden diferir.

Invita a Hermes al canal antes de realizar la prueba

Hermes no se une automáticamente a todos los canales de Slack. Invítalo explícitamente:

/invite @Hermes

Después, prueba una mención sencilla de un usuario de Slack cuyo ID de miembro esté incluido en la lista de permitidos de Hermes. Si los mensajes directos funcionan, pero las menciones en canales públicos no, céntrate en app_mention, message.channels, la membresía del canal y los permisos de la aplicación instalada antes de cambiar la configuración de red de ZimaOS.

Por qué /opt/data/gateway.lock puede devolver «Permiso denegado»

La guía del agente Hermes de ZimaSpace actual documenta ahora un problema de permisos en /opt/data. Indica que normalmente se debe a haber ejecutado anteriormente Hermes Gateway como root, dejando archivos propiedad de root dentro de $HERMES_HOME.

El flujo de trabajo documentado por ZimaSpace para el contenedor consiste en entrar en él como el hermes usuario:

docker exec -it -u hermes hermes bash

Después, activa el entorno virtual de Hermes:

source /opt/hermes/.venv/bin/activate

La configuración de mensajería se puede abrir con:

hermes gateway setup

Si la puerta de enlace falla inmediatamente al ejecutar /opt/data/gateway.lock; no ejecutes repetidamente toda la puerta de enlace como root. Primero confirma la identidad y la propiedad implicadas:

id
ls -ld /opt/data
ls -l /opt/data/gateway.lock 2>/dev/null

La guía actual de ZimaSpace recomienda comprobar los registros de Hermes en el panel de ZimaOS y usar temporalmente un shell de root solo cuando sea necesario reparar la propiedad de los archivos. No apliques un cambio de propiedad recursivo a ciegas a /opt/data a menos que hayas verificado qué archivos pertenecen a Hermes y qué usuario o grupo espera el paquete de ZimaOS instalado.

Reinicia la puerta de enlace solo después de que Hermes pueda escribir sus archivos de ejecución

En el informe de la comunidad, hacer clic en Reiniciar puerta de enlace en la interfaz web no bastó para demostrar que la puerta de enlace funcionaba correctamente. Si el proceso subyacente no puede crear o actualizar su archivo de bloqueo, la acción de la interfaz aún puede dejar la integración de Slack no disponible.

Después de corregir el problema real de propiedad, entra en el contenedor como hermes usuario, activa el entorno y ejecuta o reinicia la puerta de enlace mediante los comandos compatibles con la versión de Hermes instalada. Observa los registros de Hermes de ZimaOS mientras envías un mensaje de prueba en Slack.

Una separación útil para solucionar problemas es:

• La puerta de enlace no se inicia: investiga los permisos de /opt/data y los registros de Hermes.
• La puerta de enlace se ejecuta, pero no hay conexión con Slack: verifica el token xapp- y el modo Socket.
• La conexión con Slack existe, pero las menciones en el canal no generan respuesta: verifica los eventos de la aplicación, la pertenencia al canal, el estado de la reinstalación y SLACK_ALLOWED_USERS.
• Los mensajes directos funcionan, pero el canal no: céntrate en los eventos y permisos del canal, no en el proveedor del modelo.

Usa el panel web de Hermes para consultar el estado, no como única comprobación de funcionamiento

La guía de ZimaSpace expone el panel web de Hermes en:

http://ZIMAOS_LAN_IP:9119

El panel puede mostrar el estado de ejecución, las sesiones y la configuración del modelo. Es útil para reiniciar y observar la puerta de enlace, pero debes combinarlo con los registros cuando se produzca un error de permisos a nivel del proceso.

Lista de comprobación para solucionar problemas de Hermes Slack en ZimaOS

1. Confirma que la configuración del modelo de Hermes funcione correctamente antes de añadir Slack.
2. Entra en el contenedor de ZimaOS como hermes usuario, no como root, para el funcionamiento normal de la puerta de enlace.
3. Usa el manifiesto actual de Hermes para Slack siempre que sea posible, en lugar de adivinar manualmente los ámbitos.
4. Confirma que xoxb- el token del bot pertenezcan a la misma aplicación de Slack prevista. xapp- el token de aplicación y
5. Confirma que Socket Mode esté habilitado.
6. Confirma que tu ID de miembro de Slack esté incluido en SLACK_ALLOWED_USERS.
7. Invita a Hermes al canal que estás probando.
8. Verifica app_mention y que los eventos de mensajes necesarios estén suscritos.
9. Vuelve a instalar la aplicación de Slack después de cambiar los ámbitos o las suscripciones a eventos cuando Slack lo solicite.
10. Si /opt/data/gateway.lock falla, revisa la propiedad de los archivos y los registros de Hermes en ZimaOS antes de volver a reiniciar.
11. Cuando la puerta de enlace esté activa, prueba por separado un mensaje directo y una mención en un canal.

Preguntas frecuentes sobre Hermes Slack en ZimaOS

¿Qué significa el error de permisos de gateway.lock?

Significa que el proceso de Hermes no puede acceder al archivo de bloqueo de ejecución en la ubicación esperada. La documentación actual de ZimaSpace indica que un /opt/data el error de permisos suele estar relacionado con archivos cuya propiedad quedó asignada a root después de ejecutar Hermes Gateway como root.

¿Debo ejecutar Hermes Gateway como root para solucionarlo?

No como solución habitual. ZimaSpace documenta cómo entrar en el contenedor como hermes usuario para las operaciones normales de Hermes. Solo debes usar un shell de root temporalmente cuando hayas confirmado que es necesario reparar la propiedad de los archivos.

¿Por qué el bot de Hermes aparece en Slack, pero no responde?

Que la aplicación esté instalada y que se la haya invitado solo demuestra que Slack reconoce la aplicación. Hermes aún necesita una puerta de enlace activa, una conexión válida mediante Socket Mode, suscripciones correctas a eventos, permisos adecuados en el espacio de trabajo y un ID de miembro de Slack autorizado.

¿Hermes Slack necesita una URL de webhook pública?

No. La integración actual de Hermes con Slack utiliza Socket Mode mediante WebSockets, por lo que la instancia de Hermes puede permanecer detrás de un firewall sin un endpoint público de webhook entrante de Slack.

¿Cuál es la mejor forma actual de configurar la aplicación de Slack?

Usa el manifiesto de Slack generado por Hermes actual cuando la versión instalada de Hermes lo admita. Esto reduce los errores causados por ámbitos, suscripciones a eventos o definiciones de comandos de barra faltantes.