Come configurare un bot Matrix con Python e Simple-Matrix-Bot-Lib

Cosa stai effettivamente scegliendo quando crei un bot Matrix in questo modo?

Simple-Matrix-Bot-Lib è un livello di utilità che si sovrappone alla matrix-niolibreria client Python. Questo lo rende interessante quando si desidera un piccolo bot per comandi, notifiche o un assistente per le stanze senza dover scrivere da zero l'intero ciclo di sincronizzazione e gestione degli eventi di Matrix. Il compromesso è che si accettano le astrazioni e i modelli di autenticazione esposti dal wrapper, anziché controllare direttamente ogni dettaglio del client Matrix.

Al 6 ottobre 2026, PyPI elenca la simplematrixbotlibversione 2.13.1, rilasciata il 29 marzo 2026, che richiede Python 3.9 o versioni successive, ma precedenti a Python 4. Il sito Read the Docs del progetto avverte attualmente che la documentazione non è più aggiornata e potrebbe essere obsoleta, pertanto questa guida utilizza PyPI e la specifica Matrix corrente come riferimenti principali e considera la documentazione precedente come una guida all'implementazione piuttosto che come prova del comportamento attuale.

Per il pacchetto stesso, consultare il progetto simplematrixbotlib su PyPI . Per il comportamento del protocollo, fare riferimento alla specifica corrente dell'API Matrix Client-Server .

Simple-Matrix-Bot-Lib, matrix-nio o un Application Service?

Se il tuo obiettivo è "rispondere ai comandi nelle stanze come un unico account bot", Simple-Matrix-Bot-Lib è solitamente la soluzione più breve. Se sai già di aver bisogno di autenticazione personalizzata, di un comportamento di sincronizzazione insolito, di una verifica dettagliata del dispositivo o di un controllo della crittografia di basso livello, iniziare con matrix-nio può evitarti di dover poi lottare con un wrapper. Per i bridge o le integrazioni che richiedono il routing a livello di homeserver, consulta l' API di Matrix Application Service invece di considerare un normale account bot come sostituto.

Passaggio 1: Scegli un homeserver e conferma come il bot può accedervi.

Un bot Matrix necessita di un account utente Matrix su un homeserver. Puoi utilizzare un homeserver pubblico che consenta la creazione di account oppure un account su un homeserver che amministri. Mantieni il bot separato dalla tua identità Matrix personale in modo che permessi, appartenenza alle stanze e credenziali possano essere gestiti in modo indipendente.

La decisione cruciale riguarda l'autenticazione. L'attuale specifica Matrix supporta sia l'API di autenticazione legacy che OAuth 2.0. Un homeserver può esporre una o entrambe. Gli esempi di avvio rapido pubblicati da Simple-Matrix-Bot-Lib utilizzano un URL, un nome utente e una password per l'homeserver, quindi questo tutorial presuppone che il server offra ancora un flusso di accesso tramite password compatibile.

Prima di scrivere codice, verifica i metodi di login esposti dal tuo homeserver:

curl https://matrix.example.com/_matrix/client/v3/login

Se la risposta include un flusso di accesso con password, l'esempio basato sulle credenziali riportato di seguito è appropriato. Se il server supporta solo SSO o solo OAuth, non forzare l'inserimento di una password nell'esempio. In tal caso, verifica il supporto per l'autenticazione nella versione corrente della libreria o utilizza un client di livello inferiore che supporti il ​​flusso necessario. La specifica Matrix illustra il rilevamento delle credenziali di accesso e la gestione dei token nella sezione relativa all'accesso dell'API Client-Server .

Passaggio 2: creare un ambiente Python isolato e installare la libreria

Utilizza un ambiente virtuale in modo che le dipendenze del bot siano separate dal Python di sistema e da progetti non correlati. I metadati PyPI attuali richiedono Python 3.9 o versioni successive.

mkdir matrix-bot
cd matrix-bot
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install simplematrixbotlib

In Windows PowerShell, attiva l'ambiente con:

.venv\Scripts\Activate.ps1

Verifica cosa è stato installato anziché presumere una versione basata su un vecchio tutorial:

python -m pip show simplematrixbotlib

Il controllo della versione è importante perché le pagine pubbliche di Read the Docs mostrano ancora documentazione obsoleta e avvertono esplicitamente che potrebbe essere superata. Se un esempio presente in queste pagine è in conflitto con il pacchetto installato, è necessario esaminare i metadati della release e il repository corrente prima di modificare il codice per adattarlo alla pagina precedente.

Hai bisogno della crittografia end-to-end?

Non tutti i bot lo fanno. Un bot che si unisce solo a stanze operative non crittografate è più semplice da implementare e non necessita di mantenere uno stato di crittografia. Un bot che deve leggere e rispondere all'interno di stanze crittografate richiede dipendenze aggiuntive e uno stato di crittografia persistente.

