PythonとSimple-Matrix-Bot-Libを使用してMatrix Botをセットアップする方法

このようにマトリックスボットを構築する際、実際には何を選択していることになるのでしょうか？

Simple-Matrix-Bot-Libは、Pythonクライアントライブラリの上に構築された便利なレイヤーですmatrix-nio。そのため、Matrixの同期やイベント処理ループ全体を自分で記述することなく、小規模なコマンドボット、通知ボット、またはルームヘルパーを作成したい場合に便利です。ただし、Matrixクライアントの詳細をすべて直接制御するのではなく、ラッパーによって公開される抽象化と認証パターンを受け入れる必要があります。

2026年10月6日現在、PyPIにはsimplematrixbotlib2026年3月29日にリリースされたバージョン2.13.1が掲載されており、Python 3.9以降（ただしPython 4より前）が必要です。プロジェクトのRead the Docsサイトでは、ドキュメントがメンテナンスされておらず、古くなっている可能性があると警告されているため、このガイドではPyPIと現在のMatrix仕様を主要な参照資料として使用し、古いドキュメントは現在の動作の証明ではなく、実装に関するガイダンスとして扱います。

パッケージ自体については、PyPI の simplematrixbotlib プロジェクトを参照してください。プロトコルの動作については、最新の Matrix Client-Server API 仕様を参照してください。

Simple-Matrix-Bot-Lib、matrix-nio、それともアプリケーションサービス？

目的が「ルーム内のコマンドに単一のボットアカウントで応答する」ことであれば、Simple-Matrix-Bot-Lib が通常は最短ルートです。カスタム認証、特殊な同期動作、詳細なデバイス検証、または低レベルの暗号化制御が必要であることが既にわかっている場合は、matrix-nioから始めることで、後々のラッパーとの格闘を避けることができます。ホームサーバーレベルのルーティングが必要なブリッジや統合については、通常のボットアカウントを代用として扱うのではなく、Matrix Application Service API を参照してください。

ステップ1：ホームサーバーを選択し、ボットがログインする方法を確認します

Matrixボットには、ホームサーバー上のMatrixユーザーアカウントが必要です。アカウント作成が許可されている公開ホームサーバー、またはご自身で管理しているホームサーバーのアカウントを使用できます。権限、ルームメンバーシップ、認証情報を個別に管理できるよう、ボットは個人のMatrix IDとは別に管理してください。

重要な決定事項は認証です。現在のMatrix仕様は、従来の認証APIとOAuth 2.0の両方をサポートしています。ホームサーバーは、どちらか一方、または両方を公開している場合があります。Simple-Matrix-Bot-Libで公開されているクイックスタートの例では、ホームサーバーのURL、ユーザー名、パスワードを使用しているため、このチュートリアルでは、サーバーが互換性のあるパスワードログインフローを提供していることを前提としています。

コードを書く前に、ホームサーバーが公開しているログイン方法を確認してください。

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

レスポンスにパスワードログインフローが含まれる場合は、以下の認証情報ベースの例が適切です。サーバーがSSOのみ、またはOAuthのみの場合は、例にパスワードを強制しないでください。その場合は、現在のライブラリリリースで認証がサポートされていることを確認するか、必要なフローをサポートする下位レベルのクライアントを使用してください。Matrix仕様では、クライアント/サーバーAPIのログインセクションで、ログイン検出とトークン処理について説明しています。

ステップ2：隔離されたPython環境を作成し、ライブラリをインストールします。

仮想環境を使用することで、ボットの依存関係をシステムPythonや無関係なプロジェクトから分離できます。現在のPyPIメタデータでは、Python 3.9以降が必要です。

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

Windows PowerShell で、以下のコマンドを使用して環境をアクティブ化します。

.venv\Scripts\Activate.ps1

古いチュートリアルに記載されているバージョンを前提とするのではなく、実際に何がインストールされているかを確認してください。

python -m pip show simplematrixbotlib

バージョンチェックが重要なのは、公開されているRead the Docsページには古いドキュメントがまだ掲載されており、それらが最新ではない可能性があるという警告が明示的に表示されているためです。これらのページにある例がインストール済みのパッケージと競合する場合は、コードを古いページに合わせて変更する前に、リリースメタデータと現在のリポジトリを確認してください。

