How to Build a Chatbot with AstrBot: Complete Getting Started Guide

Mar 3, 2026

Purpose

This post demonstrates how to build a multi-platform chatbot using AstrBot, from installation to plugin development. I’ll cover the complete setup process including LLM provider configuration and platform integration.

Why AstrBot?

I needed a chatbot framework that could work across multiple messaging platforms: QQ for Chinese users, Telegram for international users, and potentially WeChat Work for enterprise scenarios. Most frameworks lock you into a single platform.

AstrBot caught my attention because:

Multi-platform support: QQ, Telegram, WeChat Work, Feishu, DingTalk, Slack, Discord
Plugin system: Over 1000 community plugins available
LLM integration: Works with OpenAI, DeepSeek, Ollama, Anthropic, and any OpenAI-compatible API
Python-based: Easy to extend with custom plugins

The architecture looks like this:

┌─────────────────────────────────────────────────────────────┐
│                      AstrBot Core                           │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │  Platform   │  │     LLM     │  │   Plugin    │        │
│  │  Adapters   │  │  Providers  │  │   System    │        │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘        │
└─────────┼────────────────┼────────────────┼────────────────┘
          │                │                │
    ┌─────┴─────┐    ┌─────┴─────┐    ┌─────┴─────┐
    │ QQ/Telegram│    │ OpenAI/   │    │  Custom   │
    │  WeChat... │    │ DeepSeek..│    │  Plugins  │
    └───────────┘    └───────────┘    └───────────┘

Prerequisites

Before starting, make sure you have:

Python 3.10 or higher
Basic command-line familiarity
API keys for your chosen LLM provider (OpenAI, DeepSeek, etc.)
Platform-specific credentials (Telegram bot token, QQ adapter, etc.)

Installation

I tried three installation methods. Here’s what worked best.

Method 1: Using uv (Recommended)

The fastest way to get started is with uv, a modern Python package manager:

uv tool install astrbot
astrbot init
astrbot run

The astrbot init command creates a project directory with default configuration. When you run astrbot run, it starts the bot and launches a WebUI.

Method 2: Python Virtual Environment

If you prefer traditional Python setup:

# Clone the repository
git clone https://github.com/Soulter/AstrBot.git
cd AstrBot

# Create virtual environment
python3 -m venv ./venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
python -m pip install -r requirements.txt

# Run AstrBot
python main.py

Method 3: Docker with NapCatQQ

For QQ integration, the Docker approach bundles AstrBot with NapCat (a QQ adapter):

mkdir astrbot && cd astrbot
wget https://raw.githubusercontent.com/NapNeko/NapCat-Docker/main/compose/astrbot.yml
sudo docker compose -f astrbot.yml up -d

I chose the uv method for simplicity. It took about 30 seconds to install and run.

First Run and WebUI

After running astrbot run, I saw this output:

[2026-03-03 14:30:00] [INFO] AstrBot 启动中...
[2026-03-03 14:30:01] [INFO] WebUI 运行在 http://localhost:6185
[2026-03-03 14:30:01] [INFO] 默认管理员账号: admin
[2026-03-03 14:30:01] [INFO] 默认密码: 123456

Opening http://localhost:6185 in my browser showed the WebUI dashboard:

┌────────────────────────────────────────────┐
│  AstrBot Dashboard                         │
├────────────────────────────────────────────┤
│  ┌──────────┐ ┌──────────┐ ┌──────────┐   │
│  │  Config  │ │ Platform │ │   LLM    │   │
│  │          │ │  Setup   │ │ Providers│   │
│  └──────────┘ └──────────┘ └──────────┘   │
│                                            │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐   │
│  │  Plugin  │ │   Log    │ │  System  │   │
│  │  Market  │ │  Viewer  │ │  Status  │   │
│  └──────────┘ └──────────┘ └──────────┘   │
└────────────────────────────────────────────┘

The default credentials are admin / 123456. I recommend changing these immediately in the configuration.

Configuring LLM Providers

AstrBot supports multiple LLM providers through an OpenAI-compatible interface. Here’s how I set up different providers.

OpenAI Configuration

In the WebUI, navigate to “LLM Providers” and add a new provider:

Provider Name: openai
API Base URL: https://api.openai.com/v1
API Key: sk-your-openai-api-key
Model: gpt-4o

The API base URL defaults to OpenAI’s official endpoint. For other providers, you change this URL.

Using DeepSeek

DeepSeek is a cost-effective alternative with strong Chinese language support:

Provider Name: deepseek
API Base URL: https://api.deepseek.com/v1
API Key: your-deepseek-api-key
Model: deepseek-chat

Local LLM with LM Studio or Ollama

For privacy or cost reasons, I tested with local models. LM Studio provides an OpenAI-compatible server:

Provider Name: lm-studio
API Base URL: http://localhost:1234/v1
API Key: lm-studio
Model: local-model

The “API Key” can be any string for local models. The key requirement is the correct base URL.

With Ollama, the setup is similar:

