Frequently Asked Questions

General Questions

What is NapCat?

NapCat is a modern implementation of the Bot protocol based on NTQQ. It implements the OneBot 11 protocol, allowing developers to create QQ bots using a standardized API.

Is NapCat free?

Yes, NapCat is a non-profit open-source project. You can use it freely under the terms of its license.

Which QQ protocol does NapCat use?

NapCat is based on NTQQ (the new Tencent QQ client) and implements the OneBot 11 protocol standard for bot development.

What are the main features?

Easy to Use - Beginners can get started effortlessly
Quick and Efficient - Runs for extended periods on low-memory systems
Rich API Interface - Fully implements most standard OneBot 11 interfaces
Stable and Reliable - Continuous and stable development and maintenance

Installation and Setup

How do I install NapCat?

Download the latest version from the Release page
Extract the archive
Configure your onebot11.json file
Run NapCat

For detailed instructions, see the Installation Guide.

What are the system requirements?

NapCat is lightweight and can run on:

Windows, Linux, or macOS
Low-memory systems (as low as 512MB RAM)
Requires a compatible NTQQ installation

Do I need to install NTQQ separately?

Yes, NapCat requires NTQQ to be installed as it’s based on the NTQQ client.

Where do I find the configuration file?

The configuration file is typically named onebot11.json and is located in the NapCat configuration directory. The exact location depends on your installation method.

Configuration

How do I enable the HTTP API?

Add an HTTP server configuration to your onebot11.json:

{
  "network": {
    "httpServers": [{
      "enable": true,
      "port": 3000,
      "host": "127.0.0.1",
      "token": "your_secret_token"
    }]
  }
}

How do I enable WebSocket?

Add a WebSocket server configuration:

{
  "network": {
    "websocketServers": [{
      "enable": true,
      "port": 3001,
      "host": "127.0.0.1",
      "token": "your_secret_token"
    }]
  }
}

Can I run multiple network adapters?

Yes! You can configure multiple HTTP servers, WebSocket servers, WebSocket clients, and webhooks simultaneously:

{
  "network": {
    "httpServers": [{...}, {...}],
    "websocketServers": [{...}, {...}],
    "websocketClients": [{...}],
    "httpClients": [{...}]
  }
}

What is the token for?

The token is used for authentication. It ensures that only authorized applications can access your bot’s API. Always use a strong, random token in production.

Do I need to set a token?

The token is optional but highly recommended for security. If you don’t set a token, anyone who can reach your bot’s API can control it.

Authentication and Security

How do I authenticate API requests?

Use one of these methods: Authorization header (recommended):

curl -H "Authorization: Bearer your_token" http://localhost:3000/api

Query parameter:

curl "http://localhost:3000/api?access_token=your_token"

How do I verify webhook signatures?

NapCat signs webhook requests with HMAC-SHA1:

const crypto = require('crypto');
const signature = req.headers['x-signature'];
const body = JSON.stringify(req.body);

const hmac = crypto.createHmac('sha1', 'your_token');
hmac.update(body);
const expected = 'sha1=' + hmac.digest('hex');

if (signature === expected) {
  // Signature valid
}

Is it safe to expose NapCat to the internet?

No. NapCat should always run behind a reverse proxy (like Nginx) with:

HTTPS/TLS encryption
Rate limiting
IP whitelisting
Strong authentication tokens

For development, bind to 127.0.0.1 only.

Usage and API

How do I send a message?

HTTP API:

curl -X POST http://localhost:3000/send_private_msg \
  -H "Content-Type: application/json" \
  -d '{"user_id": 12345678, "message": "Hello!"}'

WebSocket:

ws.send(JSON.stringify({
  action: 'send_private_msg',
  params: {
    user_id: 12345678,
    message: 'Hello!'
  }
}));

How do I receive messages?

Messages are delivered via:

WebSocket - Events pushed to connected clients
HTTP Webhook - HTTP POST to your server
WebSocket Client (Reverse WS) - NapCat connects to your server

See Network Configuration for details.

What message formats are supported?

NapCat supports:

Plain text strings
CQ code format (e.g., [CQ:image,file=xxx])
Array format (OneBot 11 message segments)

{
  "message": [
    {"type": "text", "data": {"text": "Hello "}},
    {"type": "face", "data": {"id": "123"}}
  ]
}

How do I send images?

Use the image message segment:

{
  "message": [
    {"type": "image", "data": {"file": "file:///path/to/image.jpg"}}
  ]
}

Supported image sources:

Local file: file:///path/to/image.jpg
HTTP URL: http://example.com/image.jpg
Base64: base64://iVBORw0KG...

What APIs are available?

NapCat implements most OneBot 11 standard APIs:

Send messages (private, group, guild)
Delete messages
Get message info
Send reactions (likes)
Group management (kick, ban, admin)
Friend requests
Group member info
And more…

See the API Reference for complete list.

Troubleshooting

My bot won’t connect

Check if NapCat is running
Verify the port and host in your configuration
Check firewall settings
Ensure NTQQ is logged in
Review logs for error messages

See Troubleshooting Guide for detailed solutions.

I’m getting “token verify failed”

This means authentication failed:

Verify the token matches in both config and request
Check for typos or extra spaces
Ensure you’re sending the token correctly (header or query param)
Token is case-sensitive

