Simple-Matrix-Bot-Lib을 사용하여 Python으로 Matrix Echo Bot을 구축하세요.

2026년 10월 10일 현재, PyPI에는 Simple-Matrix-Bot-Lib 2.13.1 버전이 등록되어 있으며, 이 버전은 2026년 3월 29일에 릴리스되었습니다. 이 패키지는 Python 3.9 이상을 요구하지만, Python 3.9는 지원이 종료되었으므로 패키지에서 지원하는 유지 관리되는 Python 버전을 사용하십시오. 호스팅된 프로젝트 문서에는 여전히 2.11.0 버전이 표시되어 있고 유지 관리가 중단되었다는 경고가 있으므로, 이 가이드에서는 봇 API에 대해서는 현재 PyPI 예제를 따르고 이전 설명서는 명확하게 표시된 구성 참고 사항에만 사용합니다. PyPI에서 패키지 릴리스 및 메타데이터를 확인하십시오 . 프로젝트 문서 상태를 참조하십시오 .

가장 빠르고 안정적인 설정은 전용 Matrix 사용자 계정, Python 가상 환경, 그리고 테스트룸에서 응답하는 소형 에코봇을 사용하는 것입니다 !echo. 이 예시는 암호화되지 않은 테스트룸을 기준으로 작성되었으며, 암호화된 테스트룸의 경우 추가 설정이 필요합니다.

라이브러리를 설치하기 전에 무엇이 필요합니까?

봇을 실행할 홈서버에 일반 계정을 생성하거나 요청하세요. 고유한 사용자 이름(예 echo_bot: )을 지정하세요. 홈서버 관리자 권한은 필요하지 않습니다. 해당 서버에서 계정 등록이 비활성화되거나 제한될 수 있으므로 계정 생성 정책을 준수하세요. 메시지 전송이 허용된 비공개 테스트룸에만 해당 계정을 초대하세요.

Python 3.11 또는 현재 지원되는 다른 Python 브랜치를 사용하십시오. 패키지 메타데이터에는 여전히 Python 3.9가 허용되지만, Python.org는 해당 브랜치의 지원을 2025년 10월 31일로 종료했으므로 패키지의 최소 요구 사항은 적절한 배포 권장 사항이 아닙니다. Python.org의 Python 3.9 지원 공지를 참조하십시오 .

Simple-Matrix-Bot-Lib은 어떻게 설치하나요?

새 프로젝트 폴더에서 다음 명령어를 실행하세요. 가상 환경은 이 봇의 패키지를 다른 Python 프로젝트와 분리하여 관리합니다. 버전 고정(version pin)을 사용하면 이 문서에서 검증된 최신 릴리스를 기준으로 예제를 재현할 수 있습니다. 업그레이드할 때는 현재 PyPI 릴리스와 호환성 정보를 확인하세요.

python3 --version
python3 -m venv .venv
source .venv/bin/activate
python -m pip install "simplematrixbotlib==2.13.1"

.venv\Scripts\Activate.ps1Windows PowerShell에서 `--config` 명령 대신 ` --config` 명령을 사용하여 환경을 활성화합니다 source. 그런 다음 `.pypi.py`라는 이름의 파일을 생성합니다 bot.py. PyPI 프로젝트 페이지에는 패키지 이름과 설치 명령이 설명되어 있으며, 공개된 예제에서는 `.pypi.py`, `.pypi.py`, 메시지 리스너 및 `.pypi.py`를 사용합니다 Creds. Bot현재 MessageMatchPyPI 사용 예제를 참조하세요 .

터미널 명령어를 사용하여 파이썬 가상 환경을 생성하고 활성화한 후 simplematrixbotlib 버전 2.13.1을 설치합니다.
터미널에는 봇 프로젝트에 대한 격리된 환경과 고정된 패키지 설치 명령이 표시됩니다.

봇 계정을 연결하고 명령어를 추가하는 방법은 무엇인가요?

