AstrBot(메신저 위에 Agent를 올리는 올인원 오픈소스 챗봇 플랫폼)

GitHub의 AstrBotDevs/AstrBot를 자세히 보면, AstrBot은 단순한 “챗봇 하나”라기보다 여러 메신저 플랫폼, 여러 LLM 제공자, 플러그인 시스템, 지식베이스, Agent 실행 계층을 하나로 묶은 통합형 AI 챗봇 인프라에 가깝습니다. 공식 설명도 “주요 IM 플랫폼과 통합되는 오픈소스 올인원 Agent 챗봇 플랫폼”이며, 개인용 AI 비서부터 고객지원, 업무 자동화, 사내 지식베이스까지 다양한 시나리오를 겨냥하고 있습니다. 

문서와 저장소를 함께 보면 이 프로젝트는 AstrBotDevs 조직과 전 세계 오픈소스 기여자들이 유지하는 비영리 성격의 프로젝트이며, 라이선스는 AGPL-v3입니다. 또 네트워크 서비스 형태로 수정본을 제공하면 변경사항 공개 의무가 생긴다는 점이 문서에 명시돼 있습니다. 즉, “오픈소스니까 일단 가져다 SaaS로 감싸면 끝” 같은 프로젝트는 아니고, 운영·배포 전략까지 포함해 검토해야 하는 플랫폼형 소프트웨어입니다. 

 

GitHub - AstrBotDevs/AstrBot: Agentic IM Chatbot infrastructure that integrates lots of IM platforms, LLMs, plugins and AI featu

 

---

프로젝트 소개

AstrBot을 한 문장으로 정리하면 이렇습니다.

“메신저 안에서 동작하는 Agentic AI 애플리케이션을 빠르게 만들고 운영하기 위한 통합 런타임”

공식 README와 문서 기준으로 AstrBot은 다음을 한 번에 제공합니다. 메신저 연동, 모델 제공자 연동, Agent Runner, WebUI/ChatUI, 플러그인, MCP, 지식베이스, 웹 검색, 자동 컨텍스트 압축, 샌드박스 실행 환경까지 포함합니다. 특히 “IM workflow 안에서 production-ready AI application을 빠르게 구축한다”는 표현이 핵심입니다. 즉 사용자는 웹앱을 새로 만드는 대신, 이미 쓰고 있는 메신저를 AI 앱의 인터페이스로 삼을 수 있습니다. (GitHub)

지원 범위도 꽤 넓습니다. 문서에는 18개 이상 메신저 플랫폼 연동 가이드가 있고, README에는 QQ, Telegram, Slack, Discord, WeCom, Feishu, DingTalk, LINE, Satori, Misskey 등이 정리돼 있습니다. 모델 쪽도 OpenAI 호환 API, Anthropic, Gemini, DeepSeek, Ollama, LM Studio 등과 연결할 수 있습니다. 즉 AstrBot은 특정 모델이나 특정 채널에 종속된 프레임워크가 아니라, 채널과 모델을 모두 추상화한 통합 허브라고 보는 편이 맞습니다. (AstrBot)

---

왜 이 프로젝트가 등장했을까

이 프로젝트가 흥미로운 이유는, 지금 AI 챗봇 개발이 보통 아래처럼 분절되어 있기 때문입니다.

1. 메신저 연동은 별도 봇 SDK로 처리
2. LLM 호출은 또 다른 SDK나 게이트웨이로 처리
3. 멀티턴 에이전트 로직은 LangChain류나 별도 Agent 프레임워크로 처리
4. 운영은 Docker, WebUI, 플러그인, 지식베이스를 또 따로 붙임

이렇게 되면 “텔레그램/디스코드/사내 메신저 어디서든 돌아가고, 플러그인 설치되고, 문서 검색되고, 웹에서 관리되는 AI 봇”을 만들기 위해 너무 많은 조각을 직접 꿰어야 합니다. AstrBot은 이 문제를 정면으로 해결하려고 나왔습니다. 공식 문서가 AstrBot을 all-in-one Agentic assistant로 소개하고, 이벤트 버스 및 파이프라인 기반의 높은 모듈성을 강조하는 이유도 여기에 있습니다. (AstrBot)

특히 문서의 Agent Runner 설명이 이 프로젝트의 문제의식을 잘 보여줍니다. AstrBot 팀은 Dify, Coze, Alibaba Bailian 같은 “내장형 Agent 기능을 가진 서비스”를 예전에는 일반 Chat Provider처럼 다뤘지만, 실제로는 단순 텍스트 완성과 다르게 계획-행동-관찰-재계획 루프를 수행하는 별도 계층이 필요하다고 판단했습니다. 그래서 v4.7.0부터 이를 Chat Provider와 Agent Runner로 분리했습니다. 이건 단순 기능 추가가 아니라, LLM 호출과 에이전트 실행을 아키텍처 수준에서 분리한 설계 결정입니다. (AstrBot)

