Come configurare la moderazione della stanza Matrix con il bot Mjolnir

Mjolnir è un bot di moderazione di Matrix in grado di applicare policy di ban condivise, oscurare messaggi, monitorare stanze protette e aiutare i moderatori ad agire senza utilizzare account personali. Una configurazione sicura dipende da tre fattori: dove viene eseguito il bot, chi può impartirgli comandi e quali permessi riceve in ogni stanza protetta. Mantieni privata la sala di controllo, proteggi solo le stanze che intendi proteggere e verifica i permessi prima di affidarti al bot durante un incidente.

Questa guida si basa sulla documentazione di configurazione e moderazione di Mjolnir e sulle linee guida di moderazione della community di Matrix, verificate il 6 ottobre 2026. La pagina delle release del progetto indica la versione 1.12.1 come l'ultima versione rilasciata al momento della revisione. Si consiglia di consultare nuovamente la pagina delle release e l'esempio di configurazione originali durante l'installazione, poiché i tag del container e le opzioni supportate possono subire modifiche.

Mjolnir è adatto alla vostra comunità Matrix?

Utilizzate Mjolnir quando i moderatori devono condividere le regole di moderazione tra diverse stanze, iscriversi a liste di policy comuni o applicare azioni ripetute in modo coerente. Le autorizzazioni della stanza Matrix determinano comunque le azioni del bot; Mjolnir non acquisisce autorità solo perché si è unito a una stanza. Per la moderazione ordinaria di stanze di piccole dimensioni, gli strumenti integrati nella stanza potrebbero essere sufficienti. Mjolnir è più utile quando la stessa community gestisce più stanze o necessita di un flusso di lavoro controllato e condiviso.

La moderazione delle stanze e l'amministrazione del server domestico sono ambiti distinti. Mjolnir può gestire i ban e le oscurazioni a livello di stanza con le autorizzazioni appropriate. I comandi più invasivi a livello di server, come la disattivazione degli utenti, lo spostamento degli alias o la chiusura delle stanze, richiedono che Mjolnir sia un amministratore del server Synapse. Non concedere l'accesso di amministratore del server domestico a meno che i moderatori non abbiano una specifica necessità di eseguire tali operazioni.

Cosa bisogna preparare prima dell'installazione?

• Un account homeserver Matrix dedicato al bot, come ad esempio @mjolnir:example.org.
• Una sala di gestione privata in cui i moderatori autorizzati possono impartire comandi e ricevere messaggi di stato.
• Una directory o un volume persistente per la configurazione e lo stato di Mjolnir.
• Un piano per stanze crittografate. L'attuale configurazione di Mjolnir supporta la crittografia nativa; la configurazione documenta anche Pantalaimon come opzione separata e obsoleta. Non abilitare entrambe le opzioni contemporaneamente.
• Una stanza di prova in cui è possibile verificare inviti, autorizzazioni e comportamento delle liste prima di proteggere le stanze di produzione più utilizzate.

Come si installa Mjolnir?

Il progetto upstream documenta l'installazione di Docker e l'auto-compilazione. Per la maggior parte degli amministratori che già utilizzano i container, Docker Compose è comodo perché consente di riavviare il bot e visualizzare i log senza dover tenere aperto un terminale interattivo. Segui le istruzioni di configurazione di Docker del progetto e blocca una release revisionata in produzione anziché affidarti indefinitamente a un latesttag fluttuante. L'immagine ufficiale è matrixdotorg/mjolnir.

Prepara la configurazione prima di avviare il container. La guida Docker originale prevede che la configurazione si trovi in ​​una directory di dati persistente in config/production.yaml. Assicurati che questa directory sia leggibile solo dagli amministratori e dal servizio che ne hanno bisogno. Il file potrebbe contenere un token di accesso o altre credenziali di login; non caricarlo in un repository pubblico, non incollarlo in una chat di supporto e non includerlo nei log.

