Installation

Detailed installation instructions for NapCat in Shell and Framework modes

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

1. Visit GitHub Releases

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

2. Choose your platform

   Download the appropriate package for your operating system:

   Windows

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

   macOS

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

   Linux

   • NapCat-linux-x64.zip for 64-bit Linux
   • Extract to a folder like /opt/napcat or ~/napcat
3. 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)

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

1. Install QQ

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

2. 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
   
3. 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"
   }
   
4. 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.

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

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

1. Extract NapCat

   unzip NapCat-linux-x64.zip -d /opt/napcat
   cd /opt/napcat
   
2. 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)

3. Launch NapCat

   Run NapCat in Shell mode:

   ./napcat --shell
   

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

4. Login via QR code

   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

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

1. Verify installation

   Check that NapCat is running:

   curl http://localhost:3000/get_status
   

   You should receive a JSON response with the bot status.

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

3. 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:

1. Stop NapCat

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

2. Backup configuration

   cp -r config config.backup
   
3. Download new version

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

4. Restart NapCat

   Launch NapCat again with your preferred mode.

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