วิธีการตั้งค่า Matrix Bot ด้วย Python และ Simple-Matrix-Bot-Lib

เมื่อคุณสร้างบอท Matrix ด้วยวิธีนี้ คุณกำลังเลือกอะไรกันแน่?

Simple-Matrix-Bot-Lib เป็นเลเยอร์อำนวยความสะดวกบนmatrix-nioไลบรารีไคลเอ็นต์ Python ทำให้เป็นที่น่าสนใจเมื่อคุณต้องการบอทคำสั่งขนาดเล็ก บอทแจ้งเตือน หรือผู้ช่วยในห้องแชท โดยไม่ต้องเขียนลูปการซิงค์และการจัดการเหตุการณ์ของ Matrix ทั้งหมดด้วยตนเอง ข้อเสียคือคุณต้องยอมรับรูปแบบนามธรรมและการตรวจสอบสิทธิ์ที่เปิดเผยโดยตัวห่อหุ้มแทนที่จะควบคุมรายละเอียดไคลเอ็นต์ Matrix ทุกอย่างโดยตรง

ณ วันที่ 6 ตุลาคม 2026 PyPI ระบุเวอร์ชันsimplematrixbotlib2.13.1 ซึ่งเผยแพร่เมื่อวันที่ 29 มีนาคม 2026 และต้องการ Python 3.9 หรือใหม่กว่า แต่ต่ำกว่า Python 4 เว็บไซต์ Read the Docs ของโครงการในปัจจุบันเตือนว่าเอกสารประกอบไม่ได้รับการดูแลรักษาและอาจล้าสมัย ดังนั้นคู่มือนี้จึงใช้ PyPI และข้อกำหนด Matrix ปัจจุบันเป็นแหล่งอ้างอิงหลัก และถือว่าเอกสารเก่าเป็นแนวทางในการใช้งานมากกว่าเป็นหลักฐานยืนยันพฤติกรรมปัจจุบัน

สำหรับตัวแพ็กเกจเอง โปรดดูที่โปรเจ็กต์ simplematrixbotlib บน PyPIส่วนพฤติกรรมของโปรโตคอล ให้ใช้ข้อกำหนด API ไคลเอ็นต์-เซิร์ฟเวอร์ของ Matrix ฉบับปัจจุบัน

Simple-Matrix-Bot-Lib, matrix-nio หรือ Application Service?

หากเป้าหมายของคุณคือ “ตอบคำสั่งในห้องแชทโดยใช้บัญชีบอทเดียว” Simple-Matrix-Bot-Lib มักจะเป็นทางเลือกที่สั้นที่สุด แต่ถ้าคุณรู้แล้วว่าต้องการการตรวจสอบสิทธิ์แบบกำหนดเอง พฤติกรรมการซิงค์ที่ผิดปกติ การตรวจสอบอุปกรณ์อย่างละเอียด หรือการควบคุมการเข้ารหัสระดับต่ำ การเริ่มต้นด้วยmatrix-nioจะช่วยหลีกเลี่ยงปัญหาการใช้งาน wrapper ในภายหลัง สำหรับ bridges หรือ integrations ที่ต้องการการกำหนดเส้นทางระดับ homeserver โปรดอ่านAPI ของ Matrix Application Serviceแทนที่จะใช้บัญชีบอทปกติเป็นตัวแทน

ขั้นตอนที่ 1: เลือกโฮมเซิร์ฟเวอร์และยืนยันวิธีการที่บอทสามารถเข้าสู่ระบบได้

บอท 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 อธิบายการค้นหาการเข้าสู่ระบบและการจัดการโทเค็นในส่วนการเข้าสู่ระบบของ Client-Server 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

