Como configurar a moderação de salas Matrix com o bot Mjolnir

Mjolnir é um bot de moderação para Matrix que pode aplicar políticas de banimento compartilhadas, editar mensagens, monitorar salas protegidas e ajudar moderadores a agir sem usar contas pessoais. Uma configuração segura depende de três decisões: onde o bot é executado, quem pode enviar comandos para ele e quais permissões ele recebe em cada sala protegida. Mantenha a sala de controle privada, proteja apenas as salas desejadas e verifique as permissões antes de confiar no bot durante um incidente.

Este guia segue a documentação de configuração e moderação do Mjolnir e as diretrizes de moderação da comunidade Matrix, verificadas em 6 de outubro de 2026. A página de lançamentos do projeto lista a versão 1.12.1 como a mais recente no momento desta revisão. Consulte novamente a página de lançamentos e o exemplo de configuração do projeto original ao instalar, pois as tags do contêiner e as opções suportadas podem mudar.

O Mjolnir é adequado para a sua comunidade Matrix?

Use o Mjolnir quando os moderadores precisarem compartilhar regras de moderação entre várias salas, assinar listas de políticas comuns ou aplicar ações repetidas de forma consistente. As permissões da sala Matrix ainda determinam o que o bot pode fazer; o Mjolnir não ganha autoridade apenas por entrar em uma sala. Para a moderação comum de salas pequenas, as ferramentas integradas da sala podem ser suficientes. O Mjolnir é mais útil quando a mesma comunidade opera várias salas ou precisa de um fluxo de trabalho controlado e compartilhado.

A moderação de salas e a administração do servidor doméstico são funções distintas. O Mjolnir pode gerenciar banimentos e redações em nível de sala com as permissões apropriadas. Comandos mais drásticos que afetam todo o servidor — como desativar usuários, mover aliases ou encerrar salas — exigem que o Mjolnir seja um administrador do servidor Synapse. Não conceda acesso de administrador do servidor doméstico a menos que os moderadores tenham uma necessidade específica para essas operações.

O que você deve preparar antes de instalá-lo?

• Uma conta de servidor doméstico Matrix dedicada ao bot, como por exemplo @mjolnir:example.org...
• Uma sala de gerenciamento privada onde moderadores autorizados podem emitir comandos e receber mensagens de status.
• Um diretório ou volume persistente para a configuração e o estado do Mjolnir.
• Um plano para salas criptografadas. A configuração atual do Mjolnir suporta criptografia nativa; a configuração também documenta o Pantalaimon como uma opção separada e obsoleta. Não habilite ambos os caminhos simultaneamente.
• Uma sala de testes onde você pode confirmar convites, permissões e comportamentos de listas antes de proteger salas de produção movimentadas.

Como instalar o Mjolnir?

O projeto original documenta a instalação do Docker e a compilação própria. Para a maioria dos administradores que já executam contêineres, o Docker Compose é conveniente porque pode reiniciar o bot e exibir os logs sem precisar manter um terminal interativo aberto. Siga as instruções de configuração do Docker do projeto e fixe uma versão revisada em produção, em vez de depender indefinidamente de uma latesttag flutuante. A imagem oficial é matrixdotorg/mjolnir.

Prepare a configuração antes de iniciar o contêiner. O guia do Docker espera que a configuração esteja em um diretório de dados persistente em `/etc/docker/ config/production.yamlconfig.conf`. Mantenha esse diretório legível apenas pelos administradores e pelo serviço que precisa dele. O arquivo pode conter um token de acesso ou outras credenciais de login; não o envie para um repositório público, não o cole em uma sala de suporte nem o inclua em logs.

Use a configuração padrão atual do projeto com comentários como fonte de referência para os nomes das opções. No mínimo, defina o URL do servidor principal e a sala de gerenciamento e, em seguida, configure a autenticação e a criptografia para a sua implantação escolhida. Se você usar uma configuração baseada em token, trate o token como uma senha. O guia de configuração original descreve como obtê-lo fazendo login como o bot a partir de um perfil de navegador separado no Element e abrindo Configurações, Ajuda e Sobre e a seção Token de acesso. Ele alerta para não fazer logout em seguida, pois isso pode invalidar o token; em vez disso, feche o perfil do navegador. Para uma sala de gerenciamento criptografada, habilite e teste o suporte à criptografia do Mjolnir antes de depender de comandos ali.

# 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]'

Esse pequeno trecho não representa uma configuração completa. Em particular, as configurações de criptografia e login dependem se você usa criptografia nativa ou o caminho opcional do Pantalaimon. Consulte o exemplo atual em vez de copiar um blog antigo ou um arquivo de composição. O guia de configuração do Mjolnir também recomenda manter o bot próximo ao servidor doméstico em termos de rede para reduzir a latência de resposta.

Como você deve proteger a sala da gerência?

Crie uma sala para moderadores confiáveis, convide a conta do bot e torne a sala privada para a equipe de moderação. O ID ou alias da sala deve ser inserido em `<room_id>` managementRoom. A configuração atual descreve esta sala como a fonte de comandos e avisa que qualquer pessoa que possa enviar comandos para lá pode controlar o Mjolnir; ela não fornece uma camada de controle de acesso mais granular por comando. Isso torna a revisão de membros essencial. Remova moderadores antigos imediatamente e não use a sala de controle do bot como um chat geral da comunidade.

