Skip to main content

​
Overview

This quickstart guide will help you set up NapCat and send your first message in about 5-10 minutes. We’ll use Framework Mode which is the easiest way to get started.
This guide assumes you have QQ installed on your system. If you don’t have QQ, download it from the official QQ website.

​
Prerequisites

Before you begin, make sure you have:
  • QQ installed (Windows/macOS/Linux)
  • Node.js 18.0.0 or higher
  • A QQ account for your bot
  • Basic command line knowledge

​
Step 1: Download NapCat

1

Get the latest release

Download the latest version of NapCat from the GitHub Releases page.Choose the appropriate package for your operating system:
  • Windows: NapCat-win-x64.zip
  • macOS: NapCat-darwin-x64.zip
  • Linux: NapCat-linux-x64.zip
2

Extract the archive

Extract the downloaded archive to a location of your choice:
# Example for Linux/macOS
unzip NapCat-linux-x64.zip -d napcat
cd napcat

​
Step 2: Initial Configuration

Create a basic configuration file to get started:
1

Create config directory

mkdir -p config
2

Create OneBot config

Create config/onebot11.json with the following content:
config/onebot11.json
{
  "http": [
    {
      "enable": true,
      "host": "0.0.0.0",
      "port": 3000,
      "secret": "",
      "enableHeart": true,
      "enablePost": false
    }
  ],
  "ws": [
    {
      "enable": false,
      "host": "0.0.0.0",
      "port": 3001
    }
  ],
  "reverseWs": {
    "enable": false,
    "urls": []
  },
  "debug": false,
  "heartInterval": 30000,
  "messagePostFormat": "array",
  "enableLocalFile2Url": true,
  "musicSignUrl": "",
  "reportSelfMessage": false,
  "token": ""
}
This enables an HTTP API server on port 3000.

​
Step 3: Launch NapCat

Double-click napcat.exe or run from command prompt:
napcat.exe
On first launch, NapCat will show you the WebUI URL with a token. Save this URL - you’ll use it to access the management interface.

​
Step 4: Login to QQ

1

Open WebUI

Open the WebUI URL shown in the console output (e.g., http://127.0.0.1:6099/webui/?token=xxxxx)
2

Choose login method

You have three options:
  • QR Code Login (Recommended): Scan QR code with your phone
  • Quick Login: Use saved account if you’ve logged in before
  • Password Login: Login with account and password
3

Complete login

Follow the on-screen instructions to complete the login process.Once logged in, you’ll see “登录成功” (Login Successful) and your account information.

​
Step 5: Verify Connection

Test that your bot is working by calling the API:
cURL
curl http://localhost:3000/get_login_info
You should receive a response like: 
{
  "status": "ok",
  "retcode": 0,
  "data": {
    "user_id": 123456789,
    "nickname": "YourBotName"
  },
  "message": "",
  "wording": "",
  "echo": ""
}
If you see a valid response with your bot’s user ID and nickname, your bot is ready to use!

​
Step 6: Send Your First Message

Let’s send a test message to yourself or a friend: 
curl -X POST http://localhost:3000/send_private_msg \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 987654321,
    "message": "Hello from NapCat!"
  }'
Replace 987654321 with a real QQ number (you can send to yourself first for testing).

​
Step 7: Receive Messages

To receive messages, you have two options: Update your config/onebot11.json to enable WebSocket: 
{
  "ws": [
    {
      "enable": true,
      "host": "0.0.0.0",
      "port": 3001
    }
  ]
}
Restart NapCat and connect with a WebSocket client:
Node.js WebSocket Client
const WebSocket = require('ws');

const ws = new WebSocket('ws://localhost:3001');

ws.on('open', () => {
  console.log('Connected to NapCat');
});

ws.on('message', (data) => {
  const event = JSON.parse(data);
  
  if (event.post_type === 'message') {
    console.log('Received message:');
    console.log('Sender:', event.user_id);
    console.log('Content:', event.raw_message);
    
    // Echo the message back
    if (event.message_type === 'private') {
      ws.send(JSON.stringify({
        action: 'send_private_msg',
        params: {
          user_id: event.user_id,
          message: `You said: ${event.raw_message}`
        }
      }));
    }
  }
});

​
Option 2: HTTP Webhook

Enable webhook in config/onebot11.json: 
{
  "http": [
    {
      "enable": true,
      "host": "0.0.0.0",
      "port": 3000,
      "secret": "",
      "enablePost": true,
      "postUrls": ["http://your-server.com:8080/webhook"]
    }
  ]
}
NapCat will POST events to your webhook URL.

​
Next Steps

Congratulations! You’ve successfully set up NapCat and sent your first message. Here’s what to explore next:

Configuration

Learn about all configuration options

Message Handling

Work with different message types and media

API Reference

Explore all available API actions

Deployment

Deploy your bot to production

​
Troubleshooting

If port 3000 or 3001 is already in use, change the port number in config/onebot11.json to an available port (e.g., 3002, 8080).
Make sure:
  • NapCat is running and shows “HTTP Server started” in the logs
  • You’re using the correct host and port
  • Firewall allows the connection
Try these solutions:
  • Refresh the QR code if it expired
  • Use quick login if you’ve logged in before
  • Check if QQ account has restrictions
Verify:
  • The target QQ number is correct
  • Your bot account hasn’t been restricted
  • The recipient hasn’t blocked your bot
For more help, check the Troubleshooting Guide or visit the Community.

Build docs developers (and LLMs) love

Get started for freeTalk to us