Events aren’t being received

For WebSocket: Connect to / not /api
Check that the adapter is enabled in config
Verify the bot is logged in and online
Check reportSelfMessage setting
Enable debug logging to see event flow

Messages aren’t sending

Check API response for error messages
Verify user/group ID is correct
Ensure bot has permission (is friend or group member)
Check message format
Review rate limits

Configuration changes have no effect

Ensure you edited the correct config file
Check JSON syntax is valid
Restart NapCat completely
Check file permissions
Look for error messages in logs

Community and Support

Where can I get help?

Join the NapCat community groups (get password from WebUI):

NapCat Family Group 1 (1090875633)
NapCat Family Group 2 (1059714215)
NapCat Family Group 3 (1085662710)
NapCat Family Group 4 (1085359803)

Note: This is a non-profit project. Please search for solutions to basic questions and integration issues on your own.

Can I contribute to NapCat?

Yes! Contributions are welcome. Please read the Contributing Guide for guidelines.

How do I report a bug?

Report bugs on GitHub Issues:

Search for existing issues first
Provide clear reproduction steps
Include version, environment, and logs
Remove sensitive information (tokens, QQ numbers)

Where is the documentation?

Documentation is available at:

Is there an English community?

The main community is Chinese-language focused. However, documentation is being translated, and English speakers are welcome in the community groups.

Advanced Topics

Can I run NapCat in Docker?

Yes, Docker deployment is supported. Check the deployment documentation for container setup.

How do I run multiple bots?

Run separate NapCat instances with different configuration files and NTQQ accounts.

Can I use NapCat with other frameworks?

Yes! NapCat implements the OneBot 11 standard, so it works with any framework that supports OneBot 11:

Nonebot2
Koishi
AstrBot
And many others

What’s the difference between WebSocket Server and Client?

WebSocket Server - Your application connects to NapCat
WebSocket Client (Reverse) - NapCat connects to your server

Use server mode for simpler setups. Use client mode when NapCat needs to connect out (e.g., NapCat behind NAT).

How do I handle rate limits?

Implement rate limiting in your application:

Don’t send too many messages too quickly
Use delays between requests
Monitor API responses for rate limit errors
Implement exponential backoff on errors

Can I modify NapCat?

Yes, but with restrictions:

NapCat is open source under specific license terms
Developing projects based on NapCat code requires authorization from the main author
Always comply with local laws and regulations
See the License for details

Version and Updates

How do I check my NapCat version?

Check the version in:

Startup logs
WebUI About page
HTTP API root endpoint response

How do I update NapCat?

Download the latest release
Backup your configuration
Stop NapCat
Replace files with new version
Review migration notes for breaking changes
Start NapCat

What is the latest version?

Check the Release page for the latest version.

Are there breaking changes between versions?

Some versions may include breaking changes. Always review the Migration Guide and release notes before updating.

What is the minimum version for community groups?

The community join key requires NapCat version >= 4.17.31 and is only valid for the latest 100 versions.

Project and Development

Who maintains NapCat?

NapCat is currently looking for a new primary maintainer. Contact [email protected] if interested.

What license does NapCat use?

NapCat uses a hybrid license:

Third-party code follows original licenses
Certain authorized projects are exempt from restrictions
Remaining code is governed by the repository license

See LICENSE for details.

Can I mention NapCat in other communities?

No. Please do not mention NapCat in other communities (including other protocol-side or application-side projects) to avoid disputes.

How can I support the project?

You can support NapCat by:

Contributing code or documentation
Reporting bugs and issues
Helping other users in the community
Sharing your projects built with NapCat
Following the code of conduct

Resources

​General Questions

​What is NapCat?

​Is NapCat free?

​Which QQ protocol does NapCat use?

​What are the main features?

​Installation and Setup

​How do I install NapCat?

​What are the system requirements?

​Do I need to install NTQQ separately?

​Where do I find the configuration file?

​Configuration

​How do I enable the HTTP API?

​How do I enable WebSocket?

​Can I run multiple network adapters?

​What is the token for?

​Do I need to set a token?

​Authentication and Security

​How do I authenticate API requests?

​How do I verify webhook signatures?

​Is it safe to expose NapCat to the internet?

​Usage and API

​How do I send a message?

​How do I receive messages?

​What message formats are supported?

​How do I send images?

​What APIs are available?

​Troubleshooting

​My bot won’t connect

​I’m getting “token verify failed”

​Events aren’t being received

​Messages aren’t sending

​Configuration changes have no effect

​Community and Support

​Where can I get help?

​Can I contribute to NapCat?

​How do I report a bug?

​Where is the documentation?

​Is there an English community?

​Advanced Topics

​Can I run NapCat in Docker?

​How do I run multiple bots?

​Can I use NapCat with other frameworks?

​What’s the difference between WebSocket Server and Client?

​How do I handle rate limits?

​Can I modify NapCat?

​Version and Updates

​How do I check my NapCat version?

​How do I update NapCat?

​What is the latest version?

​Are there breaking changes between versions?

​What is the minimum version for community groups?

​Project and Development

​Who maintains NapCat?

​What license does NapCat use?

​Can I mention NapCat in other communities?

​How can I support the project?

​Next Steps

Build docs developers (and LLMs) love