Installation

System Requirements

Before installing NapCat, ensure your system meets these requirements:

Minimum Requirements

Operating System: Windows 10+, macOS 10.15+, or Linux (Ubuntu 20.04+, Debian 11+, etc.)
Node.js: Version 18.0.0 or higher
Memory: 512MB RAM minimum, 1GB recommended
Storage: 200MB available disk space
QQ: Latest version of QQ installed (for Framework mode)

Recommended Requirements

Memory: 2GB RAM or more for better performance
Storage: 1GB available disk space for logs and cache
Network: Stable internet connection

NapCat supports both Shell Mode (standalone) and Framework Mode (QQ plugin). Choose the mode that best fits your deployment needs.

Download NapCat

Visit GitHub Releases

Go to the NapCat GitHub Releases page to download the latest version.

Choose your platform

Download the appropriate package for your operating system:

Windows
macOS
Linux

NapCat-win-x64.zip for 64-bit Windows
Extract to a folder like C:\NapCat

NapCat-darwin-x64.zip for Intel Macs
NapCat-darwin-arm64.zip for Apple Silicon
Extract to a folder like /Applications/NapCat

NapCat-linux-x64.zip for 64-bit Linux
Extract to a folder like /opt/napcat or ~/napcat

Verify the download

Check that you have the main executable:

Windows: napcat.exe
Linux/macOS: napcat

Installation Methods

NapCat supports two deployment modes. Choose the one that fits your needs:

Framework Mode (Recommended)
Shell Mode
Docker

Framework Mode Installation

Framework Mode runs NapCat as a plugin injected into QQ, providing the best compatibility and features.

Prerequisites

QQ installed on your system
QQ version must match NapCat compatibility (check release notes)

Installation Steps

Install QQ

Download and install the latest version of QQ from the official QQ website.

Extract NapCat

Extract the NapCat archive to a permanent location:

# Linux/macOS
unzip NapCat-linux-x64.zip -d /opt/napcat
cd /opt/napcat

# Windows PowerShell
Expand-Archive NapCat-win-x64.zip -DestinationPath C:\NapCat
cd C:\NapCat

Create configuration

Create the configuration directory and files:

mkdir -p config

Create config/napcat.json:

config/napcat.json

{
  "fileLog": true,
  "consoleLog": true,
  "fileLogLevel": "info",
  "consoleLogLevel": "info"
}

Create config/onebot11.json:

config/onebot11.json

{
  "http": [
    {
      "enable": true,
      "host": "0.0.0.0",
      "port": 3000,
      "secret": "",
      "enableHeart": true,
      "enablePost": false
    }
  ],
  "ws": [
    {
      "enable": true,
      "host": "0.0.0.0",
      "port": 3001
    }
  ],
  "debug": false,
  "messagePostFormat": "array"
}

Launch NapCat

Run NapCat in Framework mode:

# Linux/macOS
./napcat --framework

# Windows
.\napcat.exe --framework

NapCat will automatically detect your QQ installation and inject itself as a plugin.

Access WebUI

After launch, NapCat will display the WebUI URL:

[NapCat] WebUI URL: http://127.0.0.1:6099/webui/?token=your-token-here

Open this URL in your browser to access the management interface.

Framework Mode Features

✅ Multiple login methods (QR code, password, quick login)
✅ Rich WebUI for management
✅ Access to all QQ features
✅ Best compatibility with QQ
✅ Suitable for desktop environments

Shell Mode Installation

Shell Mode runs NapCat as a standalone process, ideal for headless servers.

Prerequisites

No QQ installation required
Server or headless environment

Installation Steps

Extract NapCat

unzip NapCat-linux-x64.zip -d /opt/napcat
cd /opt/napcat

Create configuration

Create the configuration directory:

mkdir -p config

Create config/napcat.json:

config/napcat.json

{
  "fileLog": true,
  "consoleLog": true,
  "fileLogLevel": "info",
  "consoleLogLevel": "info"
}

Create config/onebot11.json (same as Framework mode)

Launch NapCat

Run NapCat in Shell mode:

./napcat --shell

In Shell mode, NapCat manages QQ instances as child processes with automatic crash recovery.

NapCat will generate a QR code in the terminal. Scan it with your QQ mobile app to log in.Alternatively, access the WebUI at the provided URL to use other login methods.

Shell Mode Features

✅ Runs independently of QQ GUI
✅ Process management and crash recovery
✅ Suitable for headless servers
✅ Minimal resource usage
✅ Automatic restart on crash

Docker Installation

Deploy NapCat using Docker for easy containerized deployment.

Docker support may vary depending on the NapCat version. Check the official documentation for the latest Docker images.

Using Docker Compose

Create a docker-compose.yml file:

docker-compose.yml

version: '3'

services:
  napcat:
    image: napcatneko/napcat:latest
    container_name: napcat
    restart: unless-stopped
    ports:
      - "3000:3000"  # HTTP API
      - "3001:3001"  # WebSocket
      - "6099:6099"  # WebUI
    volumes:
      - ./config:/app/config
      - ./data:/app/data
      - ./logs:/app/logs
    environment:
      - TZ=Asia/Shanghai