다음 내용을 .로 저장하세요 bot.py. 시작 시 봇 암호를 입력하라는 메시지가 표시되므로 암호는 소스 파일에 기록되지 않습니다. 무인 서비스 배포를 위해서는 암호를 하드코딩하는 대신 운영 체제의 암호 관리자 또는 보호된 환경 변수에서 암호를 읽어오세요. 라이브러리에서 생성된 세션 또는 액세스 토큰 저장소는 자격 증명으로 취급하여 비공개로 유지하고 버전 관리 시스템에서 제외하세요.

import getpass
import simplematrixbotlib as botlib

creds = botlib.Creds(
    homeserver="https://matrix.example.org",
    username="echo_bot",
    password=getpass.getpass("Bot password: "),
)
bot = botlib.Bot(creds)
PREFIX = "!"

@bot.listener.on_message_event
async def echo(room, message):
    match = botlib.MessageMatch(room, message, bot, PREFIX)
    if (match.is_not_from_this_bot()
            and match.prefix()
            and match.command("echo")):
        text = " ".join(match.args())
        reply = text or "Usage: !echo <text>"
        await bot.api.send_text_message(room.room_id, reply)

bot.run()

샘플 홈서버 URL을 사용자의 서버 기본 URL로 바꾸고 봇 계정의 사용자 이름과 비밀번호를 사용하세요. 리스너는 방 메시지를 수신하고, MessageMatch자신의 메시지는 무시하며 !echo명령만 처리합니다. API 호출은 나머지 단어들을 같은 방으로 다시 보냅니다. 이러한 이름과 메서드 호출은 라이브러리의 PyPI 예제를 따릅니다. Simple-Matrix-Bot-Lib 퀵스타트와 비교해 보세요 .

파이썬 편집기에서 임포트, getpass 프롬프트, Matrix 홈서버 및 echo_bot 자격 증명, 그리고 봇 초기화 화면이 표시됩니다.
자격 증명 블록은 전용 계정을 사용하고 암호를 파일에 저장하는 대신 암호를 입력하라는 메시지를 표시합니다.
on_message_event 리스너, MessageMatch 검사 및 send_text_message 호출을 보여주는 Python 편집기
핸들러는 봇이 보낸 메시지를 무시하고, !echo 명령과 일치하는 값을 찾아서 그 인수를 방으로 다시 보냅니다.

봇을 실행하고 제대로 작동하는지 확인하는 방법은 무엇인가요?

활성화된 가상 환경에서 다음 명령을 실행하십시오.

python bot.py

메시지가 나타나면 봇 계정 비밀번호를 입력하세요. 테스트 룸에서 를 보내세요 !echo hello. 정상적으로 작동하는 기본 봇은 에 응답합니다 hello. 응답이 없으면 봇 계정이 해당 룸에 참여했는지, 사용자가 메시지를 보낼 권한이 있는지, 홈서버 URL이 올바른지, 메시지가 정확한 !접두사로 시작하는지 확인하세요. 프로세스를 계속 실행 상태로 유지하세요. 터미널을 닫으면 이 간단한 포그라운드 배포가 중지됩니다.

매트릭스 형식의 테스트룸에서 @you:example.org가 !echo hello를 보내고 @echo_bot:example.org가 hello로 응답하는 것을 보여줍니다.
샘플 대화는 에코 명령에 대한 예상 요청과 응답을 보여주는 예시이며, 실제 테스트 결과가 아닙니다.

이 샘플은 종단 간 암호화된 채팅방 메시지를 처리하지 않습니다. 해당 라이브러리는 종단 간 암호화(E2EE)를 지원한다고 명시되어 있지만, 현재 호스팅되는 설명서는 2.11.0 버전으로 표시되어 있으며 최신 버전이 아닐 수 있습니다. 해당 설명서에는 추가적인 matrix-nio[e2e]종속성 및 Config.encryption_enabled설정에 대한 내용이 포함되어 있습니다. 암호화를 활성화하기 전에 설치하려는 버전에 맞는 정확한 설치 및 검증 단계를 확인하십시오. 이전 버전 설명서에는 join_on_invite봇이 접근해야 하는 채팅방에만 초대할 수 있도록 설정하는 방법도 나와 있습니다. 자동 채팅방 참여를 제어해야 하는 경우 해당 설정을 확인하십시오. 라이브러리의 종단 간 암호화 및 구성 설명서를 참조하십시오 .

