Python과 Simple-Matrix-Bot-Lib을 사용하여 Matrix 봇을 설정하는 방법

이런 식으로 매트릭스 봇을 만들 때 실제로 무엇을 선택하는 건가요?

Simple-Matrix-Bot-Lib은 파이썬 클라이언트 라이브러리 위에 구축된 편의 계층입니다 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 클라이언트-서버 API 사양을 참조하십시오 .

Simple-Matrix-Bot-Lib, matrix-nio, 아니면 애플리케이션 서비스?

"하나의 봇 계정으로 방에서 명령에 응답"하는 것이 목표라면 Simple-Matrix-Bot-Lib이 가장 빠른 해결책일 수 있습니다. 하지만 사용자 지정 인증, 특이한 동기화 동작, 상세한 장치 검증 또는 저수준 암호화 제어가 필요한 경우, matrix-nio 부터 시작하면 나중에 래퍼를 사용하는 번거로움을 피할 수 있습니다. 홈서버 수준의 라우팅이 필요한 브리지 또는 통합의 경우, 일반 봇 계정을 대용으로 사용하는 대신 Matrix 애플리케이션 서비스 API를 참조하십시오.

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 사양의 클라이언트-서버 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-devE2EE 추가 기능을 설치한 후 사용하는 방법이 나와 있습니다.

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

Matrix가 E2EE를 지원한다고 해서 무조건 활성화하지 마십시오. 암호화가 필요한 방에서 봇의 저장소를 영구 저장하고 장치 신뢰도를 관리할 준비가 된 경우에만 사용하십시오. matrix -nio 문서에 따르면 E2EE가 활성화되면 암호화 상태, 키 및 장치 신뢰도가 로컬에 저장됩니다.

3단계: 봇 계정을 생성하고 계정 정보는 소스 코드에 포함하지 마세요.

클라이언트를 사용하거나 홈서버에서 제공하는 계정 관리 프로세스를 통해 전용 Matrix 계정을 생성하세요. 정확한 등록 UI는 제공업체마다 다르므로, 이 가이드에서는 특정 Element 화면을 가정하거나 모든 곳에서 등록이 가능하다고 주장하지 않습니다.

개발을 위해 세 가지 환경 변수를 내보내십시오.

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()확인은 중요합니다. 그렇지 않으면 단순한 메아리형 봇이 피드백 루프를 만들 수 있기 때문입니다.

언제 허용 목록을 추가해야 할까요?

봇이 민감한 작업을 실행하기 전에 미리 조치를 취해야 합니다. 단순히 "퐁!"만 반환하는 명령어는 큰 영향을 미치지 않지만, 배포 작업을 실행하거나 내부 시스템을 조회하거나 기밀 데이터를 게시하는 명령어는 모든 사용자가 참여한 모든 채팅방에서 실행되어서는 안 됩니다.

Simple-Matrix-Bot-Lib은 사용자 접근 관리 및 허용/차단 목록 구성 기능을 제공한다고 광고합니다. 하지만 실제 운영 환경에서 봇을 개발할 때는 권한 부여를 선택적인 마무리 작업이 아닌 애플리케이션 로직으로 처리해야 합니다. 사용자 ID, 방 ID 또는 둘 다를 기준으로 접근을 제한하고, 하위 시스템의 서버 측 권한 설정을 2차 방어선으로 활용하십시오.

비밀번호 로그인과 액세스 토큰 방식 중 어느 것이 실질적인 장단점이 있을까요?

비밀번호 로그인은 이해하기 쉽고 패키지에 게시된 최소 예제와 일치합니다. 단점은 장시간 실행되는 봇은 계정 비밀번호를 보유해야 하며, 일부 최신 Matrix 배포 환경에서는 SSO 또는 OAuth 흐름을 선호할 수 있다는 점입니다.

액세스 토큰은 비밀번호 반복 사용을 줄여주지만, 토큰 수명 주기 규칙은 인증 시스템에 따라 다릅니다. Matrix 사양에서는 액세스 토큰을 불투명한 자격 증명으로 취급하고 HTTP Authorization: Bearer스키마를 사용하여 전송해야 한다고 명시하고 있습니다. 최신 Matrix 버전은 일부 흐름에서 만료되는 액세스 토큰과 갱신 토큰도 지원합니다. 비밀번호 자격 증명을 위해 작성된 예제가 갱신, 해지 또는 OAuth를 자동으로 처리한다고 가정해서는 안 됩니다.