エンドツーエンド暗号化が必要ですか？

すべてのボットがそうするわけではありません。暗号化されていない運用ルームにのみ参加するボットは、展開が容易で、暗号化状態を維持する必要もありません。暗号化されたルーム内でメッセージの読み取りと返信を行うボットは、追加の依存関係と永続的な暗号化状態を必要とします。

Simple-Matrix-Bot-Lib のドキュメントと現在の matrix-nio のドキュメントの両方で、E2EE は matrix-nio の暗号化サポートと libolm に依存していることが示されています。Debian または Ubuntu では、matrix-nio のドキュメントにインストール手順libolm-devと E2EE エクストラのインストール手順が記載されています。

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

MatrixがE2EEをサポートしているからといって、安易にE2EEを有効にしないでください。E2EEは、ルームで暗号化が必要であり、ボットのストアを永続化し、デバイスの信頼性を管理する準備ができている場合にのみ使用してください。matrix -nioのドキュメントには、E2EEを有効にすると、暗号化状態、キー、およびデバイスの信頼性がローカルに保存されると記載されています。

ステップ3：ボットアカウントを作成し、認証情報をソースコードから除外する

クライアントまたはホームサーバーが提供するアカウント管理プロセスを使用して、専用のMatrixアカウントを作成してください。登録画面はプロバイダーによって異なるため、このガイドでは特定のElement画面を想定しておらず、すべての場所で登録が可能であるとは断言していません。

開発環境向けに、以下の3つの環境変数をエクスポートします。

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

環境変数はローカル環境でのチュートリアルには便利ですが、本番環境レベルのシークレット管理システムとして自動的に機能するわけではありません。VPSやコンテナプラットフォームでは、プラットフォームのシークレットストア、ソース管理外の保護された環境ファイル、または専用のシークレットマネージャーを使用することをお勧めします。MatrixのパスワードやアクセストークンをGitにコミットしないでください。

サーバーまたはボットの設定で招待が自動参加されない場合は、ボットアカウントをテストルームに招待し、Matrixクライアントで招待を承諾してください。まずはプライベートテストルームから始めましょう。これにより、ボットの動作検証中に誤ってコマンドが実行されることを防ぐことができます。

ステップ4：最小限のコマンドボットを作成、実行、テストする

bot.py簡単なコマンドで作成します!ping。以下の構造は、公開パッケージの例に従います。 を作成しCreds、 を作成しBot、非同期メッセージリスナーを追加し、 を使用しMessageMatch、 を介してテキストメッセージを送信します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()

アクティベートされた仮想環境から実行してください。

python bot.py

テストルームでは、以下を送信してください。

!ping

成功の条件は単純です。ボットが接続を維持し、ルームイベントを認識し、応答しますPong!。また、ボットが自身の応答に返信しないことも確認してください。このis_not_from_this_bot()チェックは重要です。なぜなら、単純なエコー型ボットはフィードバックループを発生させてしまう可能性があるからです。

許可リストはいつ追加すべきですか？

ボットが機密情報を実行する前に、コマンドを追加してください。「Pong!」を返すだけのコマンドは影響が少ないですが、デプロイメントジョブを実行したり、内部システムに問い合わせたり、機密データを投稿したりするコマンドは、参加しているすべてのルームのすべてのユーザーに対して実行されるべきではありません。

Simple-Matrix-Bot-Libは、ユーザーアクセス管理と許可/ブロックリストの設定を機能として宣伝しています。しかし、本番環境で使用するボットの場合、認証はオプションの仕上げステップではなく、アプリケーションロジックとして扱うべきです。ユーザーID、ルームID、またはその両方でアクセスを制限し、ダウンストリームシステムのサーバー側権限を第二の防御線として維持してください。

パスワードログインとアクセストークン：実際的なトレードオフは？

パスワードログインは理解しやすく、パッケージに公開されている最小限のサンプルと一致しています。欠点は、長時間稼働するボットがアカウントのパスワードを保持している必要があることであり、最新のMatrix展開では、代わりにSSOまたはOAuthフローが好まれる場合があります。