---

AstrBot의 핵심 아이디어

AstrBot을 이해하는 가장 좋은 방법은, 이 프로젝트를 “봇”이 아니라 “플랫폼”으로 보는 것입니다.

1) 입력 채널은 메신저다

QQ, Telegram, Slack, Discord 같은 여러 채널에서 메시지를 받습니다. 공식 문서 기준으로 다수의 주류 IM 플랫폼을 지원하며, 멀티 인스턴스 배치도 고려하고 있습니다. (GitHub)

2) 추론 엔진은 모델 제공자 + Agent Runner다

모델 제공자는 “한 번 답하는” 역할이고, Agent Runner는 “생각하고 행동하는” 역할입니다. 이 분리가 AstrBot의 설계 핵심입니다. (AstrBot)

3) 기능 확장은 플러그인과 도구다

플러그인 시스템과 1000개 이상 플러그인 생태계를 전면에 내세우고 있습니다. 커스텀 명령, 이벤트 처리, 메시지 응답, 저장소 접근, 이미지 생성 등 개발자 확장 포인트가 많습니다. (GitHub)

4) 운영 관리는 WebUI/ChatUI가 담당한다

CLI 프로젝트가 아니라, 시각적 관리 대시보드와 경량 ChatUI를 함께 제공하는 점이 큰 차별점입니다. 이건 “개발자가 만들기 쉬운 프레임워크”를 넘어, 실제로 운영 가능한 제품 형태를 지향한다는 의미입니다. (GitHub)

---

핵심 기능

1. 멀티 플랫폼 메신저 연동

AstrBot은 메신저 채널을 AI 애플리케이션의 프런트엔드처럼 취급합니다. README에 QQ Official, OneBot v11, Telegram, WeCom, WeChat Official Accounts, Feishu, DingTalk, Slack, Discord, LINE, Satori, Misskey 등이 명시돼 있고, 문서에서는 18개 이상 플랫폼 통합을 안내합니다. (GitHub)

개발자 관점에서 이게 중요한 이유는, 비즈니스 로직을 채널별로 새로 쓰지 않아도 되기 때문입니다. 예를 들어 “질문 응답 + 문서 검색 + 도구 호출” 흐름을 만들어두면, 이를 텔레그램 봇으로도, 사내 협업 메신저용 봇으로도 재사용할 수 있습니다. 결국 AstrBot은 메시지 채널 추상화 계층을 제공합니다. (GitHub)

2. 다양한 모델 서비스와의 연결

AstrBot은 OpenAI 호환 서비스, Anthropic, Gemini, Moonshot AI, Zhipu AI, DeepSeek, Ollama, LM Studio 등을 지원합니다. 여기에 Whisper, TTS류도 포함돼 있어 텍스트 중심을 넘어 음성 관련 기능까지 이어질 수 있습니다. (GitHub)

이 구조는 특정 모델 벤더에 종속되지 않도록 해줍니다. 개발자는 “이 봇은 OpenAI에서만 돌아간다”가 아니라, 같은 기능을 다른 API 게이트웨이나 자체 호스팅 모델로 옮길 수 있습니다. 특히 Ollama, LM Studio 지원은 로컬/온프레미스 지향 사용성과 맞닿아 있습니다. (GitHub)

3. Agent Runner 계층

이건 AstrBot을 평범한 챗봇 프레임워크와 구분하는 핵심입니다. 공식 문서에 따르면 Chat Provider는 단일 턴 완성을 담당하고, Agent Runner는 사용자 의도와 컨텍스트, 환경 상태를 받아 Plan → Act → Observe → Re-plan 루프를 반복합니다. 기본 내장 러너 외에 Dify, Coze, Alibaba Bailian, DeerFlow도 연결할 수 있습니다. (AstrBot)

즉 AstrBot은 “LLM API를 감싼 봇”이 아니라, 도구 사용과 루프 제어를 포함한 에이전트 실행 환경입니다.

4. 플러그인 시스템

README는 1000개 이상 플러그인의 원클릭 설치를 강조하고, 개발 문서는 Star 클래스를 상속해 플러그인을 작성하는 방식을 설명합니다. 핸들러는 데코레이터로 등록하며, 이벤트 객체를 통해 발신자·메시지 정보에 접근하고 응답을 생성합니다. (GitHub)

