Build Your Own QQ Chatbot with Napcat & AstrBot!

1. Create the Project Directory#

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

1
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:

1
version: "3.8"
2

3
services:
4
  astrbot:
5
    image: soulter/astrbot:latest
6
    container_name: astrbot
7
    ports:
8
      - "6185:6185"
9
    volumes:
10
      - ./data:/AstrBot/data
11
      - ./astra_db:/AstrBot/astra_db
12
    restart: always
13
    networks:
14
      - astrbot-net
15

16
  napcat:
17
    image: mlikiowa/napcat-docker:latest
18
    container_name: napcat
19
    ports:
20
      - "6099:6099"
21
      - "6195:6195"
22
      - "6199:6199"
23
    environment:
24
      - NAPCAT_UID=0
25
      - NAPCAT_GID=0
26
      - WS_ENABLE=true
27
      - WS_URL=ws://astrbot:6199/ws
28
    volumes:
29
      - ./napcat/config:/usr/src/app/napcat/config
30
      - ./napcat/QQ:/root/.config/QQ
31
    restart: always
32
    networks:
33
      - astrbot-net
34

35
networks:
36
  astrbot-net:
37
    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:

1
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.

1. Get the WebUI Token#

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

1
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.

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.

1. Docker image pull is too slow?#

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

1
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:

1
docker compose pull
2
docker compose down
3
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.