การตรวจสอบเวอร์ชันนั้นมีความสำคัญ เพราะหน้า "อ่านเอกสาร" ที่เผยแพร่สู่สาธารณะยังคงแสดงเอกสารเวอร์ชันเก่า และมีการแจ้งเตือนอย่างชัดเจนว่าเอกสารเหล่านั้นอาจล้าสมัย หากตัวอย่างจากหน้าเหล่านั้นขัดแย้งกับแพ็กเกจที่ติดตั้งไว้ ให้ตรวจสอบเมตาเดตาของรุ่นและที่เก็บปัจจุบันก่อนที่จะแก้ไขโค้ดของคุณให้ตรงกับหน้าเวอร์ชันเก่า

คุณต้องการการเข้ารหัสแบบ end-to-end หรือไม่?

ไม่ใช่ทุกบอทที่จะทำแบบนั้น บอทที่เข้าร่วมเฉพาะห้องปฏิบัติการที่ไม่เข้ารหัสจะง่ายต่อการใช้งานและไม่จำเป็นต้องรักษาสถานะการเข้ารหัส บอทที่คาดว่าจะอ่านและตอบกลับภายในห้องปฏิบัติการที่เข้ารหัสจำเป็นต้องมีส่วนประกอบเพิ่มเติมและสถานะการเข้ารหัสแบบถาวร

เอกสารประกอบของ Simple-Matrix-Bot-Lib และเอกสารประกอบของ matrix-nio ในปัจจุบันระบุว่า E2EE อาศัยการสนับสนุนการเข้ารหัสและ libolm ของ matrix-nio บน Debian หรือ Ubuntu เอกสารของ matrix-nio อธิบายวิธีการติดตั้งlibolm-devและส่วนเสริม E2EE ดังนี้:

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

อย่าเปิดใช้งาน E2EE เพียงเพราะ Matrix รองรับฟังก์ชันนี้ ควรใช้เมื่อห้องสนทนาต้องการการเข้ารหัส และคุณพร้อมที่จะจัดเก็บข้อมูลของบอทและจัดการความน่าเชื่อถือของอุปกรณ์เอกสารประกอบของ 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 client หากเซิร์ฟเวอร์หรือการตั้งค่าบอทของคุณไม่ได้เปิดใช้งานการเข้าร่วมอัตโนมัติ เริ่มต้นด้วยห้องทดสอบส่วนตัว เพื่อจำกัดการเรียกใช้คำสั่งโดยไม่ตั้งใจในขณะที่คุณตรวจสอบพฤติกรรมของบอท

ขั้นตอนที่ 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 โฆษณาว่าการจัดการการเข้าถึงของผู้ใช้และการกำหนดค่าอนุญาต/บล็อกลิสต์เป็นคุณสมบัติเด่น สำหรับบอทที่ใช้งานจริง ควรพิจารณาการอนุญาตเป็นส่วนหนึ่งของตรรกะการทำงานของแอปพลิเคชัน ไม่ใช่ขั้นตอนการปรับแต่งเพิ่มเติม ควรจำกัดการเข้าถึงด้วยรหัสผู้ใช้ รหัสห้อง หรือทั้งสองอย่าง และเก็บสิทธิ์การเข้าถึงฝั่งเซิร์ฟเวอร์บนระบบปลายทางไว้เป็นแนวป้องกันที่สอง

การเข้าสู่ระบบด้วยรหัสผ่านเทียบกับการใช้โทเค็นการเข้าถึง: ข้อดีข้อเสียในทางปฏิบัติคืออะไร?

การเข้าสู่ระบบด้วยรหัสผ่านนั้นเข้าใจง่ายและตรงกับตัวอย่างขั้นต่ำที่เผยแพร่ไว้ในแพ็กเกจ ข้อเสียคือบอทที่ทำงานต่อเนื่องเป็นเวลานานจะต้องมีรหัสผ่านของบัญชี และการใช้งาน Matrix ในปัจจุบันบางระบบอาจต้องการใช้ SSO หรือ OAuth แทน