Sia la documentazione di Simple-Matrix-Bot-Lib che quella attuale di matrix-nio indicano che E2EE si basa sul supporto di crittografia di matrix-nio e su libolm. Su Debian o Ubuntu, i documenti di matrix-nio mostrano l'installazione libolm-deve poi l'aggiunta di E2EE:

sudo apt-get install libolm-dev
python -m pip install "matrix-nio[e2e]"

Non abilitare la crittografia end-to-end (E2EE) solo perché Matrix la supporta. Utilizzala quando le stanze richiedono la crittografia e sei pronto a rendere persistenti i dati del bot e a gestire la fiducia del dispositivo. La documentazione di matrix-nio specifica che lo stato della crittografia, le chiavi e la fiducia del dispositivo vengono memorizzati localmente quando la crittografia end-to-end è abilitata.

Passaggio 3: crea l'account del bot e non inserire le credenziali nel codice sorgente.

Crea un account Matrix dedicato utilizzando un client o la procedura di gestione dell'account fornita dal tuo homeserver. L'interfaccia utente di registrazione esatta varia a seconda del provider, quindi questa guida non presuppone una schermata Element specifica né afferma che la registrazione aperta sia disponibile ovunque.

Per lo sviluppo, esportare tre variabili d'ambiente:

export MATRIX_HOMESERVER="https://matrix.example.com"
export MATRIX_USERNAME="botname"
export MATRIX_PASSWORD="replace-with-a-secret"

Le variabili d'ambiente sono comode per un tutorial locale, ma non costituiscono automaticamente un sistema di gestione dei segreti di livello produttivo. Su una piattaforma VPS o container, è preferibile utilizzare l'archivio dei segreti della piattaforma, un file di ambiente protetto al di fuori del controllo di versione o un gestore di segreti dedicato. Non inserire mai una password Matrix o un token di accesso in Git.

Se il server o la configurazione del bot non gestiscono automaticamente gli inviti, invita l'account del bot in una stanza di prova e accetta l'invito tramite un client Matrix. Inizia con una stanza di prova privata. Questo limita l'esecuzione accidentale di comandi mentre verifichi il comportamento del bot.

Passaggio 4: Scrivi, esegui e testa un bot di comando minimale

Crea bot.pycon un piccolo !pingcomando. La struttura seguente segue l'esempio del pacchetto pubblico: crea Creds, crea Bot, aggiungi un listener di messaggi asincrono, usa MessageMatch, e invia un messaggio di testo tramite bot.api.

import os
import simplematrixbotlib as botlib

HOMESERVER = os.environ["MATRIX_HOMESERVER"]
USERNAME = os.environ["MATRIX_USERNAME"]
PASSWORD = os.environ["MATRIX_PASSWORD"]
PREFIX = "!"

creds = botlib.Creds(HOMESERVER, USERNAME, PASSWORD)
bot = botlib.Bot(creds)

@bot.listener.on_message_event
async def ping(room, message):
    match = botlib.MessageMatch(room, message, bot, PREFIX)

    if (
        match.is_not_from_this_bot()
        and match.prefix()
        and match.command("ping")
    ):
        await bot.api.send_text_message(room.room_id, "Pong!")

bot.run()

Eseguilo dall'ambiente virtuale attivato:

python bot.py

Nella sala d'esame, inviare:

!ping

Un risultato positivo è semplice: il bot rimane connesso, rileva l'evento della stanza e risponde con Pong!. Verifica inoltre che non risponda alla propria risposta. Questo is_not_from_this_bot()controllo è importante perché un bot ingenuo in stile echo potrebbe altrimenti creare cicli di feedback.

Quando è opportuno aggiungere una lista di elementi consentiti?

Aggiungine uno prima che il bot possa attivare qualsiasi operazione sensibile. Un comando che restituisce solo "Pong!" ha un impatto minimo, ma un comando che esegue processi di distribuzione, interroga sistemi interni o pubblica dati riservati non dovrebbe essere eseguito per ogni utente in ogni stanza a cui si è connessi.

Simple-Matrix-Bot-Lib pubblicizza la gestione degli accessi utente e la configurazione di liste di autorizzazione/blocco come funzionalità. Per un bot in produzione, è consigliabile considerare l'autorizzazione come parte della logica applicativa, non come un passaggio opzionale di rifinitura. Limitate l'accesso tramite ID utente, ID stanza o entrambi, e mantenete le autorizzazioni lato server sui sistemi a valle come seconda linea di difesa.

Accesso tramite password o tramite token di accesso: qual è il compromesso pratico?