Provider Name: ollama
API Base URL: http://localhost:11434/v1
API Key: ollama
Model: llama3.2

I found that local models work well for basic conversations but struggle with complex reasoning tasks compared to cloud providers.

Platform Integration

After configuring LLM providers, I connected AstrBot to messaging platforms.

Telegram Bot Setup

Creating a Telegram bot is straightforward:

Message @BotFather on Telegram
Send /newbot and follow the prompts
Copy the bot token

In AstrBot’s WebUI, add a Telegram platform:

Platform Type: telegram
Bot Token: 1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
Webhook URL: https://your-domain.com/api/telegram/webhook

The webhook URL requires a publicly accessible HTTPS endpoint. For development, I used ngrok:

ngrok http 6185

This gives a temporary HTTPS URL that forwards to my local AstrBot instance.

QQ Integration with NapCat

QQ requires the NapCat adapter. The Docker installation method includes this by default. For manual setup:

version: '3'
services:
  napcat:
    image: mlikiowa/napcat-docker:latest
    environment:
      - NAPCAT_GID=your-qq-group-id
    volumes:
      - ./napcat-data:/app/napcat/config
    ports:
      - "3000:3000"

  astrbot:
    image: soulter/astrbot:latest
    ports:
      - "6185:6185"
    volumes:
      - ./astrbot-data:/AstrBot/data

NapCat uses the OneBot v11 protocol to communicate with QQ. After starting the containers, scan the QR code with your QQ mobile app to authenticate.

WeChat Work and Feishu

For enterprise platforms, AstrBot uses webhook integrations:

Platform Type: wechat_work
Webhook URL: https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=your-key

Platform Type: feishu
App ID: your-app-id
App Secret: your-app-secret

These platforms require creating bot applications in their respective admin consoles.

Creating Your First Plugin

AstrBot’s plugin system, called “Star,” uses Python decorators for command registration. Here’s a minimal Hello World plugin:

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

@register("helloworld", "your-name", "A simple Hello World plugin", "1.0.0", "https://github.com/your-repo")
class HelloWorldPlugin(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(f"Hello world command triggered by {user_name}")
        yield event.plain_result(f"Hello, {user_name}!")

The key parts:

@register declares the plugin metadata
@filter.command("helloworld") registers the /helloworld command
event.plain_result() sends a text response

To install this plugin, I created a directory structure:

my-plugin/
├── main.py
└── metadata.yaml

Then I placed it in data/plugins/ and restarted AstrBot. The plugin appears in the WebUI’s plugin management section.

Wake Prefixes and Commands

AstrBot uses wake prefixes to trigger bot responses. The default prefix is /. You can configure this in data/cmd_config.json:

{
  "wake_prefix": ["/", "!", "bot "],
  "command_prefix": "/",
  "reply_prefix": "",
  "reply_mention": true
}

With this configuration, users can trigger the bot with /, !, or bot as prefixes. So both /helloworld and bot helloworld work.

Rate Limiting

To prevent abuse, AstrBot includes built-in rate limiting:

{
  "enabled": true,
  "max_requests_per_minute": 10,
  "max_tokens_per_request": 4096,
  "cooldown_seconds": 60
}

I set this to 10 requests per minute per user, which prevents API cost explosions from spam.

Running as a Service

For production deployment, I set up AstrBot as a systemd service:

[Unit]
Description=AstrBot Chatbot Service
After=network.target

[Service]
Type=simple
User=astrbot
WorkingDirectory=/opt/astrbot
ExecStart=/usr/local/bin/astrbot run
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Then I enabled and started the service:

sudo systemctl daemon-reload
sudo systemctl enable astrbot
sudo systemctl start astrbot

This ensures AstrBot restarts automatically after system reboots or crashes.

Troubleshooting Common Issues

WebUI Not Accessible

If the WebUI doesn’t load, check the port binding:

netstat -tlnp | grep 6185

If the port is in use, kill the conflicting process or change AstrBot’s port in the configuration.

LLM Provider Connection Failed

For OpenAI API errors, verify:

API key is valid and has credits
Network can reach the API endpoint (check firewall/proxy)
Model name is correct (e.g., gpt-4o not gpt-4)

For local models, ensure LM Studio or Ollama is running:

# Check LM Studio server
curl http://localhost:1234/v1/models

# Check Ollama
ollama list

QQ Adapter Not Connecting

NapCat requires scanning a QR code on first run. Check the logs for the QR code display:

docker logs napcat-container-name

Summary

In this post, I walked through the complete process of setting up AstrBot: installation via uv, configuring LLM providers like OpenAI and local models, connecting to messaging platforms including Telegram and QQ, and writing a custom plugin. The key point is AstrBot’s plugin-based architecture abstracts away platform differences, letting you focus on bot logic rather than integration details.

The framework handles the complexity of multi-platform deployment through adapters, while the Star plugin system provides a clean Python interface for custom functionality. Whether you need a simple echo bot or a sophisticated AI assistant, AstrBot provides the building blocks.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!