토큰 수명 주기, SSO, OAuth 또는 서비스 계정 방식 인증이 배포의 핵심이라면, 설치하는 Simple-Matrix-Bot-Lib 릴리스에서 해당 기능이 제대로 구현되었는지 확인하십시오. 래퍼에서 충분한 제어 기능을 제공하지 않는다면 matrix-nio를 직접 사용하는 것이 더 깔끔한 설계 방식입니다.

봇을 노트북, VPS, 컨테이너 또는 쿠버네티스에서 실행해야 할까요?

암호화되지 않은 경량 봇의 경우 일반적으로 작은 VM이나 컨테이너로 충분합니다. 하지만 암호화된 봇의 경우, 지속성 확보가 설계 필수 요건이 됩니다. 로컬 암호화 저장소가 손실되면 장치 ID가 변경되어 신뢰도가 손상될 수 있기 때문입니다. matrix-nio의 E2EE 예제는 재시작 시 장치 ID와 암호화 저장소를 보존하는 것을 강조합니다.

일반적인 설정 오류 및 그 의미

• 로그인이 즉시 실패합니다. 홈서버 URL을 확인하고 검사하십시오 /_matrix/client/v3/login. 비밀번호 로그인을 지원하지 않는 서버는 비밀번호 기반 빠른 시작과 호환되지 않을 수 있습니다.
• 봇이 시작되지만 메시지를 인식하지 못하는 경우: 봇 계정이 실제로 채팅방에 참여하고 있는지, 그리고 일반 텍스트 이벤트를 사용하여 테스트하고 있는지 확인하십시오.
• 봇이 반복적으로 응답합니다. 핸들러가 봇 자체에서 보낸 이벤트를 무시하도록 설정하세요.
• 암호화된 방은 읽을 수 없습니다. 기본 패키지를 설치하는 것만으로는 충분하지 않습니다. matrix-nio E2EE 종속성을 추가하고, 라이브러리 구성에 따라 암호화를 활성화하고, 암호화 저장소를 유지하십시오.
• 이전 예제에서 API 오류가 발생했습니다. 설치된 패키지 버전을 확인하세요. Simple-Matrix-Bot-Lib 공개 문서에서는 현재 유지 관리가 중단되었으므로 예제가 PyPI 릴리스보다 늦을 수 있다고 경고하고 있습니다.

어떤 길을 선택해야 할까요?

봇에 Matrix 사용자가 한 명뿐이고, 명령어가 간단하며, 저수준 프로토콜 제어보다 간결한 Python 코드를 더 중요하게 생각한다면 Simple-Matrix-Bot-Lib을 선택하세요. 특히 프로토타입, 알림 봇, 회의실 유틸리티 및 소규모 내부 자동화에 적합합니다.

암호화, 장치 검증, 사용자 지정 인증, 이벤트 유형, 동기화 동작 또는 토큰 관리가 핵심 요구 사항인 경우 matrix-nio를 직접 선택하십시오. 코드를 더 많이 작성해야 하지만 추상화 경계가 낮아 고급 Matrix 작업에 필요한 개념을 더 쉽게 이해할 수 있습니다.

통합 대상이 단일 사용자 봇이 아닌 홈서버 확장, 브리지 또는 게이트웨이인 경우 애플리케이션 서비스를 선택하십시오. 애플리케이션 서비스 API는 이러한 서버 연결 모델에 맞게 설계되었으며 홈서버 구성이 필요합니다.

Matrix 봇을 처음 만들 때는 최소한의 !ping예제를 통해 기본적인 작동 여부를 점검하는 것이 좋습니다. 인증이 제대로 되는지, 올바른 방에 참여하는지, 자체 이벤트를 무시하는지, 그리고 안정적으로 응답하는지 등을 확인하면 기본적인 구현은 완료된 것입니다. 이러한 기반이 안정된 후에 암호화, 권한 부여, 외부 API, 배포 자동화 기능을 추가하세요.

주요 참고 문헌

• PyPI의 Simple-Matrix-Bot-Lib — 현재 패키지 메타데이터, Python 요구 사항, 릴리스 내역 및 기본 예제.
• Simple-Matrix-Bot-Lib 문서 — 유용한 과거 사용 내역 참조 자료입니다. 현재 해당 사이트는 문서가 최신 정보가 아닐 수 있음을 경고하고 있습니다.
• matrix-nio 문서 — 기본 클라이언트 라이브러리, E2EE 종속성, 저장소 및 예제.
• Matrix 클라이언트-서버 API - 현재 인증, 로그인, 토큰, 회의실 및 이벤트 프로토콜 동작 방식.
• Matrix 애플리케이션 서비스 API — 브리지 및 대규모 통합을 위한 서버 통합형 대안입니다.