이 구조의 장점은 기능 확장을 애플리케이션 재배포 없이도 할 수 있다는 점입니다. 예를 들어 사내용으로는 “휴가 정책 조회”, 커뮤니티용으로는 “공지 요약”, 개인용으로는 “일정 관리” 같은 플러그인을 따로 붙일 수 있습니다. 즉 AstrBot의 확장성은 단순 설정 수준이 아니라 코드 확장 가능한 런타임에 가깝습니다. (AstrBot)

5. 지식베이스와 RAG

문서에 따르면 AstrBot은 다중 지식베이스를 지원하고, 임베딩 모델과 선택적 reranker를 설정할 수 있으며, 한 번에 최대 10개 파일 업로드, 파일당 최대 128MB를 지원합니다. 대화 중 특정 지식베이스를 지정해 사용할 수 있다는 점도 눈에 띕니다. (AstrBot)

즉 “문서를 그냥 업로드해서 답변하게 한다” 수준을 넘어서, 프로필별·시나리오별 지식 분리가 가능합니다. 고객지원 봇, 내부 위키 봇, 제품 메뉴얼 봇을 각각 따로 운영하기 쉬운 구조입니다. (AstrBot)

6. Agent Sandbox

README는 AstrBot의 샌드박스를 “코드 실행, 셸 호출, 세션 단위 리소스 재사용을 위한 격리되고 안전한 실행 환경”으로 소개합니다. 이건 에이전트가 실제 작업을 수행하게 만들 때 매우 중요합니다. (GitHub)

LLM에게 “생각만 하라”가 아니라 “파일을 읽고, 코드를 실행하고, 결과를 관찰하라”를 시키려면 안전한 실행 경계가 필요합니다. AstrBot은 이 부분까지 플랫폼에 포함시키려는 방향을 취합니다. 다시 말해, 에이전트의 행동권한을 운영 가능한 형태로 제공하려는 시도입니다. (GitHub)

7. WebUI, ChatUI, HTTP API

AstrBot은 시각적 관리 UI를 제공하고, v4.18.0부터는 API Key 기반 HTTP API도 제공합니다. 예를 들어 Authorization: Bearer abk_xxx 또는 X-API-Key 헤더로 접근하며, 채팅 엔드포인트는 username을 요구합니다. (GitHub)

이건 단순히 사람이 메신저에서만 쓰는 봇이 아니라, 다른 시스템과도 연결될 수 있는 뜻입니다. 즉 AstrBot은 운영용 콘솔 + 대화형 UI + 프로그래밍 API를 함께 가진 플랫폼입니다. (AstrBot)

---

프로젝트 구조를 어떻게 이해하면 좋을까

저장소 루트를 보면 astrbot, dashboard, docs, k8s, samples, scripts, tests, openapi.json, compose.yml 등이 보입니다. 이 구성만 봐도 코어 런타임, 관리 대시보드, 배포 스택, API 정의, 샘플과 테스트가 분리된 전형적인 플랫폼형 저장소입니다. (GitHub)

이를 개발자 관점에서 단순화하면 아래처럼 볼 수 있습니다.

이 다이어그램은 공식 문서의 이벤트 버스·파이프라인 아키텍처, Agent Runner 분리 설명, 저장소 구조를 바탕으로 재구성한 단순화 모델입니다. 실제 내부 구현은 더 복잡하겠지만, AstrBot을 이해할 때는 이 정도 레이어로 보는 것이 가장 실용적입니다. (AstrBot)

---

개발자에게 중요한 설계 포인트

Chat Provider와 Agent Runner를 분리했다

이건 정말 좋은 설계 판단입니다. 많은 프로젝트가 “모델 호출”과 “에이전트 루프”를 섞어버려서, 단순 채팅도 에이전트처럼 무거워지고, 반대로 복잡한 작업은 확장성이 떨어집니다. AstrBot은 이 둘을 분리해 각각의 책임을 명확히 했습니다. (AstrBot)

이벤트 기반 확장이 가능하다

플러그인 문서를 보면 메시지 이벤트 중심으로 핸들러를 붙이는 구조입니다. 메신저 플랫폼은 본질적으로 이벤트 기반이므로, 이 방식은 채널 연동과 궁합이 좋습니다. 새 기능을 “라우터 하나 더 만들기”가 아니라 “이벤트에 반응하는 확장 모듈 추가”로 설계한 셈입니다. (AstrBot)

운영까지 고려한 제품형 오픈소스다

compose.yml, Docker 배포 문서, Kubernetes 문서, WebUI, Desktop 배포 옵션, HTTP API를 함께 제공하는 걸 보면, 이 프로젝트는 라이브러리보다는 즉시 운영 가능한 애플리케이션 플랫폼에 가깝습니다. (GitHub)

