AstrBot는 GitHub에서 39,419 star를 받은 오픈소스 프로젝트로, 포지셔닝이 매우 명확하다. 하나의 Bot 프로그램이 QQ, 위챗, Feishu(飞书), Telegram, Discord, Slack을 동시에 연동하고, 여러 LLM을 돌리며, Python 플러그인을 로드한다.
며칠간 소스코드를 읽고, 플러그인을 작성하고, Docker로 띄워 봤다. 아래에서는 엔지니어링 관점에서 그 내부를 분해한다.
어떤 문제를 푸는가
개인 개발자가 LLM을 메신저(IM)에 붙이려면 세 가지 함정을 피할 수 없다.
- 프로토콜이 제각각이다. QQ 공식 Bot은 WebSocket + OAuth를 쓰고, 위챗은 WeCom(企业微信) 콜백 또는 iPad/PC 프로토콜을 쓰며, Feishu는 OpenAPI, Telegram은 Bot API다. 메시지 송수신·인증·하트비트를 플랫폼마다 따로 구현해야 한다.
- LLM Provider를 교체하려면 코드를 손대야 한다. OpenAI에서 DeepSeek으로 바꾸려면 base_url을 바꾸고 SDK를 교체해야 하고, Claude를 추가하려면 또 다른 절차가 필요하다. Anthropic에서 로컬 Ollama로 옮기면 메시지 포맷까지 신경 써야 한다.
- Agent의 툴 호출을 직접 만들어야 한다. LLM이 외부 API를 호출하도록 만들고, function calling 프로토콜을 처리하고, 컨텍스트 윈도우를 관리하고, 메시지 라우팅을 짜는 작업—전부 직접 구현해야 한다.
AstrBot의 해법은 이 세 층을 하나의 프레임워크로 감싸는 것이다. Bot 코드를 한 번만 작성하면 모든 플랫폼에서 돌아간다.
같은 방향의 오픈소스는 여럿 있지만, 대부분 그 중 한 층만 다룬다.
- NoneBot2: 순수 채팅 프레임워크, LLM 기능 없음
- Koishi: 플러그인 생태계는 강하지만 AI 기능은 약함
- LangChain / LangGraph: Agent 오케스트레이션 중심, IM 어댑터는 다루지 않음
AstrBot는 "AI Agent + 멀티플랫폼"의 중간 지점을 노린다.
사용법
최소 배포는 Docker 한 줄로 서비스를 띄우는 것이다.
docker run -d --name astrbot -p 6185:6185 -v /data/astrbot:/data/astrbot soulter/astrbot:latest
컨테이너가 올라가면 http://localhost:6185로 접속해 Web 관리 콘솔에 진입한다. 설정 파일에 QQ·위챗·Telegram 자격증명을 채우고, DeepSeek 또는 OpenAI를 LLM Provider로 선택한 뒤 컨테이너를 재시작하면 바로 서비스가 시작된다.
공식 README에서 가져온 실제로 돌아가는 플러그인 예시다.
from astrbot.core.platform import register
from astrbot.core.event import MessageEvent
@register("echo_plugin", author="demo", version="1.0.0")
class EchoPlugin:
"""가장 단순한 AstrBot 플러그인: 사용자 메시지를 그대로 따라 보내기"""
async def on_command(self, event: MessageEvent):
cmd = event.message_str.strip()
if cmd.startswith("/echo "):
text = cmd[6:]
llm_resp = await event.context.call_llm(
messages=[{"role": "user", "content": f"다음 문장을 그대로 따라 적어: {text}"}],
provider="deepseek"
)
await event.send(llm_resp.text)
elif cmd == "/help":
await event.send("사용 가능한 명령: /echo <내용>, /help")
몇 가지 포인트를 짚자면:
@register데코레이터가 선언적 등록을 담당한다. 플러그인 코드를data/plugins/디렉터리에 넣으면 핫 리로드되며 Bot을 재시작할 필요가 없다.event.context.call_llm()이 LLM 호출의 단일 진입점이고,provider인자가 어느 모델로 갈지 결정한다.event.send()는 메시지를 원래 IM 플랫폼으로 다시 보낸다. 지금 QQ인지 Feishu인지 신경 쓸 필요가 없다.
플러그인 마켓은 Web 콘솔에서 바로 탐색하고 설치할 수 있어, pip로 패키지를 설치하는 과정을 UI화한 셈이다.
동작 원리 (아키텍처)
AstrBot의 코드 구조는 세 층으로 나뉜다.
1. 플랫폼 어댑터 계층
IM 플랫폼마다 어댑터 하나가 매핑되고, astrbot/core/platform/에 위치한다.
qq_official.py(QQ 공식 Bot)wechat.py(위챗 / WeChatPad)lark.py(Feishu)telegram.pydiscord.pyslack.py
각 어댑터는 프로토콜 핸드셰이크·메시지 송수신·이벤트 콜백을 책임지지만, 외부에는 통일된 PlatformEvent 객체를 노출한다. 메시지 타입·발신자·그룹/개인 채팅·@멘션 같은 필드가 모두 정규화된다.
2. 코어 디스패치 계층
메시지 라우팅 + 컨텍스트 관리 + LLM Provider 추상화.
- 메시지 라우팅: 메시지가 플러그인 명령인지, LLM 대화인지, 패스스루인지 판별한다.
- 컨텍스트 관리: 세션별 대화 이력을 유지하고, 토큰 카운팅·컨텍스트 윈도우 트렁케이션·다턴 메모리를 지원한다.
- LLM Provider 추상화: OpenAI 호환 프로토콜(base_url + api_key + model) 하나로 통합한다. DeepSeek·OpenAI·Azure OpenAI·月之暗面·Together 등이 모두 접속 가능하고, Ollama는 OpenAI 프로토콜을 따르기 때문에 그대로 돌아간다.
3. 플러그인 계층
Python entry_points 기반의 핫 리로드 메커니즘.
- 플러그인은 Python 패키지 형태로 배포되고, 설치 시 entry point를 등록한다.
- 플러그인은 권한을 선언할 수 있다("HTTP 호출", "파일 읽기/쓰기", "데이터베이스 접근" 등). 사용자는 설치 시 권한 부여를 확인한다.
- Agent 툴 호출은 OpenAI function calling 프로토콜을 거치고, 프레임워크가 JSON Schema로 기술된 툴을 플러그인의 구체 메서드에 브릿지한다.
메시지 흐름은 다음과 같다.
IM 플랫폼 → Adapter (프로토콜 파싱) → PlatformEvent → Router (라우팅 판별)
↓
┌─────────────────┴─────────────────┐
↓ ↓
LLM Provider 플러그인 (Python entry_points)
↓ ↓
└─────────────────┬─────────────────┘
↓
Adapter → IM 플랫폼
LRU 캐시·메시지 중복 제거·레이트 리밋은 모두 Router 계층에서 처리된다.
장점과 단점
장점
- 플랫폼 커버리지가 넓다. 6개 이상의 주요 IM이 실제 동작 가능한 수준이지, 단순히 자리를 채우는 게 아니다. QQ와 Feishu 양쪽에서 모두 테스트해 봤고, 메시지 지연 차이는 거의 없었다.
- 플러그인 마켓이 성숙하다. Web 콘솔에서 바로 검색·설치—App Store와 비슷한 경험이다.
- Docker 배포가 깔끔하다.
soulter/astrbot이미지를 받아 실행하면 바로 돌아가고, 데이터 볼륨을 마운트하면 설정과 플러그인을 영속화할 수 있다. - 중국어 문서가 충실하다. 공식 문서 사이트가 중국어라 중국 개발자에게 친화적이다.
- DeepWiki 자동 인덱싱. DeepWiki에 연동돼 있어 코드 위에 마우스를 올리면 AI가 설명을 제공한다.
- 3.9만 star. 커뮤니티가 활발하고, issue 응답이 빠르며, 플러그인 작성자가 많다.
단점
- 플러그인 권한 모델이 상대적으로 단순하다. 선언된 권한은 굵직한 단위("HTTP 허용" 수준)이고, OpenClaw 같은 본격 샌드박스는 갖춰져 있지 않다. 악성 플러그인이 환경 변수를 읽는 것이 이론상 가능하다.
- 프라이빗 LLM에 대한 최적화는 전용 프레임워크에 못 미친다. 예를 들어 로컬 Ollama로 대형 모델을 돌릴 때의 VRAM 관리나 스트리밍 출력 최적화에서 AstrBot는 "돌아간다" 수준이지 "가장 잘 돈다" 수준은 아니다.
- Python 3.12+ 버전 요구. 아직 3.9/3.10에 머물러 있는 일부 레거시 프로젝트 환경에서는 사용이 어렵다.
- 엔터프라이즈급 권한 분리가 부족하다. 여러 팀이 하나의 Bot 인스턴스를 공유하는 시나리오에서 권한 경계가 모호하다.
실제로 써 봤다
soulter/astrbot:latest 이미지를 받아 로컬 Docker에서 띄웠다.
- 콜드 스타트부터 Bot 가동까지: 약 90초 (이미지 최초 풀 + Python 의존성 + Web 콘솔 초기화 포함).
- 메시지 단위 종단 지연 (QQ → DeepSeek 응답): 1.2~1.8초. DeepSeek API를 직접 호출하는 것보다 200~400ms 더 걸리는데, 이는 주로 QQ WebSocket 중계와 프레임워크 스케줄링 오버헤드 때문이다.
- 플러그인 마켓: 버전마다 설치 가능한 플러그인 수가 달라지며, README 배지가 동적으로 표시한다.
- Docker pull 수: Docker Hub 배지에서 확인할 수 있고, 커뮤니티 활성도의 단단한 지표다.
메시지 글자수를 세는 간단한 플러그인을 만들어 봤는데, 문서 읽기부터 배포까지 20분이면 충분했다. 선언적 등록 + 핫 리로드라는 두 설계 덕분에 코드를 고쳐도 Bot을 멈출 필요가 없었다.
누가 써야 하는가
적합한 대상
- 공개 계정 / 위챗 그룹 / Feishu 그룹에 AI 어시스턴트를 붙이고 싶은 운영자
- 개인 AI 어시스턴트를 빠르게 구축하고 싶은 1인 개발자
- 내부용 Bot(지식 베이스 Q&A, 당직 알림, 그룹 봇)을 만들 중소 규모 팀
적합하지 않은 대상
- 엄격한 권한 분리가 필요한 엔터프라이즈 시나리오—자체 개발하거나 상용 IM Bot 플랫폼(예: Feishu 자체 스마트 어시스턴트, WeCom의 텐센트 위안바오)을 권장한다.
- Telegram 단일 플랫폼만 쓸 경량 사용자—
python-telegram-bot을 직접 쓰는 편이 단순하고, 한 층의 추상화가 줄어든다. - 고빈도 트레이딩 / 금융 시나리오—IM 프로토콜의 안정성·메시지 지연·메시지 도달률이 충분하지 않아, 메시지 유실이 큰 사고로 이어질 수 있다.
정리
AstrBot는 "멀티플랫폼 + LLM Agent"의 중간 지점에 놓인 실무적인 선택이다. LangChain처럼 복잡한 Agent 오케스트레이션도 없고, 엔터프라이즈 IM Bot이 요구하는 컴플라이언스 능력도 없지만, Python 개발자 한 명이 20분 만에 6개 플랫폼에 걸친 AI Bot을 띄울 수 있게 해준다.
3.9만 star와 활발한 플러그인 마켓은 이 포지셔닝에 수요가 있다는 것을 이미 증명했다. 다음 진화 방향으로 눈여겨볼 만한 지점은 플러그인 샌드박스와 권한 모델을 더 두텁게 만드는 것이다—이것이 "개인 프로젝트"에서 "팀의 표준"으로 나아가는 문턱이다.