โทเค็นการเข้าถึงช่วยลดการใช้รหัสผ่านซ้ำๆ แต่กฎวงจรชีวิตของโทเค็นขึ้นอยู่กับระบบการตรวจสอบสิทธิ์ ข้อกำหนดของ Matrix ระบุว่าโทเค็นการเข้าถึงควรได้รับการปฏิบัติเสมือนข้อมูลประจำตัวที่ไม่โปร่งใสและส่งโดยใช้Authorization: Bearerรูปแบบ HTTP เวอร์ชัน Matrix ปัจจุบันยังรองรับโทเค็นการเข้าถึงที่หมดอายุและโทเค็นรีเฟรชในบางขั้นตอน อย่าคิดว่าตัวอย่างที่เขียนขึ้นสำหรับข้อมูลประจำตัวรหัสผ่านจะจัดการการรีเฟรช การยกเลิก หรือ OAuth โดยอัตโนมัติ

หากการจัดการวงจรชีวิตของโทเค็น, SSO, OAuth หรือการตรวจสอบสิทธิ์แบบบัญชีบริการมีความสำคัญต่อการใช้งานของคุณ โปรดตรวจสอบความสามารถนั้นในเวอร์ชัน Simple-Matrix-Bot-Lib ที่คุณติดตั้ง หากตัวห่อหุ้มไม่ให้การควบคุมที่เพียงพอ การใช้ matrix-nio โดยตรงจะเป็นทางเลือกทางวิศวกรรมที่สะอาดกว่า

คุณควรใช้งานบอทบนแล็ปท็อป, VPS, คอนเทนเนอร์ หรือ Kubernetes ดี?

สำหรับบอทขนาดเล็กที่ไม่ได้เข้ารหัส โดยปกติแล้ว VM หรือคอนเทนเนอร์ขนาดเล็กก็เพียงพอแล้ว แต่สำหรับบอทที่เข้ารหัสแล้ว การรักษาความต่อเนื่องของข้อมูลกลายเป็นข้อกำหนดในการออกแบบ: การสูญเสียที่เก็บข้อมูลการเข้ารหัสในเครื่องอาจเปลี่ยนแปลงตัวตนของอุปกรณ์และทำลายความน่าเชื่อถือ ตัวอย่าง E2EE ของ matrix-nio เน้นการรักษา ID อุปกรณ์และที่เก็บข้อมูลการเข้ารหัสไว้แม้หลังจากรีสตาร์ทเครื่อง

ข้อผิดพลาดในการติดตั้งที่พบบ่อยและโดยทั่วไปหมายความว่าอย่างไร

• การเข้าสู่ระบบล้มเหลวทันที:โปรดยืนยัน URL ของโฮมเซิร์ฟเวอร์และตรวจสอบ/_matrix/client/v3/loginเซิร์ฟเวอร์ที่ไม่ได้ประกาศการเข้าสู่ระบบด้วยรหัสผ่านอาจใช้งานไม่ได้กับการเริ่มต้นใช้งานอย่างรวดเร็วโดยใช้รหัสผ่าน
• บอทเริ่มต้นทำงานแต่ไม่เห็นข้อความใดๆ:โปรดยืนยันว่าบัญชีบอทได้เข้าร่วมห้องทดสอบแล้ว และคุณกำลังทดสอบด้วยการส่งข้อความตามปกติ
• บอทตอบกลับซ้ำๆ:ตรวจสอบให้แน่ใจว่าตัวจัดการเหตุการณ์เพิกเฉยต่อเหตุการณ์ที่ส่งมาจากบอทเอง
• ห้องที่เข้ารหัสแล้วไม่สามารถอ่านได้:การติดตั้งแพ็กเกจพื้นฐานอย่างเดียวไม่เพียงพอ ต้องเพิ่ม dependency ของ matrix-nio E2EE เปิดใช้งานการเข้ารหัสตามการตั้งค่าของไลบรารี และเก็บรักษา crypto store ไว้ด้วย
• ตัวอย่างเก่าตัวหนึ่งทำให้เกิดข้อผิดพลาด API:โปรดตรวจสอบเวอร์ชันแพ็กเกจที่ติดตั้งไว้ เอกสาร Simple-Matrix-Bot-Lib ฉบับสาธารณะในปัจจุบันเตือนว่าไม่มีการดูแลรักษาแล้ว ดังนั้นตัวอย่างอาจล้าหลังกว่าเวอร์ชันที่เผยแพร่บน PyPI