Start the container:

docker-compose up -d

View logs:

docker-compose logs -f napcat

Directory Structure

After installation, your NapCat directory should look like this:

napcat/
├── napcat              # Main executable
├── config/             # Configuration directory
│   ├── napcat.json     # Core configuration
│   └── onebot11.json   # OneBot protocol configuration
├── data/               # Runtime data (created after first run)
├── logs/               # Log files (created after first run)
└── temp/               # Temporary files (created after first run)

Configuration Files

napcat.json

Core NapCat configuration:

config/napcat.json

{
  "fileLog": true,
  "consoleLog": true,
  "fileLogLevel": "info",
  "consoleLogLevel": "info",
  "autoTimeSync": true,
  "o3HookMode": 0,
  "bypass": {
    "hook": false,
    "window": false,
    "module": false,
    "process": false,
    "container": false,
    "js": false
  }
}

See NapCat Configuration for details.

onebot11.json

OneBot 11 protocol configuration:

config/onebot11.json

{
  "http": [
    {
      "enable": true,
      "host": "0.0.0.0",
      "port": 3000,
      "secret": "",
      "enableHeart": true,
      "enablePost": false,
      "postUrls": []
    }
  ],
  "ws": [
    {
      "enable": true,
      "host": "0.0.0.0",
      "port": 3001
    }
  ],
  "reverseWs": {
    "enable": false,
    "urls": []
  },
  "debug": false,
  "heartInterval": 30000,
  "messagePostFormat": "array",
  "enableLocalFile2Url": true,
  "musicSignUrl": "",
  "reportSelfMessage": false,
  "token": ""
}

See OneBot Configuration for details.

Post-Installation

Verify installation

Check that NapCat is running:

curl http://localhost:3000/get_status

You should receive a JSON response with the bot status.

Set up authentication (recommended)

Add a secret token to your onebot11.json:

{
  "http": [
    {
      "secret": "your-secret-token-here"
    }
  ]
}

Restart NapCat for changes to take effect.

Configure firewall

If deploying on a server, configure your firewall to allow:

Port 3000 (HTTP API)
Port 3001 (WebSocket)
Port 6099 (WebUI)

# UFW (Ubuntu/Debian)
sudo ufw allow 3000/tcp
sudo ufw allow 3001/tcp
sudo ufw allow 6099/tcp

Updating NapCat

To update NapCat to a new version:

Stop NapCat

Stop the running NapCat process (Ctrl+C or stop the service).

Backup configuration

cp -r config config.backup

Download new version

Download the latest release from GitHub and extract it to the same directory (replace old files).

Restart NapCat

Launch NapCat again with your preferred mode.

Verify update

Check the version:

curl http://localhost:3000/get_version_info

Troubleshooting

Permission denied on Linux/macOS

Make the executable file executable:

chmod +x napcat

Port already in use

Change the port numbers in config/onebot11.json to available ports.

QQ not detected (Framework mode)

Ensure:

QQ is installed in the default location
You’re using a compatible QQ version
QQ is not running when you start NapCat

Failed to start WebUI

Check:

Port 6099 is not in use
Firewall allows connections
WebUI is not disabled in configuration

Next Steps

Quickstart

Follow the quickstart guide to send your first message

Configuration

Learn about all configuration options

Deployment

Deploy NapCat to production

Login Methods

Explore different ways to log in

Getting Started

Core Concepts

Configuration

Guides

Advanced

System Requirements

Minimum Requirements

Recommended Requirements

Download NapCat

Installation Methods

Framework Mode Installation

Prerequisites

Installation Steps

Framework Mode Features

Shell Mode Installation

Prerequisites

Installation Steps

Shell Mode Features

Docker Installation

Using Docker Compose

Directory Structure

Configuration Files

napcat.json

onebot11.json

Post-Installation

Updating NapCat

Troubleshooting

Next Steps

Quickstart

Configuration

Deployment

Login Methods

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Configuration

Guides

Advanced

​System Requirements

​Minimum Requirements

​Recommended Requirements

​Download NapCat

​Installation Methods

​Framework Mode Installation

​Prerequisites

​Installation Steps

​Framework Mode Features

​Shell Mode Installation

​Prerequisites

​Installation Steps

​Shell Mode Features

​Docker Installation

​Using Docker Compose

​Directory Structure

​Configuration Files

​napcat.json

​onebot11.json

​Post-Installation

​Updating NapCat

​Troubleshooting

​Next Steps

Quickstart

Configuration

Deployment

Login Methods

Build docs developers (and LLMs) love

System Requirements

Minimum Requirements

Recommended Requirements

Download NapCat

Installation Methods

Framework Mode Installation

Prerequisites

Installation Steps

Framework Mode Features

Shell Mode Installation

Prerequisites

Installation Steps

Shell Mode Features

Docker Installation

Using Docker Compose

Directory Structure

Configuration Files

napcat.json

onebot11.json

Post-Installation

Updating NapCat

Troubleshooting

Next Steps