Cómo configurar la moderación de salas Matrix con el bot Mjolnir

Mjolnir es un bot de moderación de Matrix que puede aplicar políticas de baneo compartidas, censurar mensajes, supervisar salas protegidas y ayudar a los moderadores a actuar sin usar cuentas personales. Una configuración segura depende de tres decisiones: dónde se ejecuta el bot, quién puede darle órdenes y qué permisos recibe en cada sala protegida. Mantén la sala de control privada, protege solo las salas que desees y verifica los permisos antes de confiar en el bot durante un incidente.

Esta guía sigue la documentación oficial de configuración y moderación de Mjolnir y las directrices de moderación de la comunidad Matrix, revisadas el 6 de octubre de 2026. La página de lanzamientos del proyecto indica la versión 1.12.1 como la más reciente al momento de esta revisión. Al instalar, revise nuevamente la página de lanzamientos oficial y el ejemplo de configuración, ya que las etiquetas de contenedor y las opciones compatibles pueden cambiar.

¿Es Mjolnir adecuado para tu comunidad de Matrix?

Usa Mjolnir cuando los moderadores necesiten compartir reglas de moderación entre varias salas, suscribirse a listas de políticas comunes o aplicar acciones repetidas de forma consistente. Los permisos de sala de Matrix siguen determinando lo que el bot puede hacer; Mjolnir no obtiene autoridad solo por unirse a una sala. Para la moderación habitual de salas pequeñas, las herramientas integradas de la sala pueden ser suficientes. Mjolnir es más útil cuando la misma comunidad gestiona varias salas o necesita un flujo de trabajo compartido y controlado.

La moderación de salas y la administración del servidor principal son funciones independientes. Mjolnir puede gestionar las prohibiciones y censuras a nivel de sala con los permisos adecuados. Los comandos más drásticos que afectan a todo el servidor, como la desactivación de usuarios, el cambio de alias o el cierre de salas, requieren que Mjolnir sea administrador del servidor Synapse. No otorgue acceso de administrador al servidor principal a menos que los moderadores tengan una necesidad específica para realizar dichas operaciones.

¿Qué debes preparar antes de instalarlo?

• Una cuenta de servidor principal de Matrix dedicada al bot, como por ejemplo @mjolnir:example.org.
• Una sala de administración privada donde los moderadores autorizados pueden emitir comandos y recibir mensajes de estado.
• Un directorio o volumen persistente para la configuración y el estado de Mjolnir.
• Plan para salas cifradas. La configuración actual de Mjolnir admite cifrado nativo; además, Pantalaimon aparece como una opción independiente y obsoleta. No habilite ambas opciones simultáneamente.
• Una sala de pruebas donde puedes confirmar las invitaciones, los permisos y el comportamiento de las listas antes de proteger las salas de producción con mucho tráfico.

¿Cómo se instala Mjolnir?

El proyecto upstream documenta la instalación de Docker y la autocompilación. Para la mayoría de los administradores que ya utilizan contenedores, Docker Compose resulta conveniente porque puede reiniciar el bot y mostrar los registros sin necesidad de mantener una terminal interactiva abierta. Siga las instrucciones de configuración de Docker del proyecto y fije una versión revisada en producción en lugar de depender indefinidamente de una latestetiqueta flotante. La imagen oficial es matrixdotorg/mjolnir.

Prepare la configuración antes de iniciar el contenedor. La guía oficial de Docker espera que la configuración se encuentre en un directorio de datos persistente en config/production.yaml. Mantenga ese directorio legible únicamente para los administradores y el servicio que lo necesiten. El archivo puede contener un token de acceso u otras credenciales de inicio de sesión; no lo suba a un repositorio público, no lo pegue en una sala de soporte ni lo incluya en los registros.