Recomenda-se a criptografia para a sala de gerenciamento. Se você criptografá-la, verifique se o Mjolnir consegue ler e responder às mensagens com o método de criptografia configurado. Um bot que entrou em uma sala criptografada, mas não consegue descriptografar seus eventos, pode aparecer online enquanto ignora comandos. Use a configuração de criptografia e os registros do servidor para diagnosticar o problema, em vez de desativar a criptografia da sala como primeira medida.

Quais permissões Mjolnir deve receber?

Convide o bot para cada sala que ele deve proteger e conceda a ele poder suficiente para executar as ações de moderação esperadas. O Matrix usa os níveis de poder da sala para operações como banir, expulsar, editar eventos de outros usuários e alterar o estado da sala. O valor necessário é definido pelo evento de nível de poder da sala; os valores padrão do Matrix para banir, expulsar e editar são geralmente 50 quando não especificados, mas cada sala pode alterá-los.

As diretrizes da comunidade Matrix descrevem o nível de poder 100 como uma configuração comum do Mjolnir para que ele possa impor decisões de moderação. No entanto, esse nível é considerável: qualquer pessoa que possa controlar a conta do Mjolnir efetivamente detém essa autoridade em salas protegidas, e o bot pode se tornar o proprietário de fato delas. Analise os níveis de poder de cada sala e escolha um nível que permita as ações necessárias do bot, limitando, ao mesmo tempo, a autoridade desnecessária. Não conceda a ele status de administrador do servidor principal para moderação de salas comuns.

No Element, você pode convidar o bot pelo painel de membros da sala ou inserir um comando de convite, como ` /invite @mjolnir:example.orgmjolnir`. Depois que ele entrar, ajuste a função dele na lista de membros da sala. Repita o processo para cada sala que deseja proteger. O Mjolnir não pode proteger salas das quais não faz parte, o que decorre do modelo de permissões descentralizado e individual para cada sala do Matrix.

Como criar uma lista de banimentos e adicionar salas protegidas?

Após o bot iniciar e publicar seu status na sala de gerenciamento, crie uma lista de políticas lá. O guia de início rápido do Mjolnir usa este exemplo:

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

O primeiro comando cria uma sala com lista de banimento usando o shortcode COC; a pessoa que a cria é convidada para gerenciar sua visibilidade. O segundo comando seleciona essa lista como padrão para comandos de moderação posteriores. O terceiro comando adiciona uma sala ao conjunto de salas protegidas do Mjolnir. O comando de verificação verifica se o bot possui as permissões necessárias em todas as salas protegidas, enquanto o comando de status ajuda a confirmar se ele está funcionando conforme o esperado. Use `mjolnir --verify` !mjolnir helppara ver a sintaxe dos comandos disponíveis na sua versão instalada.

Mantenha uma lista de políticas privada se ela contiver anotações internas ou for destinada apenas à sua equipe. Torne-a pública somente quando desejar que outras comunidades descubram e se inscrevam nas regras. As regras do Mjolnir são cumulativas entre as listas, portanto, revise as listas monitoradas antes de confiar nelas; uma lista pode continuar a corresponder a um usuário ou servidor mesmo que você remova uma regra duplicada de outra lista.

O que você deve testar antes de usar em um incidente real?

• Confirme se o bot publica mensagens de inicialização e de status na sala de gerenciamento configurada.
• Execute o teste !mjolnir verifyapós convidá-lo para a sala de testes e atribuir-lhe a função escolhida.
• Execute o comando !mjolnir roomse confirme se a sala desejada aparece, sem nenhuma sala não relacionada incluída.
• Analise !mjolnir protectionse ative apenas as proteções que você entende; as proteções automáticas podem afetar usuários legítimos.
• Use uma conta de teste e uma sala descartável para validar o procedimento de banimento, desbanimento e redação da equipe antes de aplicá-lo a membros reais.
• Verifique os registros do contêiner e as mensagens da sala de gerenciamento do Mjolnir caso o bot não receba comandos ou relate falta de permissões.

Não faça testes banindo um membro real da comunidade ou usando um curinga em um servidor ativo. Banimentos com curinga podem afetar muitos usuários; a configuração padrão atual exige uma confirmação adicional para banimentos com curinga. Leia o guia do moderador antes de ativar as proteções automatizadas e documente quem pode aprovar uma ação de alto impacto.

Quais são os erros de configuração mais comuns?

• Conceder privilégios de administrador ao servidor do bot por conveniência: a moderação em nível de sala geralmente requer poder de controle da sala, não direitos de administrador do Synapse.
• Deixar a sala de administração amplamente acessível: todos os membros capazes de emitir comandos têm acesso aos controles de moderação do bot.
• Esquecimento das permissões de salas protegidas: um bot pode estar online e ainda assim não conseguir banir ou ocultar informações se seu nível de privilégios for muito baixo.
• Utilizando salas criptografadas sem configurar a criptografia: a simples adesão não permite que o bot leia comandos criptografados.
• Copiando uma receita de configuração antiga: a configuração e o suporte à criptografia do Mjolnir evoluíram; use o exemplo padrão atual e a documentação de configuração.
• Partindo do pressuposto de que a remoção de uma lista reverte todas as proibições, outra lista monitorada ainda pode impor a mesma regra.

Onde posso verificar as informações atualizadas?

Comece com o guia de configuração do Mjolnir , o guia do moderador e o histórico de versões . Para permissões de sala, consulte o guia de moderação da comunidade Matrix e a especificação do Matrix para níveis de poder da sala . Os comandos exatos de instalação e as configurações de criptografia dependem do seu servidor doméstico, da configuração do contêiner e da versão do Mjolnir; essas referências oficiais devem ter prioridade caso suas instruções mudem.