---

빠르게 시작하는 방법

README가 가장 빠른 방법으로 제시하는 건 uv 기반 원클릭 설치입니다. 공식 예시는 아래와 같습니다. (GitHub)

uv tool install astrbot
astrbot init
astrbot

좀 더 운영 환경답게 쓰려면 Docker / Docker Compose 배포가 권장됩니다. 공식 문서도 컨테이너 사용자가 더 안정적이고 production-ready한 방식으로 배포할 수 있다고 안내합니다. (GitHub)

---

플러그인 개발 예시

AstrBot의 플러그인은 Star 클래스를 상속하고, @filter.command 데코레이터로 명령을 등록하는 방식입니다. 공식 최소 예제를 보면 /helloworld 같은 명령을 매우 짧은 코드로 만들 수 있습니다. (AstrBot)

아래는 문서의 구조를 이해하기 쉽게 다시 정리한 예시입니다.

from astrbot.api.event import filter, AstrMessageEvent
from astrbot.api.star import Context, Star
from astrbot.api import logger

class MyPlugin(Star):
    def __init__(self, context: Context):
        super().__init__(context)

    @filter.command("helloworld")
    async def helloworld(self, event: AstrMessageEvent):
        """간단한 인사 명령"""
        user_name = event.get_sender_name()
        logger.info("Hello world command triggered!")
        yield event.plain_result(f"Hello, {user_name}!")

    async def terminate(self):
        """플러그인 비활성화/삭제 시 정리 작업"""
        pass

이 예제에서 중요한 건 세 가지입니다.

첫째, 플러그인 진입점이 비교적 단순합니다.
둘째, 메시지 이벤트 객체를 통해 플랫폼 공통 정보에 접근합니다.
셋째, 응답 역시 AstrBot이 제공하는 결과 객체를 통해 표준화됩니다. (AstrBot)

즉 AstrBot은 개발자에게 “메신저별 API를 직접 다루지 말고, 플랫폼 공통 추상화 위에서 기능을 작성하라”는 방향을 제시합니다.

---

어떤 경우에 특히 잘 맞을까

1. 사내 업무용 AI 비서

Slack, WeCom, Feishu 같은 협업 메신저 안에서 문서 검색, 규정 조회, 워크플로 자동화를 붙이고 싶을 때 잘 맞습니다. 지식베이스, 플러그인, Agent Runner 구조가 이 시나리오와 잘 맞물립니다. (GitHub)

2. 커뮤니티/운영 자동화 봇

Discord, Telegram 등에서 FAQ 응답, 공지 생성, 링크 요약, 검색 보조, 이미지 응답 같은 기능을 붙이기 쉽습니다. 멀티채널과 플러그인 구조가 강점입니다. (GitHub)

3. 로컬 또는 자가호스팅 중심 AI 플랫폼

Ollama, LM Studio 같은 로컬 모델 제공자도 지원하므로, 퍼블릭 API 의존도를 낮추고 자체 운영 환경으로 가져가기 좋습니다. Docker, Kubernetes 문서가 있는 것도 같은 맥락입니다. (GitHub)

---

도입 전에 알아둘 점

AstrBot은 분명 강력하지만, 그만큼 “가벼운 챗봇 스크립트”는 아닙니다.

메신저 연동, 모델 제공자, 에이전트 러너, 플러그인, 지식베이스, UI, 샌드박스까지 들어가면 학습 범위가 넓습니다. 즉 작은 개인용 봇 하나만 만들 목적이라면 오히려 과할 수 있습니다. 반대로 여러 채널, 여러 기능, 여러 운영 요구사항을 하나의 시스템으로 묶으려는 팀에게는 훨씬 매력적입니다. 이 프로젝트의 진짜 가치는 기능 하나가 아니라 구성 요소들을 한 플랫폼 안에서 일관되게 운영할 수 있게 해주는 점에 있습니다. (AstrBot)

또 하나 중요한 건 라이선스입니다. AGPL-v3와 EULA를 반드시 검토해야 합니다. 특히 서비스형 배포나 수정 후 재배포를 계획한다면 법무·컴플라이언스 관점 확인이 필요합니다. (AstrBot)

---

총평

AstrBot은 “메신저 챗봇 프레임워크”라고만 부르기엔 범위가 넓습니다. 실제로는 다음을 모두 담고 있습니다.

• 멀티 메신저 게이트웨이
• 멀티 모델 연동 계층
• Agent Runner
• 플러그인 런타임
• 지식베이스/RAG
• 샌드박스 실행
• WebUI/ChatUI/HTTP API
• Docker/K8s 기반 운영 배포