L'accesso tramite password è facile da capire e corrisponde all'esempio minimo pubblicato nel pacchetto. Lo svantaggio è che un bot in esecuzione prolungata deve necessariamente conoscere la password dell'account, e alcune implementazioni moderne di Matrix potrebbero preferire flussi SSO o OAuth.

I token di accesso riducono l'uso ripetuto delle password, ma le regole del ciclo di vita dei token dipendono dal sistema di autenticazione. La specifica Matrix stabilisce che i token di accesso debbano essere trattati come credenziali opache e inviati utilizzando il Authorization: Bearerprotocollo HTTP. Le versioni attuali di Matrix supportano anche token di accesso con scadenza e token di aggiornamento in alcuni flussi. Non si deve presumere che un esempio scritto per le credenziali di password gestisca automaticamente l'aggiornamento, la revoca o l'autenticazione OAuth.

Se il ciclo di vita dei token, l'SSO, l'OAuth o l'autenticazione in stile account di servizio sono fondamentali per la tua implementazione, verifica questa funzionalità nella versione esatta di Simple-Matrix-Bot-Lib che installi. Se il wrapper non offre un controllo sufficiente, utilizzare direttamente matrix-nio è la scelta di ingegneria più pulita.

È meglio eseguire il bot su un laptop, un VPS, un container o Kubernetes?

Per un bot leggero non crittografato, una piccola macchina virtuale o un container sono solitamente sufficienti. Per un bot crittografato, la persistenza diventa un requisito di progettazione: la perdita dell'archivio crittografico locale può modificare l'identità del dispositivo e compromettere la fiducia. Gli esempi di crittografia end-to-end di matrix-nio sottolineano l'importanza di preservare l'ID del dispositivo e l'archivio crittografico anche dopo i riavvii.

Errori di configurazione comuni e il loro significato di solito

• L'accesso fallisce immediatamente: confermare l'URL del server principale e ispezionarlo /_matrix/client/v3/login. Un server che non pubblicizza l'accesso tramite password potrebbe non funzionare con un avvio rapido basato su password.
• Il bot si avvia ma non visualizza i messaggi: verifica che l'account del bot sia effettivamente connesso alla stanza e che tu stia eseguendo il test con un normale evento di testo.
• Il bot risponde ripetutamente: assicurati che il gestore ignori gli eventi inviati dal bot stesso.
• Le stanze crittografate sono illeggibili: installare il pacchetto base non è sufficiente. Aggiungere le dipendenze E2EE di matrix-nio, abilitare la crittografia in base alla configurazione della libreria e preservare l'archivio crittografico.
• Un vecchio esempio genera un errore API: verifica la versione del pacchetto installato. La documentazione pubblica di Simple-Matrix-Bot-Lib avverte attualmente che non è più mantenuta, quindi gli esempi potrebbero non essere aggiornati alla versione rilasciata su PyPI.

Quale percorso dovresti scegliere?

Scegli Simple-Matrix-Bot-Lib se il tuo bot è un singolo utente Matrix, i comandi sono semplici e dai più importanza al codice Python conciso che al controllo di protocolli di basso livello. È particolarmente adatto per prototipi, bot di notifica, utilità per le stanze e piccole automazioni interne.

Scegliete matrix-nio direttamente quando crittografia, verifica del dispositivo, autenticazione personalizzata, tipi di eventi, comportamento di sincronizzazione o gestione dei token sono requisiti fondamentali. Scriverete più codice, ma il livello di astrazione sarà più basso e più facile da comprendere per lavori avanzati con Matrix.

Scegli un servizio applicativo quando la tua integrazione è in realtà un'estensione, un bridge o un gateway del server domestico, piuttosto che un bot per un singolo utente. L'API del servizio applicativo è progettata per questo modello di connessione al server e richiede la configurazione del server domestico.

Per un primo bot Matrix, l' !pingesempio minimo rappresenta un buon punto di partenza: se riesce ad autenticarsi, ad accedere alla stanza corretta, a ignorare i propri eventi e a rispondere in modo affidabile, il percorso di base è stato validato. Aggiungete crittografia, autorizzazione, API esterne e automazione del deployment solo dopo che queste fondamenta si saranno consolidate.

Riferimenti primari

• Simple-Matrix-Bot-Lib su PyPI : metadati del pacchetto, requisiti Python, cronologia delle versioni ed esempio di base.
• Documentazione di Simple-Matrix-Bot-Lib : utile riferimento storico sull'utilizzo; il sito avverte attualmente che potrebbe essere obsoleta.
• Documentazione di matrix-nio : libreria client sottostante, dipendenze E2EE, archiviazione ed esempi.
• API client-server Matrix : comportamento attuale dei protocolli di autenticazione, login, token, stanza ed eventi.
• API del servizio applicativo Matrix : alternativa integrata server per bridge e integrazioni più complesse.