Frameworks

AstrBot: An Open-Source Framework Packing LLM Agents into WeChat, QQ, and Feishu

One bot, six IM platforms, multiple LLM providers, and a plugin system — a breakdown of AstrBot's multi-platform adapter design and Agent architecture.

Font size

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:

  1. 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.
  2. 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.
  3. 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 @register decorator handles declarative registration. Drop the plugin into data/plugins/ and it hot-reloads — no bot restart required.
  • event.context.call_llm() is the unified entry point for LLM calls. The provider parameter 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.py
  • discord.py
  • slack.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/astrbot and 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-bot is 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

Source: https://github.com/AstrBotDevs/AstrBot