AstrBot Deployment Guide: Building a Multi-Platform AI Bot for QQ, Telegram, and Feishu

Build an AI chatbot that supports multiple messaging platforms like Telegram, Feishu, and QQ in just 30 minutes.

Target Audience: Backend developers with 1-3 years of experience looking to quickly build their own AI chatbots.

Core Dependencies: Python 3.10+, uv package manager, messaging platform developer accounts.

Takeaways: Master the full deployment process of AstrBot and build multi-platform AI assistants.

---

1. Project Introduction and Architecture

AstrBot is an open-source AI Agent chatbot platform developed in Python that supports integration with various instant messaging software. Its design philosophy is that "companionship and capability should not be mutually exclusive"—it aims to provide emotional companionship while reliably performing various tasks.

1.1 Supported Messaging Platforms

1.2 Core Features

• Multi-Model Support: OpenAI, Claude, Gemini, DeepSeek, etc.
• Agent Capabilities: Supports the MCP protocol to call external tools.
• Persona Configuration: Built-in Persona system to customize AI personalities.
• Knowledge Base: Supports RAG; import documents to give the AI professional knowledge.
• WebUI: A visual console for more intuitive configuration.

---

2. Environment Preparation

2.1 Installing uv

AstrBot recommends using uv for installation. It is a next-generation Python package manager that is over 10x faster than pip.

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
irm https://astral.sh/uv/install.ps1 | iex

After installation, verify it:

uv --version
# Output similar to: uv 0.5.0

2.2 Installing AstrBot

Install with a single command:

uv tool install astrbot

2.3 Initializing the Project

astrbot init

This command creates the project directory structure:

.
├── data/              # Data directory
│   ├── cmd_config.json  # Main configuration file
│   └── config/         # Multi-config directory
├── logs/              # Log directory
└── plugins/           # Plugins directory

Enter the project directory:

cd astrbot

---

3. Configuring Messaging Platform Adapters

AstrBot supports multiple messaging platforms. Here we demonstrate configuration methods for three mainstream platforms.

3.1 Telegram Bot Configuration

Telegram is the simplest to configure, requiring only a Bot Token.

3.1.1 Creating a Bot

1. Search for @BotFather on Telegram.
2. Send /newbot to create a new bot.
3. Follow the prompts to set the name and username.
4. Copy the Bot Token (e.g., 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11).

3.1.2 Configuration File

Open data/cmd_config.json and add the following to the platform array:

{
    "platform": [
        {
            "type": "telegram",
            "enable": true,
            "token": "YOUR_BOT_TOKEN"
        }
    ]
}

3.1.3 Getting the Chat ID

After starting the bot, send a message to it, then visit:

https://api.telegram.org/bot<TOKEN>/getUpdates

Find "chat":{"id":123456789} in the returned JSON; this is your Chat ID.

3.2 Feishu (Lark) Bot Configuration

Feishu is commonly used in corporate environments. The configuration is slightly more complex.

3.2.1 Creating the App

1. Visit the Feishu Open Platform.
2. Create a corporate application.
3. Add the following permissions in "Permission Management":
   • im:chat:readonly - Read group info
   • im:message:send_as_bot - Send messages as a bot
   • im:message:receive - Receive messages

3.2.2 Creating the Bot

1. Add the "Bot" capability to the application.
2. Copy the App ID and App Secret.

3.2.3 Configuration File

{
    "platform": [
        {
            "type": "lark",
            "enable": true,
            "app_id": "YOUR_APP_ID",
            "app_secret": "YOUR_APP_SECRET",
            "verification_token": "YOUR_VERIFICATION_TOKEN"
        }
    ]
}

3.3 QQ Bot Configuration (OneBot)

QQ bots require use with NapCat or LLOneBot.

3.3.1 Installing NapCat

NapCat is recommended as the QQ client:

# Method 1: Docker Deployment (Recommended)
docker pull napneko/napcat:latest

# Method 2: Direct Installation
# Refer to https://napneko.github.io/

3.3.2 Configuration File

{
    "platform": [
        {
            "type": "onebot",
            "enable": true,
            "ws_host": "127.0.0.1",
            "ws_port": 3001,
            "http_port": 3000
        }
    ]
}

3.3.3 Starting NapCat

docker run -d \
  --name napcat \
  -p 3000:3000 \
  -p 3001:3001 \
  -v ./data:/app/data \
  napneko/napcat:latest

---

4. Configuring Large Language Models (LLM)

Without an LLM, a bot is just a relay. This step is crucial.

4.1 Using Defapi (Recommended)

