如何使用 Python 和 Simple-Matrix-Bot-Lib 設定 Matrix Bot

當你以這種方式建造 Matrix 機器人時，你實際上選擇了什麼？

Simple-Matrix-Bot-Lib 是 Python 用戶端程式庫之上的一個便捷層matrix-nio。如果您需要一個簡單的命令機器人、通知機器人或房間助手，但又不想自己編寫完整的 Matrix 同步和事件處理循環，那麼它就非常實用。但缺點是，您需要接受該封裝層提供的抽象和身份驗證模式，而不是直接控制 Matrix 用戶端的每個細節。

截至 2026 年 10 月 6 日，PyPI 列出了simplematrixbotlib2.13.1 版本，發佈於 2026 年 3 月 29 日，需要 Python 3.9 或更高版本，但低於 Python 4。該專案的 Read the Docs 網站目前警告其文件已停止維護，可能已過時，因此本指南主要參考 PyPI 和當前的 Matrix 規範，並將舊文件視為實現指南，而非當前行為的證明。

關於軟體包本身，請參閱PyPI 上的 simplematrixbotlib 專案。關於協定行為，請使用目前的 Matrix 用戶端-伺服器 API 規格。

Simple-Matrix-Bot-Lib、matrix-nio 還是應用程式服務？

如果你的目標是“使用同一個機器人帳號回覆房間內的指令”，那麼 Simple-Matrix-Bot-Lib 通常是最快捷的途徑。如果你已經知道需要自訂身份驗證、特殊的同步行為、詳細的設備驗證或底層加密控制，那麼從matrix-nio入手可以避免日後與封裝庫的衝突。對於需要 homeserver 等級路由的橋接或集成，請閱讀Matrix 應用服務 API ，而不是將普通的機器人帳號作為替代方案。

第一步：選擇一個伺服器並確認機器人如何登入

Matrix 機器人需要一個 Matrix 使用者帳戶，位於主伺服器上。您可以使用允許建立帳戶的公用主伺服器，也可以使用您管理的主伺服器上的帳戶。請將機器人帳戶與您的個人 Matrix 帳戶分開，以便可以獨立管理權限、房間成員資格和憑證。

關鍵在於身份驗證。目前的 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) 就啟用它。只有當房間需要加密，並且您已準備好持久化機器人的儲存並處理設備信任時才應啟用它。 Matrix -NIO 文件指出，啟用 E2EE 後，加密狀態、金鑰和裝置信任將儲存在本機。

步驟 3：建立機器人帳戶並將憑證保存在原始程式碼之外

使用用戶端或您的伺服器提供的帳戶管理流程建立專用的 Matrix 帳戶。特定的註冊介面因服務提供者而異，因此本指南並未預設特定的 Element 介面，也不保證所有地方都提供開放式註冊。

為了進行開發，需要導出三個環境變數：

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

環境變數對於本機教學來說很方便，但它們並非生產級金鑰管理系統。在 VPS 或容器平台上，建議使用平台自帶的金鑰儲存庫、位於原始碼控制之外的受保護環境變數文件，或使用專用的金鑰管理器。切勿將 Matrix 密碼或存取權杖提交至 Git。

如果您的伺服器或機器人設定未啟用自動加入邀請的功能，請使用 Matrix 用戶端邀請機器人帳號加入測試房間並接受邀請。建議先在私密測試房間中進行測試，這樣可以減少在驗證機器人行為時意外執行命令的可能性。

第四步：編寫、運行、測試一個最小命令機器人

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 上運行機器人？

對於未加密的輕量級機器人，通常一個小型虛擬機器或容器就足夠了。但對於加密機器人，持久性就成為一項設計要求：失去本地加密儲存會導致裝置身分改變，從而破壞信任關係。 matrix-nio 的端對端加密範例強調在重新啟動後保留裝置 ID 和加密儲存。

常見的設定故障及其通常意義

• 登入立即失敗：請確認主伺服器 URL 並進行檢查/_matrix/client/v3/login。未公開密碼登入的伺服器可能無法與基於密碼的快速啟動功能搭配使用。
• 機器人啟動但從未收到訊息：請確認機器人帳戶已實際加入房間，並且您正在使用普通文字事件進行測試。
• 機器人反覆回覆：請確保處理程序忽略機器人本身發送的事件。
• 加密房間無法讀取：僅安裝基礎軟體包是不夠的。需要新增 matrix-nio E2EE 依賴項，根據程式庫配置啟用加密，並保留加密儲存。
• 一個舊範例會引發 API 錯誤：請檢查您已安裝的軟體套件版本。 Simple-Matrix-Bot-Lib 的公開文件目前已停止維護，因此範例可能與 PyPI 版本不符。

你該選擇哪條路？

如果您的機器人僅供單一 Matrix 使用者使用，命令簡單明了，並且您更重視簡潔的 Python 程式碼而非底層協定控制，那麼 Simple-Matrix-Bot-Lib 是您的理想之選。它尤其適用於原型開發、通知機器人、聊天室工具以及小型內部自動化。

當加密、裝置驗證、自訂身分驗證、事件類型、同步行為或令牌管理是核心需求時，可以直接選擇 matrix-nio。雖然程式碼量會增加，但抽象邊界更低，更便於進行高階 Matrix 工作。

如果您的整合實際上是作為 HomeServer 擴充功能、橋接器或網關，而不是單一使用者機器人，請選擇應用服務。應用程式服務 API 專為這種伺服器連接模型而設計，並且需要對 HomeServer 進行設定。

對於第一個 Matrix 機器人來說，最小!ping範例是一個很好的檢查點：如果它能夠通過身份驗證、加入正確的房間、忽略自身事件並可靠地回复，那麼你就驗證了基本路徑。只有在基礎架構穩定之後，才能新增加密、授權、外部 API 和部署自動化功能。

主要參考文獻

• Simple-Matrix-Bot-Lib 在 PyPI 上— 目前軟體包元資料、Python 要求、發布歷史和基本範例。
• Simple-Matrix-Bot-Lib 文件－有用的歷史使用參考；該網站目前警告說，它可能已過時。
• matrix-nio 文件— 底層客戶端程式庫、E2EE 相依性、儲存與範例。
• Matrix 用戶端-伺服器 API — 目前驗證、登入、令牌、房間和事件協定行為。
• Matrix Application Service API — 適用於橋接和大型整合的伺服器整合替代方案。