Using ntqq Napcat with NoneBot

2026-05-20 ยท 17 min read

This article details the deployment process of a QQ bot based on Napcat and NoneBot.

The article is translated using AI.

Reference

NoneBot Official Documentation

https://nonebot.dev/https://github.com/nonebot/nonebot2

Napcat Official Documentation

https://napneko.pages.dev/https://github.com/NapNeko/NapCatQQ

Napcat Deployment

For installation on Linux Docker or macOS, please refer to the official documentation.

Manual Installation on Windows

  1. Go to the NapCatQQ release page
  2. Download NapCat.Shell.zip and extract it.
  3. After installation, double-click launcher.bat in the directory to start. For Windows 10, use launcher-win10.bat.
Note: For quick login, pass the QQ number as the second parameter.

Win11: launcher.bat 123456 Win10: launcher-win10.bat 123456
Note the ntqq version requirements indicated in the Releases.

One-click Script for Linux

curl -o napcat.sh https://nclatest.znin.net/NapNeko/NapCat-Installer/main/script/install.sh && sudo bash napcat.sh

whiptail must be installed, otherwise the script will exit automatically. It can be installed via apt/yum.

Alternatively, add the following parameters to the original installation command:

  1. --docker [y/n]: --docker y for Docker installation, otherwise shell installation.
  2. --qq "123456789": Pass the QQ number for Docker installation.
  3. --mode [ws|reverse_ws|reverse_http]: Pass the running mode for Docker installation.
  4. --confirm: Confirm execution for Docker installation.
  5. --proxy [0|1|2|3|4|5|6]: Pass proxy. 0 for no proxy, 1 for the first built-in proxy. Custom proxies not supported. Docker installation supports 0-7, shell installation supports 0-5.
  6. --dlc [y/n]: Whether to install DLC during shell installation.
  7. --cli [y/n]: Whether to install CLI during shell installation.
  8. --force: Force reinstall for shell installation.

Repository: NapCat.installer

Deployment on Android Termux

curl -o napcat.termux.sh https://nclatest.znin.net/NapNeko/NapCat-Installer/main/script/install.termux.sh && bash napcat.termux.sh

Repository: NapCat.installer

p.s. A proot container named napcat will be automatically created.

You can enter the container using proot-distro login napcat.

Inside the container, run xvfb-run -a qq --no-sandbox to start Napcat. Add the parameter -q QQ_number for automatic login.

For multitasking, use screen. Parameter -r id to enter a task, -s id to create a task, and ctrl + A + D to exit the task (runs in background, not terminated).

The deployment script above has already configured everything. Use the following command to start Napcat from Termux with one click (Termux -> screen -> proot container -> Napcat):

screen -dmS napcat bash -c 'proot-distro sh napcat -- bash -c "xvfb-run -a qq --no-sandbox -q 3336701131"'

Modify OneBot Configuration

After Napcat starts and logs in successfully, go to the config folder in the Napcat root directory. You will find a JSON file named like onebot11_12345678.json (ending with the QQ number).

