> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/NapNeko/NapCatQQ/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart Guide

> Get your NapCat bot up and running in minutes

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

<Note>
  This guide assumes you have QQ installed on your system. If you don't have QQ, download it from the [official QQ website](https://im.qq.com/).
</Note>

## 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

<Steps>
  <Step title="Get the latest release">
    Download the latest version of NapCat from the [GitHub Releases page](https://github.com/NapNeko/NapCatQQ/releases/).

    Choose the appropriate package for your operating system:

    * Windows: `NapCat-win-x64.zip`
    * macOS: `NapCat-darwin-x64.zip`
    * Linux: `NapCat-linux-x64.zip`
  </Step>

  <Step title="Extract the archive">
    Extract the downloaded archive to a location of your choice:

    ```bash theme={null}
    # Example for Linux/macOS
    unzip NapCat-linux-x64.zip -d napcat
    cd napcat
    ```
  </Step>
</Steps>

## Step 2: Initial Configuration

Create a basic configuration file to get started:

<Steps>
  <Step title="Create config directory">
    ```bash theme={null}
    mkdir -p config
    ```
  </Step>

  <Step title="Create OneBot config">
    Create `config/onebot11.json` with the following content:

    ```json config/onebot11.json theme={null}
    {
      "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>
</Steps>

## Step 3: Launch NapCat

<Tabs>
  <Tab title="Windows">
    Double-click `napcat.exe` or run from command prompt:

    ```cmd theme={null}
    napcat.exe
    ```
  </Tab>

  <Tab title="Linux/macOS">
    Make the binary executable and run it:

    ```bash theme={null}
    chmod +x napcat
    ./napcat
    ```
  </Tab>
</Tabs>

<Note>
  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.
</Note>

## Step 4: Login to QQ

<Steps>
  <Step title="Open WebUI">
    Open the WebUI URL shown in the console output (e.g., `http://127.0.0.1:6099/webui/?token=xxxxx`)
  </Step>

  <Step title="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
  </Step>

  <Step title="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>
</Steps>

## Step 5: Verify Connection

Test that your bot is working by calling the API:

```bash cURL theme={null}
curl http://localhost:3000/get_login_info
```

You should receive a response like:

```json theme={null}
{
  "status": "ok",
  "retcode": 0,
  "data": {
    "user_id": 123456789,
    "nickname": "YourBotName"
  },
  "message": "",
  "wording": "",
  "echo": ""
}
```

<Check>
  If you see a valid response with your bot's user ID and nickname, your bot is ready to use!
</Check>

## Step 6: Send Your First Message

Let's send a test message to yourself or a friend:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST http://localhost:3000/send_private_msg \
    -H "Content-Type: application/json" \
    -d '{
      "user_id": 987654321,
      "message": "Hello from NapCat!"
    }'
  ```

  ```javascript Node.js theme={null}
  const axios = require('axios');

  const NAPCAT_API = 'http://localhost:3000';

  async function sendMessage() {
    const response = await axios.post(`${NAPCAT_API}/send_private_msg`, {
      user_id: 987654321, // Replace with target QQ number
      message: 'Hello from NapCat!'
    });
    
    console.log('Message sent:', response.data);
  }

  sendMessage();
  ```

  ```python Python theme={null}
  import requests

  NAPCAT_API = 'http://localhost:3000'

  def send_message():
      response = requests.post(f'{NAPCAT_API}/send_private_msg', json={
          'user_id': 987654321,  # Replace with target QQ number
          'message': 'Hello from NapCat!'
      })
      
      print('Message sent:', response.json())

  if __name__ == '__main__':
      send_message()
  ```
</CodeGroup>

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:

### Option 1: WebSocket (Recommended)

Update your `config/onebot11.json` to enable WebSocket:

```json theme={null}
{
  "ws": [
    {
      "enable": true,
      "host": "0.0.0.0",
      "port": 3001
    }
  ]
}
```

Restart NapCat and connect with a WebSocket client:

```javascript Node.js WebSocket Client theme={null}
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`:

```json theme={null}
{
  "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:

<CardGroup cols={2}>
  <Card title="Configuration" icon="sliders" href="/config/napcat-config">
    Learn about all configuration options
  </Card>

  <Card title="Message Handling" icon="message" href="/guides/message-handling">
    Work with different message types and media
  </Card>

  <Card title="API Reference" icon="code" href="/api/onebot/overview">
    Explore all available API actions
  </Card>

  <Card title="Deployment" icon="server" href="/guides/deployment">
    Deploy your bot to production
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Port already in use">
    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).
  </Accordion>

  <Accordion title="Cannot connect to API">
    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
  </Accordion>

  <Accordion title="Login failed">
    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
  </Accordion>

  <Accordion title="Message not received">
    Verify:

    * The target QQ number is correct
    * Your bot account hasn't been restricted
    * The recipient hasn't blocked your bot
  </Accordion>
</AccordionGroup>

For more help, check the [Troubleshooting Guide](/resources/troubleshooting) or visit the [Community](/resources/community).