Utilizza la configurazione predefinita corrente del progetto, completa di commenti, come fonte di riferimento per i nomi delle opzioni. Come minimo, imposta l'URL del server principale e la sala di gestione, quindi configura l'autenticazione e la crittografia per la distribuzione scelta. Se utilizzi una configurazione basata su token, tratta il token come una password. La guida di configurazione originale descrive come ottenerlo accedendo come bot da un profilo browser separato in Element e aprendo Impostazioni, Guida e informazioni, e la sezione Token di accesso. Avverte di non disconnettersi successivamente, poiché ciò potrebbe invalidare il token; chiudi invece quel profilo browser. Per una sala di gestione crittografata, abilita e testa il supporto di crittografia di Mjolnir prima di utilizzare i comandi in quella posizione.

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

Quel breve estratto non rappresenta una configurazione completa. In particolare, le impostazioni di crittografia e di accesso dipendono dal fatto che si utilizzi la crittografia nativa o il percorso opzionale di Pantalaimon. Si consiglia di fare riferimento all'esempio attuale anziché copiare un vecchio post del blog o un file compose. La guida di configurazione di Mjolnir raccomanda inoltre di mantenere il bot vicino al server principale in termini di rete per ridurre la latenza di risposta.

Come si dovrebbe mettere in sicurezza la sala direzionale?

Crea una stanza per i moderatori fidati, invita l'account del bot e rendi la stanza privata per il team di moderazione. L'ID o l'alias della stanza va inserito in managementRoom. La configurazione attuale descrive questa stanza come la fonte dei comandi e avverte che chiunque possa inviare comandi lì può controllare Mjolnir; non fornisce un livello di controllo degli accessi più granulare per singolo comando. Questo rende essenziale la revisione dell'iscrizione. Rimuovi tempestivamente gli ex moderatori e non utilizzare la stanza di controllo del bot come chat generale della community.

Si consiglia di crittografare la sala di gestione. Se la si crittografa, verificare che Mjolnir sia in grado di leggere e rispondere ai messaggi utilizzando il metodo di crittografia configurato. Un bot che si è unito a una sala crittografata ma non riesce a decrittografarne gli eventi potrebbe risultare online ignorando i comandi. Per diagnosticare il problema, anziché disattivare la crittografia della sala come primo tentativo, utilizzare la configurazione di crittografia a monte e i relativi log.

Quali autorizzazioni dovrebbe ricevere Mjolnir?

Invita il bot in ogni stanza che deve proteggere e assegnagli un livello di potenza sufficiente per eseguire le azioni di moderazione previste. Matrix utilizza i livelli di potenza della stanza per operazioni come ban, espulsioni, oscuramento degli eventi di altri utenti e modifica dello stato della stanza. Il valore richiesto è definito dall'evento relativo al livello di potenza della stanza; i valori predefiniti di Matrix per ban, espulsione e oscuramento sono generalmente 50, se non specificati, ma le singole stanze possono modificarli.

Le linee guida della community di Matrix descrivono il livello di potenza 100 come una configurazione comune per Mjolnir, in modo che possa imporre le decisioni di moderazione. Tuttavia, questo livello è considerevole: chiunque possa controllare l'account Mjolnir ha di fatto tale autorità nelle stanze protette e il bot può diventarne il proprietario di fatto. Esaminate i livelli di potenza di ogni stanza e scegliete un livello che consenta al bot di eseguire le azioni richieste, limitando al contempo l'autorità non necessaria. Non assegnategli i privilegi di amministratore del server domestico per la normale moderazione delle stanze.

In Element, puoi invitare il bot dal pannello dei membri della stanza o inserire un comando di invito come /invite @mjolnir:example.org. Dopo che si è unito, modifica il suo ruolo nell'elenco dei membri della stanza. Ripeti l'operazione per ogni stanza da proteggere. Mjolnir non può proteggere le stanze a cui non si è unito, il che deriva dal modello di permessi decentralizzato di Matrix, stanza per stanza.

Come si crea una lista di utenti bloccati e si aggiungono stanze protette?

Una volta che il bot si è avviato e ha pubblicato il suo stato nella sala di gestione, crea lì un elenco di policy. La guida rapida di Mjolnir utilizza questo esempio:

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