คุณควรเลือกเส้นทางไหน?

เลือกใช้ Simple-Matrix-Bot-Lib เมื่อบอทของคุณเป็นผู้ใช้ Matrix เพียงคนเดียว คำสั่งไม่ซับซ้อน และคุณให้ความสำคัญกับโค้ด Python ที่กระชับมากกว่าการควบคุมโปรโตคอลระดับต่ำ เหมาะอย่างยิ่งสำหรับต้นแบบ บอทแจ้งเตือน ยูทิลิตี้ห้องประชุม และระบบอัตโนมัติภายในขนาดเล็ก

เลือกใช้ matrix-nio โดยตรงเมื่อการเข้ารหัส การตรวจสอบอุปกรณ์ การตรวจสอบสิทธิ์แบบกำหนดเอง ประเภทเหตุการณ์ พฤติกรรมการซิงค์ หรือการจัดการโทเค็นเป็นข้อกำหนดหลัก คุณอาจต้องเขียนโค้ดมากขึ้น แต่ขอบเขตของนามธรรมจะต่ำกว่าและเข้าใจได้ง่ายกว่าสำหรับงาน Matrix ขั้นสูง

เลือกใช้บริการแอปพลิเคชันเมื่อการเชื่อมต่อของคุณเป็นส่วนขยายของโฮมเซิร์ฟเวอร์ ตัวเชื่อมต่อ หรือเกตเวย์ มากกว่าจะเป็นบอทสำหรับผู้ใช้คนเดียว API ของบริการแอปพลิเคชันได้รับการออกแบบมาสำหรับโมเดลที่เชื่อมต่อกับเซิร์ฟเวอร์และต้องมีการกำหนดค่าโฮมเซิร์ฟเวอร์

สำหรับบอท Matrix ตัวแรก!pingตัวอย่างที่เรียบง่ายที่สุดถือเป็นจุดตรวจสอบที่ดี: หากมันสามารถตรวจสอบสิทธิ์ เข้าร่วมห้องที่ถูกต้อง เพิกเฉยต่อเหตุการณ์ของตัวเอง และตอบกลับได้อย่างน่าเชื่อถือ นั่นหมายความว่าคุณได้ตรวจสอบเส้นทางพื้นฐานเรียบร้อยแล้ว ค่อยเพิ่มการเข้ารหัส การอนุญาต API ภายนอก และระบบอัตโนมัติในการปรับใช้หลังจากที่รากฐานนั้นมั่นคงแล้ว

เอกสารอ้างอิงหลัก

• Simple-Matrix-Bot-Lib บน PyPI — ข้อมูลเมตาของแพ็กเกจปัจจุบัน ข้อกำหนดของ Python ประวัติการเผยแพร่ และตัวอย่างพื้นฐาน
• เอกสารประกอบการใช้งาน Simple-Matrix-Bot-Lib — แหล่งข้อมูลอ้างอิงการใช้งานในอดีตที่มีประโยชน์; ปัจจุบันเว็บไซต์แจ้งเตือนว่าข้อมูลอาจล้าสมัยแล้ว
• เอกสารประกอบการใช้งาน matrix-nio — ไลบรารีไคลเอ็นต์พื้นฐาน, การพึ่งพาแบบ E2EE, การจัดเก็บข้อมูล และตัวอย่างการใช้งาน
• Matrix Client-Server API — พฤติกรรมปัจจุบันของโปรโตคอลการตรวจสอบสิทธิ์ การเข้าสู่ระบบ โทเค็น ห้อง และเหตุการณ์
• Matrix Application Service API — ทางเลือกที่ผสานรวมเข้ากับเซิร์ฟเวอร์สำหรับบริดจ์และการผสานรวมขนาดใหญ่