Utilice la configuración predeterminada actual del proyecto con comentarios como fuente de información para los nombres de las opciones. Como mínimo, configure la URL del servidor principal y la sala de administración, y luego configure la autenticación y el cifrado para la implementación elegida. Si utiliza una configuración basada en tokens, trate el token como una contraseña. La guía de configuración original describe cómo obtenerlo iniciando sesión como el bot desde un perfil de navegador independiente en Element y abriendo Configuración, Ayuda y Acerca de, y la sección Token de acceso. Se advierte que no se debe cerrar la sesión después, ya que esto puede invalidar el token; en su lugar, cierre ese perfil de navegador. Para una sala de administración cifrada, habilite y pruebe la compatibilidad con el cifrado de Mjolnir antes de depender de los comandos allí.

# Illustrative values only; use the exact keys and authentication method
# from the current upstream configuration sample. Never share real secrets.
homeserverUrl: https://matrix.example.org
managementRoom: '!privateRoomId:example.org'
accessToken: '[STORE A SECRET HERE, NOT IN PUBLIC]'

Ese pequeño fragmento no constituye una configuración completa. En particular, la configuración de cifrado e inicio de sesión depende de si se utiliza el cifrado nativo o la opción Pantalaimon. Consulte el ejemplo actual en lugar de copiar un archivo antiguo de blog o de configuración. La guía de configuración de Mjolnir también recomienda mantener el bot cerca del servidor principal en la red para reducir la latencia de respuesta.

¿Cómo se debe asegurar la sala de administración?

Crea una sala para moderadores de confianza, invita a la cuenta del bot y haz que la sala sea privada para el equipo de moderación. El ID o alias de la sala se incluye en managementRoom. La configuración actual describe esta sala como la fuente de comandos y advierte que cualquiera que pueda enviar comandos allí puede controlar Mjolnir; no proporciona una capa de control de acceso más granular por comando. Por lo tanto, la revisión de la membresía es esencial. Elimina a los antiguos moderadores de inmediato y no uses la sala de control del bot como un chat general de la comunidad.

Se recomienda cifrar la sala de administración. Si la cifra, verifique que Mjolnir pueda leer y responder a los mensajes con el método de cifrado configurado. Un bot que se haya unido a una sala cifrada pero no pueda descifrar sus eventos podría aparecer en línea ignorando los comandos. Para diagnosticar este problema, utilice la configuración de cifrado y los registros del servidor principal en lugar de desactivar el cifrado de la sala como primera medida.

¿Qué permisos debería recibir Mjolnir?

Invita al bot a cada sala que deba proteger y asígnale el nivel de poder suficiente para realizar las acciones de moderación esperadas. Matrix utiliza los niveles de poder de las salas para operaciones como banear, expulsar, censurar eventos de otros usuarios y cambiar el estado de la sala. El valor requerido viene definido por el evento de nivel de poder de la sala; los valores predeterminados de Matrix para banear, expulsar y censurar suelen ser 50 cuando no se especifica, pero cada sala puede modificarlos.

La guía de la comunidad de Matrix describe el nivel de poder 100 como una configuración común de Mjolnir para que pueda aplicar decisiones de moderación. Sin embargo, ese nivel es considerable: cualquiera que pueda controlar la cuenta de Mjolnir tiene efectivamente esa autoridad en las salas protegidas, y el bot puede convertirse en su propietario de facto. Revisa los niveles de poder de cada sala y elige uno que permita al bot realizar las acciones necesarias, limitando al mismo tiempo la autoridad innecesaria. No le otorgues el estado de administrador del servidor principal para la moderación habitual de la sala.

En Element, puedes invitar al bot desde el panel de miembros de la sala o introducir un comando de invitación como /invite @mjolnir:example.org. Una vez que se una, ajusta su rol en la lista de miembros de la sala. Repite el proceso para cada sala que quieras proteger. Mjolnir no puede proteger salas a las que no se haya unido, debido al modelo de permisos descentralizado de Matrix, que gestiona cada sala individualmente.

¿Cómo se crea una lista de salas prohibidas y se añaden salas protegidas?