Defapi is an AI model aggregation platform offering prices at roughly half the official rate, with fast access in certain regions.

4.1.1 Registering for Defapi

1. Visit Defapi to register an account.
2. Get your API Key from the console.

4.1.2 Configuration File

Add the provider configuration in cmd_config.json:

{
    "provider": [
        {
            "id": "defapi",
            "type": "openai_chat_completion",
            "model": "claude-sonnet-4-20250514",
            "key": ["YOUR_DEFAPI_API_KEY"],
            "api_base": "https://api.defapi.org/v1",
            "enable": true
        }
    ],
    "provider_settings": {
        "default_provider_id": "defapi",
        "enable": true
    }
}

4.2 Using Official OpenAI

If you have an OpenAI API Key:

{
    "provider": [
        {
            "id": "openai",
            "type": "openai_chat_completion",
            "model": "gpt-4o",
            "key": ["sk-xxx"],
            "api_base": "https://api.openai.com/v1",
            "proxy": "http://127.0.0.1:7890",
            "enable": true
        }
    ]
}

4.3 Using DeepSeek

DeepSeek is highly recommended for its high cost-performance ratio:

{
    "provider": [
        {
            "id": "deepseek",
            "type": "openai_chat_completion",
            "model": "deepseek-chat",
            "key": ["sk-xxx"],
            "api_base": "https://api.deepseek.com/v1",
            "enable": true
        }
    ]
}

---

5. Startup and Verification

5.1 Starting the Service

astrbot

You should see output similar to:

INFO - AstrBot starting...
INFO - WebUI: http://localhost:6185
INFO - Platform adapters loaded: telegram, lark, onebot
INFO - Provider loaded: defapi
INFO - AstrBot started successfully!

5.2 Accessing the Console

Open your browser and visit http://localhost:6185. Default credentials:

• Username: astrbot
• Password: astrbot

5.3 Testing the Chat

Send a message to the bot on the respective messaging platform:

Hello! Who are you?

If everything is correct, the bot will reply using the configured LLM.

---

6. Troubleshooting

6.1 Startup Failure

Issue: ModuleNotFoundError: No module named 'astrbot'

Solution:

# Reinstall
uv tool uninstall astrbot
uv tool install astrbot

6.2 Messages Not Received

Issue: Sending a message to the bot results in no response.

Troubleshooting Steps:

1. Check if the platform adapter is enabled:

astrbot -p

1. Check the logs:

tail -f logs/astrbot.log

1. Confirm platform configurations (Tokens/Secrets) are correct.

6.3 Model Call Failure

Issue: Error: API request failed

Troubleshooting Steps:

1. Confirm the API Key is correct.
2. Check network connectivity (proxy may be needed).
3. Verify the model name is correct.
4. Ensure the account has sufficient balance.

6.4 Rate Limiting

Issue: 429 Too Many Requests

Solution: Configure multiple API Keys for load balancing:

{
    "provider": [
        {
            "id": "openai-multi",
            "type": "openai_chat_completion",
            "model": "gpt-4o",
            "key": ["key1", "key2", "key3"],
            "api_base": "https://api.openai.com/v1",
            "enable": true
        }
    ]
}

6.5 Telegram Bot Private Chat Not Working

Issue: Works in groups but no response in private chat.

Solution: You must talk to @BotFather, send /start to activate the bot, then private messages will work.

6.6 Feishu Bot Not Receiving Messages

Issue: Feishu bot is configured correctly but receives nothing.

Solution:

1. Confirm the app is published.
2. Ensure the bot is added to the group chat or private chat is enabled.
3. Check if the public access URL is working correctly.

---

7. Advanced Extensions

7.1 Plugin Development

AstrBot supports plugin extensions. Create plugins/my_plugin/main.py:

from astrbot.api.event import filter, EventMessage

@filter()
async def handle_hello(event: EventMessage):
    if event.message_str == "hello":
        await event.reply("Hello! I'm your AI assistant!")

7.2 Persona Configuration

Create a persona in the "Persona" page of the console and set the system prompt:

You are a friendly AI assistant who likes to answer questions concisely.

7.3 MCP Integration

AstrBot supports the MCP protocol to call external tools. Configure MCP services in the "Skills" page of the console.

7.4 Knowledge Base (RAG)

Create a knowledge base in the console and upload documents to give the AI domain-specific knowledge.

---

Further Reading

• AstrBot Official Documentation
• AstrBot GitHub
• NapCat QQ Deployment Guide
• Feishu Open Platform Documentation
• OneBot Protocol Specification