Il primo comando crea una stanza con la lista di ban tramite lo shortcode COC; la persona che la crea viene invitata in modo che possa gestirne la visibilità. Il secondo seleziona tale lista come predefinita per i successivi comandi di moderazione. Il terzo aggiunge una stanza al set di stanze protette di Mjolnir. Il comando di verifica controlla se il bot dispone delle autorizzazioni necessarie nelle stanze protette, mentre il comando di stato aiuta a confermare che stia funzionando come previsto. Utilizza !mjolnir helpper visualizzare la sintassi dei comandi disponibile nella versione installata.

Mantieni privato un elenco di regole se contiene note interne o è destinato solo al tuo team. Rendilo pubblico solo quando desideri che altre community lo scoprano e lo sottoscrivano. Le regole di Mjolnir si sommano tra i vari elenchi, quindi rivedi gli elenchi monitorati prima di farvi affidamento; un elenco può continuare a corrispondere a un utente o a un server anche se rimuovi una regola duplicata da un altro elenco.

Cosa bisogna testare prima di utilizzarlo in un incidente reale?

• Conferma che il bot pubblichi messaggi di avvio e di stato nella sala di gestione configurata.
• Avvia il programma !mjolnir verifydopo averlo invitato nella stanza di prova e avergli assegnato il ruolo scelto.
• Esegui il comando !mjolnir roomse verifica che venga visualizzata la stanza desiderata, senza che siano incluse stanze non correlate.
• Esaminate !mjolnir protectionse attivate solo le protezioni che comprendete; le protezioni automatiche possono avere ripercussioni sugli utenti legittimi.
• Utilizza un account di prova e una stanza temporanea per convalidare la procedura di ban, sblocco e oscuramento del team prima di applicarla ai membri reali.
• Controlla i log del container e i messaggi della sala di gestione di Mjolnir se il bot non esegue i comandi o segnala autorizzazioni mancanti.

Non effettuare test bannando un membro reale della community o utilizzando un tasto jolly su un server attivo. I ban con tasti jolly possono avere un impatto su molti utenti; la configurazione predefinita attuale richiede un flag di conferma aggiuntivo per i ban con tasti jolly. Leggi la guida per i moderatori prima di abilitare le protezioni automatiche e documenta chi può approvare un'azione ad alto impatto.

Quali sono gli errori di configurazione più comuni?

• Assegnare i privilegi di amministratore al server del bot per comodità: la moderazione a livello di stanza di solito richiede l'accesso alla stanza stessa, non i diritti di amministratore di Synapse.
• Lasciando la sala di gestione ampiamente accessibile: a ogni membro in grado di impartire comandi vengono affidati i controlli di moderazione del bot.
• Dimenticare i permessi per le stanze protette: un bot può essere online e non riuscire comunque a bannare o oscurare i contenuti se il suo livello di autorizzazione è troppo basso.
• Utilizzo di stanze crittografate senza configurare la crittografia: la sola iscrizione non consente al bot di leggere i comandi crittografati.
• Copia di una vecchia ricetta di configurazione: la configurazione e il supporto per la crittografia di Mjolnir sono in continua evoluzione; si consiglia di utilizzare l'esempio predefinito e la documentazione di configurazione attuali.
• Supponendo che la rimozione da una lista annulli tutti i divieti: un'altra lista di monitoraggio potrebbe comunque applicare la stessa regola.

Dove è possibile verificare i dettagli aggiornati?

Iniziate consultando la guida di configurazione di Mjolnir , la guida per i moderatori e la cronologia delle versioni . Per le autorizzazioni delle stanze, consultate la guida alla moderazione della community di Matrix e le specifiche di Matrix per i livelli di potenza delle stanze . I comandi di installazione e le impostazioni di crittografia esatte dipendono dal vostro homeserver, dalla configurazione del container e dalla versione di Mjolnir; in caso di modifiche alle istruzioni, questi riferimenti ufficiali dovrebbero avere la precedenza.