{
"http": {
// Whether to enable HTTP service, true to enable, false to disable
"enable": false,
// IP address for HTTP service to listen on, empty to listen on all addresses
"host": "",
// HTTP service port
"port": 3000,
// HTTP report secret key, can be empty
"secret": "",
// Whether to enable HTTP heartbeat
"enableHeart": false,
// Whether to enable HTTP report service
"enablePost": false,
// HTTP report URLs, e.g., ["http://127.0.0.1:8080/onebot/v11/http"]
"postUrls": []
},
"ws": {
// Whether to enable forward WebSocket service
"enable": false,
// IP address for forward WebSocket service to listen on, empty to listen on all addresses
"host": "",
// Forward WebSocket service port
// When port is the same as HTTP service port, host must also be the same, otherwise startup may fail
"port": 3001
},
"reverseWs": {
// Whether to enable reverse WebSocket service
"enable": false,
// Reverse WebSocket URLs, e.g., ["ws://127.0.0.1:8080/onebot/v11/ws"]
"urls": []
},
"GroupLocalTime": {
"Record": false,// Whether to enable local group chat time recording
"RecordList": []// Enable all groups ["-1"]   Single group ["11111"]   Multiple groups ["1","2","3"]
},
// Whether to enable debug mode. When enabled, reported messages will carry a raw field with the original message content.
"debug": false,
// WebSocket heartbeat interval in milliseconds
"heartInterval": 30000,
// Message report format: array for message segments, string for CQ code string
"messagePostFormat": "array",
// Whether to convert local files to URLs. If URL cannot be obtained, use base64 field to return file content.
"enableLocalFile2Url": true,
// Music sign URL, used to handle music-related requests
"musicSignUrl": "",
// Whether to report self-sent messages
"reportSelfMessage": false,
// access_token, can be empty
"token": ""
}
# Unless there are special requirements, the following configuration is generally sufficient:
"ws": {
"enable": true,
"host": "127.0.0.1",
"port": 3001
},
"reverseWs": {
"enable": true,
"urls": ["ws://127.0.0.1:8080/onebot/v11/ws/"]
},

NoneBot Deployment

NoneBot only supports Python 3.9 or above.

For installing Python 3 in Termux, refer to this article.

Install the Scaffold

Ensure you have Python 3.9 or above installed, then run the following command in the terminal:

  1. Install pipx
    python -m pip install --user pipx
    python -m pipx ensurepath
  2. If the output of this step contains "open a new terminal" or "re-login", please close the current terminal and open a new one.
  3. Install the Scaffold
    pipx install nb-cli

After installation, you can use the nb command in the terminal to use the scaffold. If the command is not found (e.g., "Command not found"), please refer to the pipx documentation to check your environment variables.

Create a Project

Use the scaffold to create a project:

nb create

This command will start the project creation process. You will see some prompts:

  1. Project Template
    [?] Select a template to use: bootstrap (Beginner or User)
  2. Here we choose the bootstrap template, which is a simple project template that can install store plugins. If you need to write your own plugins, please choose the simple template.
  3. Project Name
    [?] Project name: awesome-bot
  4. Here we use awesome-bot as an example project name. You can name it according to your needs.
  5. Other Options: Note that for multi-select options, use space to select or deselect, and Enter to confirm.
    [?] Which drivers would you like to use? FastAPI (FastAPI Driver)
    [?] Which adapters would you like to use? OneBot v11 (OneBot v11 Protocol)
    [?] Install dependencies now? (Y/n) Yes
    [?] Create virtual environment? (Y/n) Yes
  6. Here we chose to create a virtual environment. nb-cli will automatically use this virtual environment in subsequent operations. If you do not need automatic virtual environment creation or have already created another virtual environment, nb-cli will install dependencies into the currently activated Python virtual environment.
  7. Select Built-in Plugins
    [?] Which built-in plugins would you like to use? echo
  8. Here we select the echo plugin as an example. It is a simple echo plugin that can be used to test if your bot is running correctly.

Run the Project

After the project is created, you can run it in the project directory using the following command:

nb run

You should now have your first NoneBot project running!

Final Steps

After both are deployed, start them simultaneously. If you see the following log on the NoneBot side, the connection is successful.

11-06 15:34:31 [INFO] uvicorn | ('127.0.0.1', 3814) - "WebSocket /onebot/v11/ws/" [accepted]
11-06 15:34:31 [INFO] nonebot | OneBot V11 | Bot 3336701131 connected
11-06 15:34:31 [INFO] websockets | connection open

At this point, try mentioning the bot in a group and reply with @bot /echo hello. If the bot replies, the deployment is complete.

Use ctrl + C to exit NoneBot, then enter nb plugin to browse the NoneBot plugin library and enrich your bot!