アクセストークンはパスワードの繰り返し使用を減らしますが、トークンのライフサイクルルールは認証システムによって異なります。Matrixの仕様では、アクセストークンは不透明な認証情報として扱われ、HTTPAuthorization: Bearerスキームを使用して送信されるべきだとされています。現在のMatrixバージョンでは、一部のフローで有効期限付きアクセストークンとリフレッシュトークンもサポートされています。パスワード認証情報用に作成されたサンプルが、リフレッシュ、失効、またはOAuthを自動的に処理すると想定しないでください。

トークンライフサイクル、SSO、OAuth、またはサービスアカウント方式の認証がデプロイメントの中心となる場合は、インストールするSimple-Matrix-Bot-Libのリリースでこれらの機能が利用可能かどうかを確認してください。ラッパーが十分な制御機能を提供していない場合は、matrix-nioを直接使用する方がよりクリーンな設計上の選択肢となります。

ボットはノートパソコン、VPS、コンテナ、それともKubernetesのどれで実行すべきでしょうか？

暗号化されていない軽量ボットの場合、通常は小型のVMまたはコンテナで十分です。暗号化されたボットの場合、永続性が設計要件となります。ローカルの暗号化ストアが失われると、デバイスのIDが変更され、信頼性が損なわれる可能性があるためです。matrix-nioのE2EEの例では、再起動後もデバイスIDと暗号化ストアを保持することを重視しています。

よくある設定ミスとその意味

• ログインはすぐに失敗します。ホームサーバーのURLを確認し、検査してください/_matrix/client/v3/login。パスワードログインを推奨していないサーバーは、パスワードベースのクイックスタートでは動作しない可能性があります。
• ボットは起動するものの、メッセージを認識しません。ボットアカウントが実際にルームに参加していること、および通常のテキストイベントでテストしていることを確認してください。
• ボットは繰り返し「ハンドラーがボット自身から送信されたイベントを無視するようにしてください」と応答します。
• 暗号化されたルームは読み取れません。基本パッケージをインストールするだけでは不十分です。matrix-nioのE2EE依存関係を追加し、ライブラリの設定に従って暗号化を有効にし、暗号ストアを保持する必要があります。
• 古いサンプルコードではAPIエラーが発生します。インストールされているパッケージのバージョンを確認してください。Simple-Matrix-Bot-Libの公開ドキュメントは現在メンテナンスされていないため、サンプルコードがPyPIのリリースに遅れる可能性があると警告しています。

あなたはどちらの道を選ぶべきでしょうか？

Simple-Matrix-Bot-Libは、ボットが単一のMatrixユーザーで構成され、コマンドがシンプルで、低レベルのプロトコル制御よりも簡潔なPythonコードを重視する場合に最適です。特に、プロトタイプ、通知ボット、ルームユーティリティ、小規模な内部自動化に適しています。

暗号化、デバイス検証、カスタム認証、イベントタイプ、同期動作、トークン管理が必須要件である場合は、matrix-nioを直接選択してください。記述するコード量は増えますが、抽象化の境界が低くなり、高度なMatrix処理を理解しやすくなります。

統合対象が単一ユーザーボットではなく、ホームサーバーの拡張機能、ブリッジ、またはゲートウェイである場合は、アプリケーションサービスを選択してください。アプリケーションサービスAPIは、サーバー接続モデル向けに設計されており、ホームサーバーの設定が必要です。

初めてのMatrixボットの場合、最小限の!pingサンプルが適切なチェックポイントとなります。認証ができ、正しいルームに参加でき、自身のイベントを無視し、確実に応答できるのであれば、基本的な動作は確認できたことになります。暗号化、認可、外部API、デプロイの自動化などは、その基盤が安定してから追加しましょう。

主要参考文献

• PyPI上のSimple-Matrix-Bot-Lib — 現在のパッケージメタデータ、Pythonの要件、リリース履歴、および基本的な例。
• Simple-Matrix-Bot-Lib のドキュメント— 有用な過去の使用例の参考資料ですが、現在、サイトには情報が古くなっている可能性があるという警告が表示されています。
• matrix-nio のドキュメント— 基盤となるクライアントライブラリ、E2EE の依存関係、ストレージ、およびサンプル。
• Matrixクライアント/サーバーAPI — 現在の認証、ログイン、トークン、ルーム、およびイベントプロトコルの動作。
• Matrix Application Service API ― ブリッジや大規模な統合のための、サーバー統合型の代替手段。