## WARNING!!!

Using a personal QQ account to run a bot is technically against Tencent's Terms of Service and may result in your account being flagged or restricted. Do not use this for any illegal purposes! If your account gets flagged, we take no responsibility!

---

## Introduction

AI large language models have been evolving rapidly, and QQ bots are becoming increasingly common. I've wanted to build my own QQ bot for a while, but most solutions are quite involved – setting up environments, configuring protocols, and often spending a lot of time without even getting it to run properly.

Then I came across the **AstrBot + NapCat** combination – it's surprisingly easy to set up. AstrBot handles the "brain" (integrating AI models and managing various features), while NapCat handles sending and receiving QQ messages. The two communicate via the OneBot protocol, and the entire setup can be deployed with a single Docker command.

---

## What are AstrBot and NapCat?

In simple terms, **AstrBot** is a chatbot framework that supports various AI large language models (DeepSeek, OpenAI, Gemini, etc.), complete with a plugin system and a web management panel – it's very feature-rich.

**NapCat** is a protocol adapter for QQ. It simulates QQ client login and message handling, acting as a bridge that connects QQ to AstrBot.

The flow looks something like this:

```
You send a QQ message → NapCat receives it → AstrBot processes it → Calls the AI model → AstrBot generates a reply → NapCat sends it back to QQ
```

---

## Prerequisites

Before we start, you'll need the following:

1. **A Linux server** (at least 2 vCPU and 2 GB RAM recommended, Ubuntu 20.04+ or CentOS 7+)
2. **A QQ account** (to be used as the bot – an older, regularly active account is preferred, as new accounts are more likely to get flagged)
3. **An LLM API Key** (for DeepSeek, you can sign up at [platform.deepseek.com](https://platform.deepseek.com) – they give free credits upon registration)
4. **Docker and Docker Compose installed**

---

## Deployment

### 1. Create the Project Directory

SSH into your server and create a directory for the configuration files:

```bash
mkdir -p /opt/astrbot && cd /opt/astrbot
```

### 2. Write docker-compose.yml

Create a `docker-compose.yml` file in this directory with the following content:

```yaml
version: "3.8"

services:
  astrbot:
    image: soulter/astrbot:latest
    container_name: astrbot
    ports:
      - "6185:6185"
    volumes:
      - ./data:/AstrBot/data
      - ./astra_db:/AstrBot/astra_db
    restart: always
    networks:
      - astrbot-net

  napcat:
    image: mlikiowa/napcat-docker:latest
    container_name: napcat
    ports:
      - "6099:6099"
      - "6195:6195"
      - "6199:6199"
    environment:
      - NAPCAT_UID=0
      - NAPCAT_GID=0
      - WS_ENABLE=true
      - WS_URL=ws://astrbot:6199/ws
    volumes:
      - ./napcat/config:/usr/src/app/napcat/config
      - ./napcat/QQ:/root/.config/QQ
    restart: always
    networks:
      - astrbot-net

networks:
  astrbot-net:
    driver: bridge
```

A few important notes about this configuration:

- `WS_ENABLE=true` enables NapCat's WebSocket client mode
- `WS_URL=ws://astrbot:6199/ws` is the key – it tells NapCat to connect to AstrBot's WebSocket service. Make sure to include `/ws` at the end, otherwise the connection will fail
- Both containers communicate via the custom `astrbot-net` network, so you don't need to worry about IP addresses

If pulling Docker images is particularly slow for you, you can add a domestic mirror prefix to the image name, such as `m.daocloud.io/docker.io/soulter/astrbot:latest`.

### 3. Start the Containers

Run the following command in the directory containing `docker-compose.yml`:

```bash
docker compose up -d
```

Wait about a minute, then check the status with `docker compose ps`. Both containers should show `Up` – that means they're running successfully.

---

## Configuring NapCat (Logging into QQ)

### 1. Get the WebUI Token

Run the following command to view NapCat's startup logs:

```bash
docker logs napcat
```

Look for a line containing something like `NapCat WebUI Login Token: xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` and note down that Token.

### 2. Log into the WebUI

In your browser, visit `http://your_server_ip:6099` and enter the Token you just retrieved to log in.

Then follow the NapCat WebUI prompts to scan the QR code with your phone's QQ app to log in to your bot's QQ account.

---

## Configuring AstrBot

### 1. Access the Admin Dashboard

Open your browser and go to `http://your_server_ip:6185`. The default username and password are both `astrbot`. You'll be prompted to change the password on first login – after that, log back in.

### 2. Connect an AI Model

In the left sidebar, navigate to **"Model Providers"** → **"Chat"**, then click **"Add Provider"**:

- **Provider**: Select `DeepSeek/OpenAI API Compatible`
- **API Address**: `https://api.deepseek.com/v1`
- **API Key**: Paste the Key you obtained from DeepSeek
- **Model**: Enter `deepseek-chat`

### 3. Create a Bot Instance

In the left sidebar, go to **"Bots"** → **"Create Bot"**:

- **Platform Type**: Select `QQ Personal Account (OneBot v11)`
- **WebSocket Address**: `0.0.0.0:6199`
- **Reverse WebSocket Token**: Leave blank
- **Enabled**: Toggle on

After saving, restart AstrBot and watch the logs. If you see a message like `[Info] Connected to OneBot v11 client`, that means AstrBot and NapCat have successfully established a connection.

---

## Verify It Works

Once all steps above are completed, send a message to your bot from another QQ account to test it. Under normal circumstances, the bot will call the DeepSeek API to generate a response.

You can also customise the bot's response style by configuring the System Prompt (persona) in the AstrBot admin dashboard.

---

## Common Issues

### 1. Docker image pull is too slow?

Use a domestic mirror by prefixing the image name with `m.daocloud.io/docker.io/`, for example:

```yaml
image: m.daocloud.io/docker.io/soulter/astrbot:latest
```

### 2. WebSocket connection fails?

Check these points:

- Does `WS_URL` end with `/ws`?
- Are both containers on the same Docker network?
- Is port `6199` open in your cloud server's security group?

### 3. QQ account got flagged/restricted?

Tencent's anti‑bot mechanisms are beyond our control. We recommend using an older, regularly active account, avoid frequently restarting containers (which causes repeated logins), and refrain from sending sensitive content.

### 4. How to update?

In the project directory, run:

```bash
docker compose pull
docker compose down
docker compose up -d
```

### 5. How to back up?

Simply archive the `./data`, `./napcat`, and `./astra_db` directories. To restore, extract the backup files back into place and restart the containers.

---

## Summary

With AstrBot + NapCat + Docker, you can go from zero to a fully functional QQ bot in about 10 minutes. And AstrBot offers much more than what's covered here – it also has a plugin system, MCP service extensions, multi‑platform support, and more. Feel free to explore on your own!