봇이 로그인 상태를 유지하고 테스트룸의 구성원이며 응답을 !echo hello정상적으로 처리 하면 설정이 완료된 것입니다 hello. 실제 운영 환경에서는 프로세스 관리자를 통해 실행하고 비밀번호와 세션 데이터를 보호해야 합니다.

댓글 남기기

추측 없이 Synapse의 Systemd 파일 제한을 늘리는 방법

추측 없이 Synapse의 Systemd 파일 제한을 늘리는 방법

Synapse가 프로세스별 파일 열기 제한에 도달했는지 진단하고, 해당 서비스 또는 워커에 대한 systemd 드롭인을 설정하고, 실제 제한을 확인합니다.

요소에 "복호화 실패" 오류가 표시되나요? 누락된 룸 키를 복구하세요.

요소에 "복호화 실패" 오류가 표시되나요? 누락된 룸 키를 복구하세요.

오류가 특정 브라우저 또는 특정 이벤트에만 국한되는지 확인한 다음, Element의 복구 키 또는 신뢰할 수 있는 장치를 사용하여 암호화된 나머지 기록을 손상시키지 않고 복구할 수 있습니다.

데이터 손실 없이 오래된 Synapse 메시지와 미디어를 정리하세요

Synapse의 기록 및 미디어 삭제 API 또는 보존 설정을 사용하여 오래된 데이터를 안전하게 제거한 다음 완료 여부와 디스크 공간 복구를 확인하십시오.

Simple-Matrix-Bot-Lib을 사용하여 Python으로 Matrix Echo Bot을 구축하세요.

Simple-Matrix-Bot-Lib을 사용하여 Python으로 Matrix Echo Bot을 구축하세요.

최신 라이브러리를 설치하고, 전용 Matrix 계정을 연결한 다음, 더욱 안전한 자격 증명 처리와 명확한 테스트를 포함하는 간단한 !echo 봇을 실행하세요.

Matrix를 WhatsApp, Telegram, Discord에 각각 별도의 브리지로 연결하세요.

Matrix를 WhatsApp, Telegram, Discord에 각각 별도의 브리지로 연결하세요.

등록, 로그인 및 테스트가 각각 다른 세 개의 Mautrix 브리지를 설정하여 Docker 네트워킹, 계정 정책 및 동기화 관련 예상치 못한 문제를 방지하세요.

공유 파일을 손상시키지 않고 Synapse 미디어 디스크 공간을 확보하세요

Synapse 저장소를 채우는 항목을 찾고, 안전한 미디어 보존 설정을 지정하고, 디스크에서 파일을 직접 삭제하지 않고 원격 캐시를 정리하세요.

회의실 기록을 삭제하지 않고 비활성 Matrix 사용자 비활성화

회의실 기록을 삭제하지 않고 비활성 Matrix 사용자 비활성화

기기 활동을 검토하고, 관리자 API를 통해 비활성으로 확인된 Synapse 계정을 비활성화하고, 선택적 삭제 플래그가 실제로 무엇을 제거하는지 알아보세요.

Matrix Synapse에서 PostgreSQL 메모리 사용량 줄이기

PostgreSQL 메모리 사용량이 쿼리 작업, 공유 버퍼, 연결 또는 유지 관리 작업 중 어느 것에서 발생하는지 확인한 다음 Synapse에서 안전하게 적용할 수 있는 변경 사항을 적용하세요.

Matrix Synapse 룸 접속이 느린 이유와 확인 사항

Matrix Synapse 룸 접속이 느린 이유와 확인 사항

Synapse 설정을 변경하기 전에 Matrix 룸이 원격 홈서버에 느리게 참여하는 원인, 페더레이션 백오프, 로컬 데이터베이스 부하 또는 아웃바운드 발신자 대기열 등을 추적해 보세요.

Synapse에서 Matrix 가입을 종료하거나 초대 토큰을 요구하세요.

자체 호스팅 Synapse 서버에서 계정 생성을 중단하거나, 제한된 사용 횟수의 등록 토큰을 사용하여 초대 전용으로 가입을 유지하세요.