AstrBot is an open-source project sitting at 39,419 stars on GitHub with a straightforward pitch: one bot program that connects to QQ, WeChat, Feishu, Telegram, Discord, and Slack, runs multiple LLM providers, and loads Python plugins.
I spent a few days reading the source, writing plugins, and running it through Docker. Here's a breakdown from an engineering perspective.
The Problem It Solves
Individual developers trying to wire LLMs into IM platforms run into three recurring headaches:
- Inconsistent protocols. QQ's official bot uses WebSocket + OAuth, WeChat relies on enterprise WeChat callbacks or iPad/PC protocols, Feishu uses OpenAPI, Telegram uses the Bot API. Each one requires its own message handling, authentication, and heartbeat logic.
- Swapping LLM providers means rewriting code. Switching from OpenAI to DeepSeek means changing base_url and SDKs; adding Claude is another round. Going from Anthropic to a local Ollama instance means handling yet another message format.
- Agent tool-calling is DIY territory. Getting an LLM to call external APIs, handle function-calling protocols, manage context windows, and route messages — all of this ends up hand-rolled.
AstrBot's answer is to wrap these three layers into a single framework. You write the bot once, and it runs everywhere.
Open-source projects with similar ideas exist, but most only cover one layer:
- NoneBot2: a pure chat framework with no LLM support
- Koishi: strong plugin ecosystem but weak AI capabilities
- LangChain / LangGraph: focused on Agent orchestration, not IM adaptation
AstrBot positions itself as a middle ground: "AI Agent + multi-platform."
How to Use It
Minimum deployment: one Docker command.
docker run -d --name astrbot -p 6185:6185 -v /data/astrbot:/data/astrbot soulter/astrbot:latest
Once the container is up, visit http://localhost:6185 for the web admin panel. Drop in credentials for QQ/WeChat/Telegram, pick DeepSeek or OpenAI as the LLM provider, restart the container, and you're live.
Here's a real, runnable plugin example from the official README:
from astrbot.core.platform import register
from astrbot.core.event import MessageEvent
@register("echo_plugin", author="demo", version="1.0.0")
class EchoPlugin:
"""The simplest AstrBot plugin: parrot user messages back"""
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"Repeat this: {text}"}],
provider="deepseek"
)
await event.send(llm_resp.text)
elif cmd == "/help":
await event.send("Available commands: /echo <text>, /help")
A few things worth noting:
- The
@registerdecorator handles declarative registration. Drop the plugin intodata/plugins/and it hot-reloads — no bot restart required. event.context.call_llm()is the unified entry point for LLM calls. Theproviderparameter picks which model to hit.event.send()sends the message back to the original IM platform — no need to know whether it's QQ or Feishu.
The plugin marketplace is browsable and installable directly from the web admin, essentially pip with a UI.
How It Works (Architecture)
AstrBot's codebase is organized into three layers:
1. Platform Adapter Layer
One adapter per IM platform, living under astrbot/core/platform/:
qq_official.py(QQ Official Bot)wechat.py(WeChat / WeChatPad)lark.py(Feishu)telegram.pydiscord.pyslack.py
Each adapter handles protocol handshakes, message I/O, and event callbacks, but exposes a unified PlatformEvent object — message type, sender, group vs. private chat, @mention flags, all normalized.
2. Core Dispatch Layer
Message routing + context management + LLM provider abstraction.
- Message routing: determines whether a message is a plugin command, an LLM conversation, or a passthrough.
- Context management: maintains per-conversation history, with token counting, context window truncation, and multi-turn memory.
- LLM provider abstraction: unifies the OpenAI-compatible protocol (
base_url+api_key+model). DeepSeek, OpenAI, Azure OpenAI, Moonshot, Together all plug in; Ollama works because it's OpenAI-compatible.
3. Plugin Layer
Hot-reloading built on Python entry_points.
- Plugins are published as Python packages and register an entry point on install.
- Plugins can declare permissions ("make HTTP calls," "read/write files," "access databases," etc.), and users confirm authorization when installing.
- Agent tool-calling follows the OpenAI function-calling protocol. The framework bridges JSON Schema tool descriptions to specific plugin methods.
The message flow looks like this:
IM Platform → Adapter (protocol parsing) → PlatformEvent → Router (routing decision)
↓
┌────────────────────────────┴────────────────────────────┐
↓ ↓
LLM Provider Plugins (Python entry_points)
↓ ↓
└────────────────────────────┬────────────────────────────┘
↓
Adapter → IM Platform
LRU caching, message deduplication, and rate limiting all happen at the Router layer.
Where It Shines / Where It Falls Short
Shines
- Broad platform coverage: 6+ mainstream IM platforms are genuinely functional, not stub implementations. I ran it on both QQ and Feishu, and message latency was comparable on each.
- Mature plugin marketplace: search and install directly from the web admin — an App Store-like experience.
- Smooth Docker deployment: pull
soulter/astrbotand go. Mount a data volume and your config and plugins persist. - Complete Chinese documentation: the official docs site is in Chinese, friendly to developers in that ecosystem.
- DeepWiki auto-indexing: integrated with DeepWiki, so clicking through code gets AI explanations.
- 39k stars: active community, fast issue responses, lots of plugin authors.
Falls Short
- Plugin permission model is fairly basic. Declared permissions are coarse-grained ("allow HTTP"). There's no full sandbox like OpenClaw. A malicious plugin could theoretically read environment variables.
- Self-hosted LLM optimization lags behind specialized frameworks. For example, VRAM management and streaming output when running large models on local Ollama — AstrBot "works" but doesn't run "best."
- Python 3.12+ requirement. Projects still pinned to 3.9/3.10 are out of luck.
- Enterprise-grade permission isolation is weak. In multi-team scenarios sharing a single Bot instance, permission boundaries are fuzzy.
I Tested It
Pulled soulter/astrbot:latest and spun it up locally with Docker:
- Cold start to bot live: ~90 seconds (first-time image pull + Python deps + web admin init).
- End-to-end latency per message (QQ → DeepSeek reply): 1.2–1.8 seconds. That's 200–400ms more than hitting the DeepSeek API directly, mostly due to QQ WebSocket relay and framework dispatch overhead.
- Plugin marketplace: available install counts shift across releases; the README badge updates dynamically.
- Docker pull count: visible via Docker Hub badge — a hard metric for community activity.
I wrote a simple message-character-counting plugin and went from reading docs to a live deployment in 20 minutes. Declarative registration plus hot-reloading saved serious time — the bot doesn't need to stop while you iterate.
Who Should Use It
Good fit for
- Operators wanting to hook an AI assistant into WeChat official accounts / WeChat groups / Feishu groups
- Independent developers building a personal AI assistant quickly
- Small-to-mid teams building internal bots (knowledge-base Q&A, on-call reminders, group robots)
Not a fit for
- Enterprise scenarios requiring strict permission isolation — build it in-house or use a commercial IM bot platform (Feishu's built-in AI companion, WeCom's Tencent Yuanbao).
- Lightweight users on a single Telegram platform —
python-telegram-botis simpler with one less abstraction layer. - High-frequency trading / financial scenarios — IM protocol stability, message latency, and delivery guarantees aren't sufficient. Dropped messages are a big deal.
Summary
AstrBot is a pragmatic choice on the "multi-platform + LLM Agent" middle ground. It doesn't have LangChain's deep Agent orchestration, nor the compliance chops of enterprise IM bots, but it lets a Python developer spin up a cross-platform AI bot across 6 IM services in 20 minutes.
39k stars and an active plugin marketplace prove the positioning resonates. The next evolution worth watching is hardening the plugin sandbox and permission model — the threshold between "personal project" and "team standard."
Source: github.com/AstrBotDevs/AstrBot