Una vez que el bot se haya iniciado y haya publicado su estado en la sala de administración, cree allí una lista de políticas. El inicio rápido de Mjolnir utiliza este ejemplo:

!mjolnir list create COC code-of-conduct-ban-list
!mjolnir default COC
!mjolnir rooms add #community:example.org
!mjolnir verify
!mjolnir status

El primer comando crea una sala de lista de baneos con el shortcode COC; la persona que la crea es invitada para que pueda gestionar su visibilidad. El segundo selecciona esa lista como predeterminada para los comandos de moderación posteriores. El tercero añade una sala al conjunto de salas protegidas de Mjolnir. El comando de verificación comprueba si el bot tiene los permisos necesarios en todas las salas protegidas, mientras que status ayuda a confirmar que se está ejecutando como se espera. Use !mjolnir helppara ver la sintaxis de comandos disponible en su versión instalada.

Mantén privada una lista de políticas si contiene notas internas o está destinada únicamente a tu equipo. Hazla pública solo cuando quieras que otras comunidades descubran y se suscriban a las reglas. Las reglas de Mjolnir se acumulan entre listas, así que revisa las listas que sigues antes de confiar en ellas; una lista puede seguir coincidiendo con un usuario o servidor incluso si eliminas una regla duplicada de otra lista.

¿Qué deberías probar antes de usarlo en un incidente real?

• Confirma que el bot publique mensajes de inicio y estado en la sala de administración configurada.
• Ejecuta la prueba !mjolnir verifydespués de invitarlo a la sala de pruebas y otorgarle el rol elegido.
• Ejecuta el programa !mjolnir roomsy confirma que aparece la habitación deseada, sin que aparezca ninguna habitación que no tenga relación con la anterior.
• Revisa !mjolnir protectionsy activa únicamente las protecciones que comprendas; las protecciones automáticas pueden afectar a usuarios legítimos.
• Utilice una cuenta de prueba y una sala desechable para validar el procedimiento de bloqueo, desbloqueo y edición del equipo antes de aplicarlo a los miembros reales.
• Compruebe los registros del contenedor y los mensajes de la sala de administración de Mjolnir si el bot omite comandos o informa de permisos faltantes.

No pruebes a bloquear a un miembro real de la comunidad ni a usar un comodín en un servidor activo. Los bloqueos con comodines pueden afectar a muchos usuarios; la configuración predeterminada actual requiere una confirmación adicional para este tipo de bloqueos. Consulta la guía del moderador antes de activar las protecciones automáticas y documenta quién puede aprobar una acción de alto impacto.

¿Cuáles son los errores de configuración más comunes?

• Otorgar permisos de administrador al servidor del bot por comodidad: la moderación a nivel de sala generalmente requiere permisos de sala, no derechos de administrador de Synapse.
• Dejar la sala de administración ampliamente accesible: se confía en que todos los miembros con capacidad para emitir comandos tengan acceso a los controles de moderación del bot.
• Olvidar los permisos de la sala protegida: un bot puede estar en línea y aun así no lograr bloquear o censurar si su nivel de poder es demasiado bajo.
• Utilizar salas cifradas sin configurar el cifrado: la mera pertenencia a una comunidad no permite que el bot lea los comandos cifrados.
• Copiar una receta de configuración antigua: la configuración y la compatibilidad con el cifrado de Mjolnir evolucionan; utilice el ejemplo predeterminado actual y la documentación de configuración.
• Suponiendo que la eliminación de una lista revierta todas las prohibiciones: otra lista vigilada aún podría aplicar la misma regla.

¿Dónde puede verificar los datos actuales?

Comience con la guía de configuración de Mjolnir , la guía para moderadores y el historial de versiones . Para los permisos de sala, consulte la guía de moderación de la comunidad de Matrix y la especificación de Matrix para los niveles de poder de las salas . Los comandos de instalación y la configuración de cifrado exactos dependen de su servidor doméstico, la configuración del contenedor y la versión de Mjolnir; estas referencias deben tener prioridad si sus instrucciones cambian.