Search the web for how to install NapCat (NapCatQQ) on a Linux server without Docker. I need:
1. The latest installation method for headless Linux (no GUI)
2. Whether it supports a pure CLI/WebUI login method
3. The WebSocket configuration to connect to a local service
4. Any prerequisites (like QQ account setup)

Focus on the official NapCat documentation or GitHub repo. Return the key installation steps and configuration.


The user wants information about installing NapCat (NapCatQQ) on a Linux server without Docker. Let me search for the latest information about this.


WebSearch

Question: NapCatQQ install Linux server headless without Docker 2026


Question: NapCat GitHub official documentation installation guide


Web search results for query: "NapCat GitHub official documentation installation guide"

There's an issue with the selected model (claude-haiku-4-5-20251001). It may not exist or you may not have access to it. Run /model to pick a different model.

REMINDER: You MUST include the sources above in your response to the user using markdown hyperlinks.
[result-id: r1]


Web search results for query: "NapCatQQ install Linux server headless without Docker 2026"

There's an issue with the selected model (claude-haiku-4-5-20251001). It may not exist or you may not have access to it. Run /model to pick a different model.

REMINDER: You MUST include the sources above in your response to the user using markdown hyperlinks.
[result-id: r2]


The web search didn't return useful results due to a model issue. Let me try fetching the NapCat GitHub repo and documentation directly.


WebFetch

Prompt: Find the NapCatQQ installation instructions for Linux server without Docker, headless mode, WebUI login, WebSocket configuration, and prerequisites


Prompt: Find installation guide for Linux headless server, WebUI login, WebSocket configuration, and prerequisites


There's an issue with the selected model (claude-haiku-4-5-20251001). It may not exist or you may not have access to it. Run /model to pick a different model.


Bash

curl -sL "https://api.github.com/repos/NapNeko/NapCatQQ" | head -100

Fetch NapCatQQ GitHub repo metadata


curl -sL "https://raw.githubusercontent.com/NapNeko/NapCatQQ/main/README.md" | head -200

Fetch NapCatQQ README from GitHub


{
  "id": 777721566,
  "node_id": "R_kgDOLlsW3g",
  "name": "NapCatQQ",
  "full_name": "NapNeko/NapCatQQ",
  "private": false,
  "owner": {
    "login": "NapNeko",
    "id": 165024194,
    "node_id": "O_kgDOCdYRwg",
    "avatar_url": "https://avatars.githubusercontent.com/u/165024194?v=4",
    "gravatar_id": "",
    "url": "https://api.github.com/users/NapNeko",
    "html_url": "https://github.com/NapNeko",
    "followers_url": "https://api.github.com/users/NapNeko/followers",
    "following_url": "https://api.github.com/users/NapNeko/following{/other_user}",
    "gists_url": "https://api.github.com/users/NapNeko/gists{/gist_id}",
    "starred_url": "https://api.github.com/users/NapNeko/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.github.com/users/NapNeko/subscriptions",
    "organizations_url": "https://api.github.com/users/NapNeko/orgs",
    "repos_url": "https://api.github.com/users/NapNeko/repos",
    "events_url": "https://api.github.com/users/NapNeko/events{/privacy}",
    "received_events_url": "https://api.github.com/users/NapNeko/received_events",
    "type": "Organization",
    "user_view_type": "public",
    "site_admin": false
  },
  "html_url": "https://github.com/NapNeko/NapCatQQ",
  "description": "Modern protocol-side framework based on NTQQ",
  "fork": false,
  "url": "https://api.github.com/repos/NapNeko/NapCatQQ",
  "forks_url": "https://api.github.com/repos/NapNeko/NapCatQQ/forks",
  "keys_url": "https://api.github.com/repos/NapNeko/NapCatQQ/keys{/key_id}",
  "collaborators_url": "https://api.github.com/repos/NapNeko/NapCatQQ/collaborators{/collaborator}",
  "teams_url": "https://api.github.com/repos/NapNeko/NapCatQQ/teams",
  "hooks_url": "https://api.github.com/repos/NapNeko/NapCatQQ/hooks",
  "issue_events_url": "https://api.github.com/repos/NapNeko/NapCatQQ/issues/events{/number}",
  "events_url": "https://api.github.com/repos/NapNeko/NapCatQQ/events",
  "assignees_url": "https://api.github.com/repos/NapNeko/NapCatQQ/assignees{/user}",
  "branches_url": "https://api.github.com/repos/NapNeko/NapCatQQ/branches{/branch}",
  "tags_url": "https://api.github.com/repos/NapNeko/NapCatQQ/tags",
  "blobs_url": "https://api.github.com/repos/NapNeko/NapCatQQ/git/blobs{/sha}",
  "git_tags_url": "https://api.github.com/repos/NapNeko/NapCatQQ/git/tags{/sha}",
  "git_refs_url": "https://api.github.com/repos/NapNeko/NapCatQQ/git/refs{/sha}",
  "trees_url": "https://api.github.com/repos/NapNeko/NapCatQQ/git/trees{/sha}",
  "statuses_url": "https://api.github.com/repos/NapNeko/NapCatQQ/statuses/{sha}",
  "languages_url": "https://api.github.com/repos/NapNeko/NapCatQQ/languages",
  "stargazers_url": "https://api.github.com/repos/NapNeko/NapCatQQ/stargazers",
  "contributors_url": "https://api.github.com/repos/NapNeko/NapCatQQ/contributors",
  "subscribers_url": "https://api.github.com/repos/NapNeko/NapCatQQ/subscribers",
  "subscription_url": "https://api.github.com/repos/NapNeko/NapCatQQ/subscription",
  "commits_url": "https://api.github.com/repos/NapNeko/NapCatQQ/commits{/sha}",
  "git_commits_url": "https://api.github.com/repos/NapNeko/NapCatQQ/git/commits{/sha}",
  "comments_url": "https://api.github.com/repos/NapNeko/NapCatQQ/comments{/number}",
  "issue_comment_url": "https://api.github.com/repos/NapNeko/NapCatQQ/issues/comments{/number}",
  "contents_url": "https://api.github.com/repos/NapNeko/NapCatQQ/contents/{+path}",
  "compare_url": "https://api.github.com/repos/NapNeko/NapCatQQ/compare/{base}...{head}",
  "merges_url": "https://api.github.com/repos/NapNeko/NapCatQQ/merges",
  "archive_url": "https://api.github.com/repos/NapNeko/NapCatQQ/{archive_format}{/ref}",
  "downloads_url": "https://api.github.com/repos/NapNeko/NapCatQQ/downloads",
  "issues_url": "https://api.github.com/repos/NapNeko/NapCatQQ/issues{/number}",
  "pulls_url": "https://api.github.com/repos/NapNeko/NapCatQQ/pulls{/number}",
  "milestones_url": "https://api.github.com/repos/NapNeko/NapCatQQ/milestones{/number}",
  "notifications_url": "https://api.github.com/repos/NapNeko/NapCatQQ/notifications{?since,all,participating}",
  "labels_url": "https://api.github.com/repos/NapNeko/NapCatQQ/labels{/name}",
  "releases_url": "https://api.github.com/repos/NapNeko/NapCatQQ/releases{/id}",
  "deployments_url": "https://api.github.com/repos/NapNeko/NapCatQQ/deployments",
  "created_at": "2024-03-26T11:44:13Z",
  "updated_at": "2026-04-09T06:47:01Z",
  "pushed_at": "2026-04-06T08:57:40Z",
  "git_url": "git://github.com/NapNeko/NapCatQQ.git",
  "ssh_url": "git@github.com:NapNeko/NapCatQQ.git",
  "clone_url": "https://github.com/NapNeko/NapCatQQ.git",
  "svn_url": "https://github.com/NapNeko/NapCatQQ",
  "homepage": "https://napneko.github.io",
  "size": 373513,
  "stargazers_count": 8352,
  "watchers_count": 8352,
  "language": "TypeScript",
  "has_issues": true,
  "has_projects": false,
  "has_downloads": true,
  "has_wiki": true,
  "has_pages": false,
  "has_discussions": true,
  "forks_count": 691,
  "mirror_url": null,
  "archived": false,
  "disabled": false,
  "open_issues_count": 12,
  "license": {
    "key": "other",
    "name": "Other",
    "spdx_id": "NOASSERTION",
    "url": null,
    "node_id": "MDc6TGljZW5zZTA="
  },
  "allow_forking": true,
  "is_template": false,
  "web_commit_signoff_required": true,
[result-id: r3]


# NapCat

_Modern protocol-side framework implemented based on NTQQ._

> 云起兮风生，心向远方兮路未曾至.

---

## New Feature

在 v4.8.115+ 版本开始

1. NapCatQQ 支持 [Stream Api](https://napneko.github.io/develop/file)
2. NapCatQQ 推荐 message_id/user_id/group_id 均使用字符串类型

- [1] 解决 Docker/跨设备/大文件 的多媒体上下传问题
- [2] 采用字符串可以解决扩展到int64的问题，同时也可以解决部分语言（如JavaScript）对大整数支持不佳的问题，增加极少成本。

## Welcome

- NapCatQQ is a modern implementation of the Bot protocol based on NTQQ.
  - NapCatQQ 是现代化的基于 NTQQ 的 Bot 协议端实现

## Feature

- **Easy to Use**
  - 作为初学者能够轻松使用.
- **Quick and Efficient**
  - 在低内存操作系统长时运行.
- **Rich API Interface**
  - 完整实现了大部分标准接口.
- **Stable and Reliable**
  - 持续稳定的开发与维护.

## Quick Start

可前往 [Release](https://github.com/NapNeko/NapCatQQ/releases/) 页面下载最新版本

**首次使用**请务必查看如下文档看使用教程

> 项目非盈利，涉及 对接问题/基础问题/下层框架问题 请自行搜索解决，本项目社区不提供此类解答。

## Link

| Docs | [![Github.IO](https://img.shields.io/badge/docs%20on-Github.IO-orange)](https://napneko.github.io/) | [![Cloudflare.Worker](https://img.shields.io/badge/docs%20on-Cloudflare.Worker-black)](https://doc.napneko.icu/) | [![Cloudflare.HKServer](https://img.shields.io/badge/docs%20on-Cloudflare.HKServer-informational)](https://napcat.napneko.icu/) |
|:-:|:-:|:-:|:-:|

| Docs | [![Cloudflare.Pages](https://img.shields.io/badge/docs%20on-Cloudflare.Pages-blue)](https://napneko.pages.dev/) | [![Server.Other](https://img.shields.io/badge/docs%20on-Server.Other-green)](https://napcat.top/) | [![NapCat.Top](https://img.shields.io/badge/docs%20on-NapCat.Top-red)](https://napcat.top/) |
|:-:|:-:|:-:|:-:|

| QQ Group | [![NapCat Family Group 4](https://img.shields.io/badge/NapCat%20Family%20Group%204-Join-blue)](https://qm.qq.com/q/E4nfkGD6oK) | [![NapCat Family Group 3](https://img.shields.io/badge/NapCat%20Family%20Group%203-Join-blue)](https://qm.qq.com/q/XyiyGPqa42) | [![NapCat Family Group 2](https://img.shields.io/badge/NapCat%20Family%20Group%202-Join-blue)](https://qm.qq.com/q/gq18RH7o7S) | [![NapCat Family Group 1](https://img.shields.io/badge/NapCat%20Family%20Group%201-Join-blue)](https://qm.qq.com/q/VwpnklcXqo) |
|:-:|:-:|:-:|:-:|:-:|

| Telegram | [![Telegram](https://img.shields.io/badge/Telegram-napcatqq-blue)](https://t.me/napcatqq) |
|:-:|:-:|

| DeepWiki | [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/NapNeko/NapCatQQ) |
|:-:|:-:|

> QQ群因为特殊原因需要入群密钥，请在webui关于页面获取，仅最新的100个版本以内有效。

下面的QQ Group 无需密钥，随时清理不活跃人员和Bot，仅500人容量。

[困困猫猫的高中](https://qm.qq.com/q/14aUVclRUA)

## Thanks

- [Lagrange](https://github.com/LagrangeDev/Lagrange.Core) 对本项目的大力支持 参考部分代码 已获授权

- [AstrBot](https://github.com/AstrBotDevs/AstrBot) 是完美适配本项目的LLM Bot框架 在此推荐一下

- [MaiBot](https://github.com/MaiM-with-u/MaiBot) 一只赛博群友 麦麦 Bot框架 在此推荐一下

- [qq-chat-exporter](https://github.com/shuakami/qq-chat-exporter/) 基于NapCat的消息导出工具 在此推荐一下

- 不过最最重要的 还是需要感谢屏幕前的你哦~

---

## License

本项目采用 混合协议 开源，因此使用本项目时，你需要注意以下几点：

1. 第三方库代码或修改部分遵循其原始开源许可.
2. 本项目获取部分项目授权而不受部分约束
2. 项目其余逻辑代码采用[本仓库开源许可](./LICENSE).

**本仓库仅用于提高易用性，实现消息推送类功能，此外，禁止任何项目未经仓库主作者授权基于 NapCat 代码开发。使用请遵守当地法律法规，由此造成的问题由使用者和提供违规使用教程者负责。**
[result-id: r4]


curl -sL "https://napneko.github.io/guide/getting-started" 2>/dev/null | head -500

Fetch NapCat getting started docs


curl -sL "https://raw.githubusercontent.com/NapNeko/NapCatQQ/main/script/napcat.sh" 2>/dev/null | head -100

Check for NapCat install script


curl -sL "https://api.github.com/repos/NapNeko/NapCatQQ/releases/latest" 2>/dev/null | python3 -c "import sys,json; d=json.load(sys.stdin); print('Tag:', d.get('tag_name','')); [print(a['name'], a['browser_download_url']) for a in d.get('assets',[])]" 2>/dev/null

Get latest NapCat release info


<!DOCTYPE html>

    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width,initial-scale=1">
    <title>404 | NapCatQQ</title>
    <meta name="description" content="Not Found">
    <meta name="generator" content="VitePress v1.6.4">
    <link rel="preload stylesheet" href="/assets/style.qppx-uBn.css" as="style">
    <link rel="preload stylesheet" href="/vp-icons.css" as="style">

    <link rel="preload" href="/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
    <link rel="icon" type="image/png" sizes="32x32" href="/assets/newnewlogo.png">
    <link rel="icon" type="image/png" sizes="16x16" href="/assets/newnewlogo.png">
    <link rel="apple-touch-icon" sizes="180x180" href="/assets/newnewlogo.png">
    <link rel="mask-icon" href="/assets/newnewlogo.png" color="#5bbad5">
    <meta name="theme-color" content="#5f67ee">

[result-id: r5]


404: Not Found


Tag: v4.17.55
NapCat.Framework.zip https://github.com/NapNeko/NapCatQQ/releases/download/v4.17.55/NapCat.Framework.zip
NapCat.Shell.Windows.Node.zip https://github.com/NapNeko/NapCatQQ/releases/download/v4.17.55/NapCat.Shell.Windows.Node.zip
NapCat.Shell.Windows.OneKey.zip https://github.com/NapNeko/NapCatQQ/releases/download/v4.17.55/NapCat.Shell.Windows.OneKey.zip
NapCat.Shell.zip https://github.com/NapNeko/NapCatQQ/releases/download/v4.17.55/NapCat.Shell.zip
[result-id: r6]


curl -sL "https://napneko.github.io/develop/env" 2>/dev/null | sed -n 's/<[^>]*>//gp' | head -200

Fetch NapCat environment/development docs


curl -sL "https://napneko.github.io/guide/boot" 2>/dev/null | sed -n 's/<[^>]*>//gp' | head -200

Fetch NapCat boot/startup guide


curl -sL "https://napneko.github.io/guide/" 2>/dev/null | sed -n 's/<[^>]*>//gp' | head -300

Fetch NapCat guide index page


    404 | NapCatQQ

    (()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();
    document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));
[result-id: r7]


<identical to result [r7] from your Bash call earlier — refer to that output>


curl -sL "https://napneko.github.io/sitemap.xml" 2>/dev/null | head -100

Fetch NapCat sitemap to find correct URLs


curl -sL "https://api.github.com/repos/NapNeko/NapCatQQ/contents/" 2>/dev/null | python3 -c "import sys,json; items=json.load(sys.stdin); [print(i['name'], i['type']) for i in items]" 2>/dev/null

List NapCatQQ repo root contents


.editorconfig file
.github dir
.gitignore file
.vscode dir
CODE_OF_CONDUCT.md file
LICENSE file
README.md file
SECURITY.md file
eslint.config.js file
logo.png file
package.json file
packages dir
pnpm-lock.yaml file
pnpm-workspace.yaml file
tsconfig.base.json file
[result-id: r9]


Now I can see the key documentation URLs from the sitemap. Let me fetch the most relevant pages.


curl -sL "https://napneko.github.io/guide/boot/Shell-Linux-SemiAuto" 2>/dev/null | python3 -c "
import sys, re
html = sys.stdin.read()
# Extract text between body tags, strip HTML
text = re.sub(r'<script[^>]*>.*?</script>', '', html, flags=re.S)
text = re.sub(r'<style[^>]*>.*?</style>', '', text, flags=re.S)
text = re.sub(r'<[^>]+>', '\n', text)
text = re.sub(r'\n{3,}', '\n\n', text)
text = re.sub(r'^\s+', '', text, flags=re.M)
print(text[:5000])
"

Fetch NapCat Shell Linux semi-auto install guide


curl -sL "https://napneko.github.io/guide/boot/Shell" 2>/dev/null | python3 -c "
import sys, re
html = sys.stdin.read()
text = re.sub(r'<script[^>]*>.*?</script>', '', html, flags=re.S)
text = re.sub(r'<style[^>]*>.*?</style>', '', text, flags=re.S)
text = re.sub(r'<[^>]+>', '\n', text)
text = re.sub(r'\n{3,}', '\n\n', text)
text = re.sub(r'^\s+', '', text, flags=re.M)
print(text[:5000])
"

Fetch NapCat Shell boot guide


curl -sL "https://napneko.github.io/guide/start-install" 2>/dev/null | python3 -c "
import sys, re
html = sys.stdin.read()
text = re.sub(r'<script[^>]*>.*?</script>', '', html, flags=re.S)
text = re.sub(r'<style[^>]*>.*?</style>', '', text, flags=re.S)
text = re.sub(r'<[^>]+>', '\n', text)
text = re.sub(r'\n{3,}', '\n\n', text)
text = re.sub(r'^\s+', '', text, flags=re.M)
print(text[:5000])
"

Fetch NapCat start-install guide


BootWay03 (半自动) 教程 | NapCatQQ
Skip to content
NapCatQQ
Search
K
Main Navigation
快速开始
关于
主题
菜单
回到顶部
Sidebar Navigation
快速开始
目录导航
什么是 NapCatQQ
启动方式
安装方式
Shell
Framework
配置
基础配置
高级配置
使用
接入框架
社区资源
开发
请求接口
上报事件
消息类型
处理文件
插件开发
插件机制原理
快速开始
项目结构
配置与 WebUI
进阶功能
热重载开发
发布插件
API 参考
API 文档
类型定义
完整接口定义
接口
类型
API 文档
版本选择
协议
协议概述
网络通讯
事件基础结构
事件字段详情
接口基础接口
消息元素定义
差异实现说明
其余
喵喵
安全
联系
页面导航
BootWay03 (半自动) 教程

字数
665 字
阅读时间
3 分钟
安装教程

1. 安装 QQ 和其他依赖

你需要安装 28060+ 版本的 QQ 和
xvfb
以及
xauth
，后两者安装方法为
Debian 系（Debian、Ubuntu 等）：
sudo apt install xvfb xauth
Redhat 系（Fedora、CentOS Stream 等）：
sudo dnf install xorg-x11-server-Xvfb xorg-x11-xauth
Arch 系：
sudo pacman -S xorg-server-xvfb
Redhat系的备注
对于RHEL 10+、CentOS Stream 10+以及其他基于此的发行版，X11服务器在这些系统中已经被
完全移除
，在这种情况下无法通过xvfb实现无头运行。目前没有其他已知方案。
AlmaLinux10是一个例外。如果你真的很想使用类CentOS发行版，请考虑AlmaLinux。
其他发行版可以参考
这个页面
自行选择合适的包安装，确保安装后
xvfb-run
命令存在
2. 挂载启动

执行命令
bash
echo
'const fs = require("fs");
const path = require("path");
const CurrentPath = path.dirname(__filename);
const hasNapcatParam = process.argv.includes("--no-sandbox");
if (hasNapcatParam) {
(async () => {
await import("file://" + path.join(CurrentPath, "./napcat/napcat.mjs"));
// await import("file://" + "/path/to/napcat/napcat.mjs");
// 需要修改napcat的用户，在"/path/to/napcat"段写自己的napcat文件夹位置，并注释path.join所在行
})();
} else {
require("./application/app_launcher/index.js");
setTimeout(() => {
global.launcher.installPathPkgJson.main = "./application.asar/app_launcher/index.js";
}, 0);
}'
>
/opt/QQ/resources/app/loadNapCat.cjs
如果你使用 LiteloaderQQNT，那么执行：
bash
echo
'const fs = require("fs");
const path = require("path");
const CurrentPath = path.dirname(__filename);
const hasNapcatParam = process.argv.includes("--no-sandbox");
if (hasNapcatParam) {
(async () => {
await import("file://" + path.join(CurrentPath, "./napcat/napcat.mjs"));
// await import("file:///path/to/napcat/napcat.mjs");
// 需要修改napcat的用户，在"/path/to/napcat"段写自己的napcat文件夹位置，并注释path.join所在行
})();
} else {
require(String.raw`/opt/LiteLoaderQQNT`);  //引号中写入你的liteloaderqqnt路径
}'
>
/opt/QQ/resources/app/loadNapCat.cjs
3. 安装 napcat

安装 napcat.shell 到
/opt/QQ/resources/app/napcat
确保
/opt/QQ/resources/app/napcat/napcat.mjs
存在
4. 修补 package.json

修改
/opt/QQ/resources/app/package.json
的
main
属性从
./application/app_launcher/index.js
改为
./loadNapCat.cjs
（注意：自 QQ 29927 版本左右起 main 属性内容有所变化，找到相似 main 属性直接改即可）
这步也可以使用下面替代
bash
chmod
+777
/opt/QQ
sed
-i
's/"main": ".*\/index.js"/"main": ".\/loadNapCat.cjs"/'
/opt/QQ/resources/app/package.json
5.启动

bash
xvfb-run
-a
qq
--no-sandbox
<
-q
[快速登录的qq号]
>
6.（可选）自动启动

在安装后，可以使用systemd等工具自动启动napcat。下面是一个systemd服务的示例。
service
[Unit]
Description=Napcat QQ Server
Documentation=https://napneko.github.io/guide
After=network.target
[Service]
User=<要使用的用户>
Restart=on-failure
WorkingDirectory=<建议使用该用户的home目录位置>
ExecStart=/usr/bin/xvfb-run -a qq --no-sandbox <-q [快速登录的qq号]>
[Install]
WantedBy=multi-user.target
将上面的内容写入
/etc/systemd/system/napcat.service
，然后使用
sudo systemctl enable napcat.service --now
命令即可启动并配置服务自启。
请注意：即使配置了系统服务，在未配置快速登录或快速登录失败时一样要手动扫码。
最后编辑于 6 个月前
查看完整历史
6dbb1e1
-
Update Shell-Linux-SemiAuto.md
1741ba6
-
Update Shell-Linux-SemiAuto.md
1bb4ac5
-
Update Shell-Linux-SemiAuto.md
b3b7d65
-
格式修正
52db183
-
Bootway03 补充/修正
07c8c12
-
broken回退
8803a42
-
Update Shell-Linux-SemiAuto.md
6e8f1f1
-
Update Shell-Linux-SemiAuto.md
1967199
-
style lint
68f9457
-
fix
在 GitHub 上编辑此页面
最后更新于:
Pager
下一页
目录导航
[result-id: r10]


Shell | NapCatQQ
Skip to content
NapCatQQ
Search
K
Main Navigation
快速开始
关于
主题
菜单
回到顶部
Sidebar Navigation
快速开始
目录导航
什么是 NapCatQQ
启动方式
安装方式
Shell
Framework
配置
基础配置
高级配置
使用
接入框架
社区资源
开发
请求接口
上报事件
消息类型
处理文件
插件开发
插件机制原理
快速开始
项目结构
配置与 WebUI
进阶功能
热重载开发
发布插件
API 参考
API 文档
类型定义
完整接口定义
接口
类型
API 文档
版本选择
协议
协议概述
网络通讯
事件基础结构
事件字段详情
接口基础接口
消息元素定义
差异实现说明
其余
喵喵
安全
联系
页面导航
Shell

字数
1546 字
阅读时间
7 分钟
NapCat.Shell - Win 手动启动教程
recommend

前往
NapCatQQ 的 Releases 页面
下载 NapCat.Shell.zip 并解压
确保 QQ 版本安装且最新
双击目录下 launcher.bat 即可启动 如果是 Win10 则使用 launcher-win10.bat
如果需要快速登录 将 QQ 号传入参数即可
Windows11.bat
Windows10.bat
bash
launcher.bat
123456
bash
launcher-win10.bat
123456
NapCat.Win.一键版本
recommend

特殊说明: 一键版仅适用
Windows.AMD64
无需安装 QQ 和 NapCat 已内置
前往
NapCatQQ 的 Releases 页面
下载 NapCat.Shell.Windows.OneKey.zip 无头绿色版本解压
点击 NapCatInstaller.exe 等待自动化配置
进去 NapCat.XXXX.Shell 目录
启动 napcat.bat
由于上面的包巨大且可能并不适合下载 特此为 Win64 无头 提供轻量化一键部署方案
对应的 NapCat.Shell.Windows.OneKey.zip 启动后 自动化部署一键包(此包仅适用 Windows)
如果需要快速启动 新建 Bat 文件写入如下例子
quick.bat
bash
NapCatWinBootMain.exe
10001
NapCat.Windows 可视化管理工具

安装简单
: 单 EXE 文件，无需安装任何依赖
界面美观
: 使用 Fluent Design System 设计
功能丰富
: 支持创建配置文件、管理配置文件、一键启动/停止/重启
自动更新
: 支持自动检查 NapCatQQ 更新，一键更新
多账户管理
: 支持同时登录和管理多个 QQ 账号，轻松切换不同账户
后台托管
: 可最小化到系统托盘运行，不占用任务栏空间，支持后台静默运行
引导安装
: 提供 QQ 和 NapCatQQ 的安装引导，自动检测并指导完成必要环境配置
软件截图
NapCatQQ-Desktop
NapCat.Installer - Linux 一键使用脚本(支持Ubuntu 20+/Debian 10+/Centos9)
recommend

docker 安装卡住的请使用下方项目并自行换源
通用安装
可视化安装
Docker 安装
Shell 强制重装
TUI-CLI 安装
bash
curl
-o
\
napcat.sh
\
https://nclatest.znin.net/NapNeko/NapCat-Installer/main/script/install.sh
\
&&
bash
napcat.sh
bash
curl
-o
\
napcat.sh
\
https://nclatest.znin.net/NapNeko/NapCat-Installer/main/script/install.sh
\
&&
bash
napcat.sh
\
--tui
bash
curl
-o
\
napcat.sh
\
https://nclatest.znin.net/NapNeko/NapCat-Installer/main/script/install.sh
\
&&
bash
napcat.sh
\
--docker
y
\
--qq
"123456789"
\
--mode
ws
\
--proxy
1
\
--confirm
bash
curl
-o
\
napcat.sh
\
https://nclatest.znin.net/NapNeko/NapCat-Installer/main/script/install.sh
\
&&
bash
napcat.sh
\
--docker
n
\
--cli
n
\
--proxy
0
\
--force
bash
curl
-o
\
napcat.sh
\
https://nclatest.znin.net/NapNeko/NapCat-Installer/main/script/install.sh
\
&&
bash
napcat.sh
\
--docker
n
\
--cli
y
命令选项(高级用法)
--tui
使用
tui
可视化交互安装
--docker
[y/n]: 使用 Docker 进行安装 (y) 或使用 Shell 直接安装 (n)
Docker 安装: 将 NapCat 运行在隔离的容器环境中，方便管理和迁移，但需要先安装 Docker
Shell 安装: 直接在当前系统环境中安装 NapCat 及其依赖
--qq
,
--mode
,
--confirm
: Docker 安装时使用的参数
--cli
[y/n]: 是否安装 NapCat TUI-CLI (命令行UI工具)
NapCat TUI-CLI
: 允许你在 ssh、没有桌面、WebUI 难以使用的情况下可视化交互配置 Napcat
--proxy
[0-6]: 指定下载时使用的代理服务器序号, Docker 安装可选 0-7, shell 安装可选 0-5
--force
传入则执行 shell 强制重装
仓库地址:
NapCat.installer
NapCat.Linux.Launcher - 新式非入侵式启动器

不破坏 NT 自身文件
缓存与 NapCat 位于当前工作目录
简单方便
更新 QQ 不会干扰 NapCat 安装
可重复运行
bash
curl
-o
napcat.sh
https://github.moeyy.xyz/https://raw.githubusercontent.com/NapNeko/napcat-linux-installer/refs/heads/main/install.sh
&&
bash
napcat.sh
bash
curl
-o
napcat.sh
https://raw.githubusercontent.com/NapNeko/napcat-linux-installer/refs/heads/main/install.sh
&&
bash
napcat.sh
NapCat.Linux.Launcher
NapCat.AppImage

不破坏 NT 自身文件
缓存与 NapCat 位于当前工作目录
简单方便
更新 QQ 不会干扰 NapCat 安装
可重复运行
依赖隔离
便携式
Linux AppImage格式
需要通过包管理安装xvfb和fuse 其余依赖一般不需要管理 自带napcat和NT
前往
NapCat.AppImage
NapCat.Docker - Linux容器化部署
recommend

仓库地址:
NapCat.Docker
除了常规的 docker run 样式的安装方法,此方法支持 compose 一键模板部署 astrbot, koishi, nonebot 详细参考 Readme 处
一键模板化配置
部分
群晖 DSM 用户注意
在群晖 DSM 环境的 Docker（Container Manager）中部署 NapCat 时，可能会遇到权限问题导致
permission denied
错误，例如：
Error: EACCES: permission denied, open '/app/napcat/config/webui.json'
Error: EACCES: permission denied, mkdir '/app/.config/QQ/NapCat/temp'
原因
：群晖 DSM 在存储池的文件夹下设置了自己的 ACL（访问控制列表），即使文件夹权限为 777，也只允许在 File Station 中授权的用户访问。
解决方案
：
打开群晖的
File Station
找到 NapCat 挂载的数据目录
右键点击文件夹，选择
属性
→
权限
点击
新增
，将
Everyone
设置为
读取/写入
权限
勾选
应用到这个文件夹、子文件夹及文件
点击
保存
后重新启动容器
NapCat.MacOs - MacOs安装工具
recommend

前往下载
需要 MacOS 12.0 或以上系统，支持下载和更新 NapCatQQ
由于权限问题，补丁过程需要手动替换 package.json，请注意备份原文件～
NapCat.Termux - 安卓 Termux 部署
recommend

Termux
bash
curl
-o
napcat.termux.sh
https://nclatest.znin.net/NapNeko/NapCat-Installer/main/script/install.termux.sh
&&
bash
napcat.termux.sh
仓库地址:
NapCat.installer
NapCat.1Panel - 1Panel插件部署
community

此为 社区作品 可能会遇到一些问题，欢迎反馈。
仓库地址:
NapCat.1Panel
NapCat.Railway - Railway 部署
community

此为 社区作品 可能会遇到一些问题，欢迎反馈。
NapCat.Zeabur - Zeabur 部署
community

此为 社区作品 可能会遇到一些问题，欢迎反馈。
NapCat.Nix - Nix 部署
community

此为 社区作品 可能会遇到一些问题，欢迎反馈。
仓库地址:
NapCat.Nix
最后编辑于 2 个月前
查看完整历史
0fb0176
-
Add DSM Docker permission warning for NapCat
d1c261a
-
Remove references to deprecated Windows installers
7982ed3
-
Add section for NapCat.AppImage installation
d243903
-
fix: 适配intall rootless 删除sudo
06a3770
-
Update Shell.md
4c401e3
-
在中文、英文以及数字混排时添加空格分隔
f4f0c4c
-
fix
6fe0b23
-
fix
c191b77
-
fix
56a06c2
-
Update Shell.md
94d251f
-
✨ feat(Other): 更新NCD介绍
e23
[result-id: r11]


NapCat | NapCatQQ
Skip to content
NapCatQQ
Search
K
Main Navigation
快速开始
关于
主题
菜单
回到顶部
Sidebar Navigation
快速开始
目录导航
什么是 NapCatQQ
启动方式
安装方式
Shell
Framework
配置
基础配置
高级配置
使用
接入框架
社区资源
开发
请求接口
上报事件
消息类型
处理文件
插件开发
插件机制原理
快速开始
项目结构
配置与 WebUI
进阶功能
热重载开发
发布插件
API 参考
API 文档
类型定义
完整接口定义
接口
类型
API 文档
版本选择
协议
协议概述
网络通讯
事件基础结构
事件字段详情
接口基础接口
消息元素定义
差异实现说明
其余
喵喵
安全
联系
页面导航
NapCat

字数
189 字
阅读时间
1 分钟
快速开始

安装

配置

生态

温馨提示
如果文档中发现错误，或提交文档修改、或丰富本站文档，可点击页面底部的编辑按钮。
最后编辑于 3 个月前
查看完整历史
b1575a2
-
docs：update docs (
#119
)
420c967
-
在中文、英文以及数字混排时添加空格分隔
#2
4c401e3
-
在中文、英文以及数字混排时添加空格分隔
c8cd7ca
-
feat: 文档简化
990af7e
-
fix
cd40262
-
fix
3354ca7
-
fix
ea0d450
-
fix
0014197
-
fix
3844427
-
fix
626f5b4
-
fix
777d0ff
-
fix
5c7106e
-
update: new docs
34cd1bf
-
fix
a289316
-
fix
06a70b6
-
fix
79452d6
-
fix
3633ebf
-
补齐结构体类型
479e978
-
fix: Framewrok
1967199
-
style lint
9390f9f
-
fix
604f554
-
fix
b66578d
-
fix
68f9457
-
fix
ac82f49
-
重构文档
在 GitHub 上编辑此页面
最后更新于:
Pager
下一页
什么是 NapCatQQ
[result-id: r12]


curl -sL "https://napneko.github.io/config/basic" 2>/dev/null | python3 -c "
import sys, re
html = sys.stdin.read()
text = re.sub(r'<script[^>]*>.*?</script>', '', html, flags=re.S)
text = re.sub(r'<style[^>]*>.*?</style>', '', text, flags=re.S)
text = re.sub(r'<[^>]+>', '\n', text)
text = re.sub(r'\n{3,}', '\n\n', text)
text = re.sub(r'^\s+', '', text, flags=re.M)
print(text[:8000])
"

Fetch NapCat basic configuration docs


curl -sL "https://napneko.github.io/onebot/network" 2>/dev/null | python3 -c "
import sys, re
html = sys.stdin.read()
text = re.sub(r'<script[^>]*>.*?</script>', '', html, flags=re.S)
text = re.sub(r'<style[^>]*>.*?</style>', '', text, flags=re.S)
text = re.sub(r'<[^>]+>', '\n', text)
text = re.sub(r'\n{3,}', '\n\n', text)
text = re.sub(r'^\s+', '', text, flags=re.M)
print(text[:8000])
"

Fetch NapCat network/WebSocket configuration docs


curl -sL "https://napneko.github.io/guide/boot/Linux_startup" 2>/dev/null | python3 -c "
import sys, re
html = sys.stdin.read()
text = re.sub(r'<script[^>]*>.*?</script>', '', html, flags=re.S)
text = re.sub(r'<style[^>]*>.*?</style>', '', text, flags=re.S)
text = re.sub(r'<[^>]+>', '\n', text)
text = re.sub(r'\n{3,}', '\n\n', text)
text = re.sub(r'^\s+', '', text, flags=re.M)
print(text[:5000])
"

Fetch NapCat Linux startup docs


💖 NapCatのWebUI配置指南💖 | NapCatQQ
Skip to content
NapCatQQ
Search
K
Main Navigation
快速开始
关于
主题
菜单
回到顶部
Sidebar Navigation
快速开始
目录导航
什么是 NapCatQQ
启动方式
安装方式
Shell
Framework
配置
基础配置
高级配置
使用
接入框架
社区资源
开发
请求接口
上报事件
消息类型
处理文件
插件开发
插件机制原理
快速开始
项目结构
配置与 WebUI
进阶功能
热重载开发
发布插件
API 参考
API 文档
类型定义
完整接口定义
接口
类型
API 文档
版本选择
协议
协议概述
网络通讯
事件基础结构
事件字段详情
接口基础接口
消息元素定义
差异实现说明
其余
喵喵
安全
联系
页面导航
💖 NapCatのWebUI配置指南💖

字数
1454 字
阅读时间
7 分钟
WARNING
低于 v4.4.7 请勿将注释内容写入配置文件，否则会导致配置文件解析失败，新版本不受限制。
配置网络类型
必备知识

类型
描述
HTTP 服务端
NapCat 作为 Http 请求接受方 接收对应接口调用并回应 的单工模型
HTTP 客户端
NapCat 作为 Http 请求发起方 将事件推送至插件/应用框架 的单工模型
WebSocket 服务端
通常指正向 WS 既能主动推送事件也能接收请求 的双工模型
WebSocket 客户端
通常指反向 WS 既能主动推送事件也能接收请求 的双工模型
通过 WebUI 配置 OneBot 服务
Shell Vesion

如果你已经启动了 NapCat，并且有多于 1 个开放端口，则可以通过 WebUI 进行配置。
默认地址为
0.0.0.0
，即监听所有地址。当配置了不可用的地址时 WebUI 将被禁用。
默认端口为
6099
。
当端口被设置为
0
时将禁用 WebUI。
当端口被占用时，会自动对端口 +1，直到找到可用端口（最多尝试 100 次，失败则会禁用 WebUI），端口号会在启动日志中显示。
启动后可在启动日志中看到形如
[info] [NapCat] [WebUi] WebUi User Panel Url: http://127.0.0.1:6099/webui?token=xxxxx
的 token 信息。
也可打开
webui.json
文件，在其中找到token。(使用 NapCat.Installer - Linux 一键脚本安装时，该文件位于
/opt/QQ/resources/app/app_launcher/napcat/config/webui.json
)
webui.json
json5
{
"host"
:
"0.0.0.0"
,
// WebUI 监听地址
"port"
:
6099
,
// WebUI 端口
"token"
:
"xxxx"
,
// 登录密钥, 默认是自动生成的随机登录密码
"loginRate"
:
3
,
// 每分钟登录次数限制
}
访问
http://ip:port/webui/
，然后进行以下操作：
进入 QQ 登录，点击
QRCode
进行二维码登录。
此时会刷新WebUi Token 请到 手机端查看自身消息/NapCat控制台查看 获取随机Token。
再次进入WebUi后会强制要求修改密码 否则禁用大部分功能
登录成功后，即可进入网络配置，点击 "新建" 创建对应的服务器或客户端。(如果是公网部署, 请
务必启用 Token
)
请在创建时勾选
保存时启用
，或者创建完成后手动启用。
访问
http://ip:port
检查端口是否正常。(此处的
port
指 4 中配置的端口, 请不要与 WebUI 端口混淆)
注：WebUI 自 v4.4 版本后不支持
prefix
配置。
通过 TUI-CLI 配置 OneBot 服务
Shell Vesion

前置条件
，使用 Shell 安装时同意安装
TUI-CLI
或者使用 --cli y 参数详见
Shell 安装
recommend
。
只需要你在终端中输入
sudo napcat
即可进入 TUI-CLI 界面。
通过 文件 配置OneBot服务
Any Vesion

非常不推荐 除非你非常熟悉
v4.5.3 后支持载入 ./config/onebot11.json 作为默认配置
该配置文件名为
./config/onebot11_xxxx.json
其中 xxxx 为对应 QQ 账户
HTTP 服务端
HTTP 客户端
WS 服务端
WS 客户端
json5
{
"network"
: {
// Http服务器组 可以配置多个 这里演示为一个
"httpServers"
: [
{
"name"
:
"httpServer"
,
// 名字不能重复 唯一标识
"enable"
:
false
,
//启用状态
"port"
:
3000
,
// 监听端口
"host"
:
"0.0.0.0"
,
// 监听主机
"enableCors"
:
true
,
// 暂时没有作用
"enableWebsocket"
:
true
,
// 暂时没有作用
"messagePostFormat"
:
"array"
,
// 消息上报格式 string/array
"token"
:
""
,
// 鉴权密钥
"debug"
:
false
,
// raw数据上报
}
],
"httpClients"
: [],
"websocketServers"
: [],
"websocketClients"
: []
},
"musicSignUrl"
:
""
,
"enableLocalFile2Url"
:
false
,
"parseMultMsg"
:
false
}
json5
{
"network"
: {
"httpServers"
: [],
// Http客户端组 可以配置多个 这里演示为一个
"httpClients"
: [
{
"name"
:
"httpClient"
,
// 名字不能重复 唯一标识
"enable"
:
false
,
//启用状态
"url"
:
"http://localhost:8080"
,
// 上报地址
"messagePostFormat"
:
"array"
,
// 消息上报格式 string/array
"reportSelfMessage"
:
false
,
// 是否上报自身消息
"token"
:
""
,
// 鉴权密钥
"debug"
:
false
,
// raw数据上报
}
],
"websocketServers"
: [],
"websocketClients"
: []
},
"musicSignUrl"
:
""
,
"enableLocalFile2Url"
:
false
,
"parseMultMsg"
:
false
}
json5
{
"network"
: {
"httpServers"
: [],
"httpClients"
: [],
// WS服务端组/正向WS  可以配置多个 这里演示为一个
"websocketServers"
: [
{
"name"
:
"WsServer"
,
// 名字不能重复 唯一标识
"enable"
:
false
,
//启用状态
"host"
:
"0.0.0.0"
,
// 监听主机
"port"
:
3001
,
// 监听端口
"messagePostFormat"
:
"array"
,
// 消息上报格式 string/array
"reportSelfMessage"
:
false
,
// 是否上报自身消息
"token"
:
""
,
// 鉴权密钥
"enableForcePushEvent"
:
true
,
// 暂时没有作用
"debug"
:
false
,
// raw数据上报
"heartInterval"
:
30000
,
// 心跳周期
}
],
"websocketClients"
: []
},
"musicSignUrl"
:
""
,
"enableLocalFile2Url"
:
false
,
"parseMultMsg"
:
false
}
json5
{
"network"
: {
"httpServers"
: [],
"httpClients"
: [],
"websocketServers"
: [],
// WS客户端组/反向WS 可以配置多个 这里演示为一个
"websocketClients"
: [
{
"name"
:
"WsClient"
,
// 名字不能重复 唯一标识
"enable"
:
false
,
//启用状态
"url"
:
"ws://localhost:8082"
,
// 上报地址
"messagePostFormat"
:
"array"
,
// 消息上报格式 string/array
"reportSelfMessage"
:
false
,
// 是否上报自身消息
"reconnectInterval"
:
5000
,
// 重连间隔
"token"
:
""
,
// 鉴权密钥
"debug"
:
false
,
// raw数据上报
"heartInterval"
:
30000
,
// 心跳周期
}
]
},
"musicSignUrl"
:
""
,
"enableLocalFile2Url"
:
false
,
"parseMultMsg"
:
false
}
配置 NapCat 其它设置

如果不懂干嘛，不用看啦
在这里你可以修改日志等基础设置
v4.5.3 后支持载入 ./config/napcat.json作为默认配置
启动登录 NapCat 后，打开 NapCat 的
config
目录，找到名为
napcat_<你的QQ号>.json
的文件，如
napcat_1234567.json
。
配置内容参数解释：
napcat_xxxx.json
json5
{
// 是否开启文件日志
"fileLog"
:
true
,
// 是否开启控制台日志
"consoleLog"
:
true
,
// 日志等级, 可选值: debug, info, error
"fileLogLevel"
:
"debug"
,
"consoleLogLevel"
:
"info"
,
"packetServer"
:
""
}
最后编辑于 3 个月前
查看完整历史
b1575a2
-
docs：update docs (
#119
)
d4b0b10
-
Update WebUI login and setup instructions
420c967
-
在中文、英文以及数字混排时添加空格分隔
#2
4c401e3
-
在中文、英文以及数字混排时添加空格分隔
45fefe0
-
feat(basic/shell):新增了关于TUI-CLI的描述，展开linux一键部署的演示代码
1e638c3
-
feat: 更新文档
94541f0
-
fix
2322fa5
-
更新 WebUI 配置教程
97dfb17
-
fix
feb0401
-
增加 webui.json 文件路径说明
a7abe1b
-
Update basic.md
7cc1aa8
-
Update basic.md
e5d7b0b
-
Update basic.md
2332813
-
fix
fb7e193
-
fix
cf24609
-
fix
4c1cf88
-
fix
0cfe0f0
-
fix
7711e1b
-
fix
9b95cb4
-
fix
578710d
-
fix
5c7106e
-
update: new docs
3095ca5
-
fix
ac82f49
-
重构文档
a98431c
-
feat: support macOS
3a439a7
-
Update basic.md
a4c0f64
-
Update basic.md
8a5648c
-
Update basic.md
3433791
-
Update basic.md
a5137b3
-
Update basic.md
41e5e80
-
rearrange directory structure
73d5253
-
docs: 增加配置https的方案
670d937
-
improve docs behavior
78a3336
-
fix
e1a2208
-
docs: config change
34ea1d2
-
doc: 大量文字表述上的修改，使表意更加明确
524e75b
-
doc: update
ee33ffa
-
doc: update
dd72b4f
-
doc: update
8638068
-
fix
402edb6
-
fix
在 GitHub 上编辑此页面
最后更新于:
Pager
上一页
Framework
下一页
高级配置
[result-id: r13]


OneBot 网络基础 | NapCatQQ
Skip to content
NapCatQQ
Search
K
Main Navigation
快速开始
关于
主题
菜单
回到顶部
Sidebar Navigation
快速开始
目录导航
什么是 NapCatQQ
启动方式
安装方式
Shell
Framework
配置
基础配置
高级配置
使用
接入框架
社区资源
开发
请求接口
上报事件
消息类型
处理文件
插件开发
插件机制原理
快速开始
项目结构
配置与 WebUI
进阶功能
热重载开发
发布插件
API 参考
API 文档
类型定义
完整接口定义
接口
类型
API 文档
版本选择
协议
协议概述
网络通讯
事件基础结构
事件字段详情
接口基础接口
消息元素定义
差异实现说明
其余
喵喵
安全
联系
页面导航
OneBot 网络基础

字数
1098 字
阅读时间
5 分钟
本章节介绍 NapCatQQ 与 OneBot 11 进行 HTTP 和 WebSocket 通信的基本方式。请根据 NapCatQQ 的实际部署角色选择合适的通信模式。
1. HTTP 通信

OneBot 11 的 HTTP 通信分为两种角色：
HTTP 客户端
：NapCatQQ 作为客户端，向 OneBot 11 的 HTTP API 主动发送请求（如发送消息）。
HTTP 服务器
：NapCatQQ 作为服务器，接收 OneBot 11 推送的事件（event push）。
1.1 NapCatQQ 作为 HTTP 客户端发送请求

NapCatQQ 可以通过 HTTP POST 请求向 OneBot 11 的 API 地址发送指令。
示例：发送私聊消息
http
POST
http://<host>:<port>/send_private_msg
Content-Type
:
application/json
{
"user_id"
:
123456789
,
"message"
:
"你好，NapCatQQ！"
}
返回示例：
json
{
"status"
:
"ok"
,
"retcode"
:
0
,
"data"
: {
"message_id"
:
1234
}
}
代码演示：Python HTTP 客户端发送 API 请求
python
import
requests
url
=
"http://<host>:<port>/send_private_msg"
payload
=
{
"user_id"
:
123456789
,
"message"
:
"你好，NapCatQQ！"
}
resp
=
requests.post(url,
json
=
payload)
print
(resp.json())
🐱💻 小贴士：别忘了替换
<host>:<port>
为实际的 OneBot 11 地址哦！如果遇到连接失败，记得检查防火墙和 API 是否开启。
1.2 NapCatQQ 作为 HTTP 服务器接收事件

要接收事件，需要配置 OneBot 11 的 HTTP 上报（event push），即让 OneBot 11 向 NapCatQQ 指定的 HTTP 服务器推送事件数据。NapCatQQ 需要实现一个 HTTP 服务器，监听 POST 请求，解析收到的 JSON 数据。
事件推送示例：
json
{
"post_type"
:
"message"
,
"message_type"
:
"private"
,
"user_id"
:
123456789
,
"message"
:
"你好"
}
代码演示：Python HTTP 服务器接收事件
python
from
flask
import
Flask, request
app
=
Flask(
__name__
)
@app.route
(
"/"
,
methods
=
[
"POST"
])
def
receive_event
():
event
=
request.json
print
(
"收到事件："
, event)
return
"OK"
if
__name__
==
"__main__"
:
app.run(
port
=
8080
)
🐱👓 小提醒：Flask 默认监听 127.0.0.1，如需外部访问请加
host="0.0.0.0"
。别忘了安装 Flask：
pip install flask
！
2. WebSocket 通信

WebSocket 通信同样分为两种角色：
WebSocket 客户端
：NapCatQQ 作为客户端，主动连接 OneBot 11 的 WebSocket 服务端，进行双向通信。
WebSocket 服务器
：NapCatQQ 作为服务器，OneBot 11 作为客户端主动连接 NapCatQQ 的 WebSocket 服务端，推送事件和处理请求。
2.1 NapCatQQ 作为 WebSocket 客户端

NapCatQQ 通过 WebSocket 连接到 OneBot 11 的 ws 或 wss 地址。连接建立后，发送 JSON 格式的事件和处理请求。
发送群消息示例：
json
{
"action"
:
"send_group_msg"
,
"params"
: {
"group_id"
:
123456
,
"message"
:
"大家好！"
},
"echo"
:
"自定义标识"
}
响应示例：
json
{
"status"
:
"ok"
,
"retcode"
:
0
,
"data"
: {
"message_id"
:
5678
},
"echo"
:
"自定义标识"
}
事件推送示例：
json
{
"post_type"
:
"message"
,
"message_type"
:
"group"
,
"group_id"
:
123456
,
"user_id"
:
654321
,
"message"
:
"你好"
}
代码演示：Python WebSocket 客户端接收事件
python
import
asyncio
import
websockets
import
json
async
def
main
():
uri
=
"ws://<host>:<port>/"
async
with
websockets.connect(uri)
as
ws:
# 发送请求
req
=
{
"action"
:
"send_group_msg"
,
"params"
: {
"group_id"
:
123456
,
"message"
:
"大家好！"
},
"echo"
:
"test"
}
await
ws.send(json.dumps(req))
# 接收响应或事件
while
True
:
msg
=
await
ws.recv()
print
(
"收到消息："
, msg)
asyncio.run(main())
🐱🚀 温馨提示：记得安装 websockets 库：
pip install websockets
。WebSocket 地址要写对，wss 代表加密连接哦！
2.2 NapCatQQ 作为 WebSocket 服务器接收事件和请求

NapCatQQ 也可以实现 WebSocket 服务器，让 OneBot 11 作为客户端主动连接 NapCatQQ 的服务器。连接建立后，OneBot 11 会通过该连接推送事件和接收 NapCatQQ 的请求。NapCatQQ 需要处理来自 OneBot 11 的消息，并根据需要发送请求。
代码演示：Python WebSocket 服务器接收事件和请求
python
import
asyncio
import
websockets
async
def
handler
(websocket, path):
async
for
message
in
websocket:
print
(
"收到消息："
, message)
# 可根据需要回复消息
# await websocket.send(...)
start_server
=
websockets.serve(handler,
"0.0.0.0"
,
8765
)
asyncio.get_event_loop().run_until_complete(start_server)
asyncio.get_event_loop().run_forever()
🐱🏍 小技巧：服务器监听
0.0.0.0
可让外部设备访问。别忘了端口不要被占用，否则会启动失败！
总结

HTTP 支持 NapCatQQ 作为客户端（主动请求）和服务器（被动接收事件）两种模式。
WebSocket 支持 NapCatQQ 作为客户端（主动连接 OneBot 11）和服务器（被动接收 OneBot 11 连接）两种模式，推荐优先使用 WebSocket，实时性更好。
🐾 最后提醒：接口字段、端口、地址等都要和实际环境对应，小粗心是不行的！
最后编辑于 11 个月前
查看完整历史
2c2ecef
-
fix
cb48f6d
-
feat
在 GitHub 上编辑此页面
最后更新于:
Pager
上一页
协议概述
下一页
事件基础结构
[result-id: r14]


Linux 系统设置开机自启动步骤 | NapCatQQ
Skip to content
NapCatQQ
Search
K
Main Navigation
快速开始
关于
主题
菜单
回到顶部
Sidebar Navigation
快速开始
目录导航
什么是 NapCatQQ
启动方式
安装方式
Shell
Framework
配置
基础配置
高级配置
使用
接入框架
社区资源
开发
请求接口
上报事件
消息类型
处理文件
插件开发
插件机制原理
快速开始
项目结构
配置与 WebUI
进阶功能
热重载开发
发布插件
API 参考
API 文档
类型定义
完整接口定义
接口
类型
API 文档
版本选择
协议
协议概述
网络通讯
事件基础结构
事件字段详情
接口基础接口
消息元素定义
差异实现说明
其余
喵喵
安全
联系
页面导航
Linux 系统设置开机自启动步骤

字数
483 字
阅读时间
3 分钟
本步骤适用于 Ubuntu 系统，24.04 版本测试通过。其它版本未测试。
步骤1：创建服务文件

打开终端，运行以下命令创建一个新的 systemd 服务文件：
bash
sudo
nano
/etc/systemd/system/napcat.service
步骤2：编辑服务文件

在文件中添加以下内容：
markdown
[
Unit
]
Description=Napcat Service
After=network.target
[
Service
]
User=root
ExecStart=/usr/bin/screen -dmS napcat /usr/bin/bash -c "/usr/bin/xvfb-run -a qq --no-sandbox"
RemainAfterExit=yes
Type=oneshot
[
Install
]
WantedBy=multi-user.target
确保使用绝对路径来执行命令，以避免路径相关的问题。
步骤3：保存并关闭文件

按下
Ctrl + O
保存，
Ctrl + X
关闭 nano 编辑器。
步骤4：重新加载 systemd 守护进程

更新 systemd，以使其识别新创建的服务文件：
bash
sudo
systemctl
daemon-reload
步骤5：启用服务

将服务启用以便在启动时运行：
bash
sudo
systemctl
enable
napcat.service
步骤6：验证服务状态

检查服务是否已正确启用：
bash
sudo
systemctl
status
napcat.service
可选步骤：立即启动服务（测试用）

如果想在当前会话中测试服务，可以运行：
bash
sudo
systemctl
start
napcat.service
然后，检查 screen 会话是否存在：
bash
screen
-ls
你应该会看到名为
napcat
的会话。
注意事项

用户权限
：在服务文件中指定正确的
User
，确保程序以正确的用户权限运行。
绝对路径
：使用绝对路径（如
/usr/bin/screen
）确保命令能正确执行。
依赖关系
：如果命令依赖于特定的网络或其他服务，可能需要调整
After
部分。
日志检查
：如果服务没有按预期运行，可以查看日志：
journalctl -u napcat.service -b
，这里的
-b
显示上次启动时的日志。
最后编辑于 10 个月前
查看完整历史
4c401e3
-
在中文、英文以及数字混排时添加空格分隔
d10397c
-
新增Ubuntu设置开机自启动步骤文档
在 GitHub 上编辑此页面
最后更新于:
Pager
下一页
目录导航
[result-id: r15]


curl -sL "https://napneko.github.io/guide/install" 2>/dev/null | python3 -c "
import sys, re
html = sys.stdin.read()
text = re.sub(r'<script[^>]*>.*?</script>', '', html, flags=re.S)
text = re.sub(r'<style[^>]*>.*?</style>', '', text, flags=re.S)
text = re.sub(r'<[^>]+>', '\n', text)
text = re.sub(r'\n{3,}', '\n\n', text)
text = re.sub(r'^\s+', '', text, flags=re.M)
print(text[:6000])
"

Fetch NapCat install guide page


curl -sL "https://napneko.github.io/config/advanced" 2>/dev/null | python3 -c "
import sys, re
html = sys.stdin.read()
text = re.sub(r'<script[^>]*>.*?</script>', '', html, flags=re.S)
text = re.sub(r'<style[^>]*>.*?</style>', '', text, flags=re.S)
text = re.sub(r'<[^>]+>', '\n', text)
text = re.sub(r'\n{3,}', '\n\n', text)
text = re.sub(r'^\s+', '', text, flags=re.M)
print(text[:5000])
"

Fetch NapCat advanced configuration docs


NapCat | NapCatQQ
Skip to content
NapCatQQ
Search
K
Main Navigation
快速开始
关于
主题
菜单
回到顶部
Sidebar Navigation
快速开始
目录导航
什么是 NapCatQQ
启动方式
安装方式
Shell
Framework
配置
基础配置
高级配置
使用
接入框架
社区资源
开发
请求接口
上报事件
消息类型
处理文件
插件开发
插件机制原理
快速开始
项目结构
配置与 WebUI
进阶功能
热重载开发
发布插件
API 参考
API 文档
类型定义
完整接口定义
接口
类型
API 文档
版本选择
协议
协议概述
网络通讯
事件基础结构
事件字段详情
接口基础接口
消息元素定义
差异实现说明
其余
喵喵
安全
联系
页面导航
NapCat

字数
320 字
阅读时间
2 分钟
粗略安装流程

安装
对应版本
的 NTQQ（特殊情况部分可能安装方式已代为安装）。
下载你需要的 NapCat 版本（特殊情况部分可能安装方式包含 NapCat 本体）。
遵照其详细教程启动 NapCat 本体。
进入 WebUI，启动你需要的 HTTP/WS 客户端与服务端。
配置框架或者独立插件连接 NapCat。
启动方式

NapCat 有着众多启动方式，每种方式各有优点：
Shell 版本
：具有低内存、服务器部署简单的特点。
Framework 版本
：具有方便人机交互、便于窥屏的特点。
悄悄话: 我还是推荐你用 Shell 的，毕竟~~~
Shell 启动/安装方式

推荐教程：
方法 1 - 使用命令行启动
Linux 手动配置教程：
方法 2 - Linux 手动配置
Framework 启动/安装方式

推荐教程：
方法 1 - 作为 LiteLoader 插件启动
原生使用 NapCatQQ 启动（由于启动方式变更，暂不提供教程）
体验一下 一键安装 神秘教程？

在线体验
最后编辑于 5 个月前
查看完整历史
3270e4c
-
更改了Shell安装方式的方法排序
3b5563a
-
fix
7d8f1b9
-
fix
4c401e3
-
在中文、英文以及数字混排时添加空格分隔
52db183
-
Bootway03 补充/修正
109e6a0
-
fix
c8cd7ca
-
feat: 文档简化
在 GitHub 上编辑此页面
最后更新于:
Pager
上一页
什么是 NapCatQQ
下一页
Shell
[result-id: r16]


高级配置 | NapCatQQ
Skip to content
NapCatQQ
Search
K
Main Navigation
快速开始
关于
主题
菜单
回到顶部
Sidebar Navigation
快速开始
目录导航
什么是 NapCatQQ
启动方式
安装方式
Shell
Framework
配置
基础配置
高级配置
使用
接入框架
社区资源
开发
请求接口
上报事件
消息类型
处理文件
插件开发
插件机制原理
快速开始
项目结构
配置与 WebUI
进阶功能
热重载开发
发布插件
API 参考
API 文档
类型定义
完整接口定义
接口
类型
API 文档
版本选择
协议
协议概述
网络通讯
事件基础结构
事件字段详情
接口基础接口
消息元素定义
差异实现说明
其余
喵喵
安全
联系
页面导航
高级配置

字数
705 字
阅读时间
3 分钟
配置 FFmpeg

自 v4.4.11 起无需配置 FFmpeg 可享受音视频处理，除了手动安装的 Linux 用户。
FFmpeg 是什么？

FFmpeg
是知名的开源音视频处理库，被用于许多音视频编解码相关的项目中。
为什么要使用 FFmpeg？

本项目使用 FFmpeg 是为了编解码语音和视频，以使 NapCat 以 QQ 支持的格式处理语音和视频文件。
如果你的 Bot 没有处理语音和视频的需求，可以选择不安装 FFmpeg。
安装 FFmpeg

Windows 系统

在
此处
下载 ffmpeg-master-latest-win64-gpl.zip；
将其中的文件夹解压至一个你知道的地方（例如
C:\Program Files
），然后重命名为
ffmpeg
；
你的
ffmpeg
文件夹的结构看起来应该是这样的：
text
ffmpeg
|___bin
|___|___ffmpeg.exe
|___|___ffplay.exe
|___\___ffprobe.exe
|___doc
|___\ ...
|___LICENSE
\___README.txt
注意
请一定要保证
bin
文件夹内同时包含
ffmpeg.exe
、
ffplay.exe
以及
ffprobe.exe
！
否则会产生意想不到的错误。
添加 bin 目录到系统环境变量，不会可以搜索系统设置环境变量
注意安装完成后可能需要
重启
如果有其他程序也需要使用 FFmpeg
如果其他程序支持手动选择 FFmpeg 位置，只需配置为 NapCat 所使用的 FFmpeg 即可。
如果其他程序不支持手动选择 FFmpeg 位置，只需将 FFmpeg 的
bin
目录注册到系统的
PATH
变量中（可参考
此教程
）即可。
如果你将 FFmpeg 安装到了系统变量中，那么无论有没有在 NapCat 中配置 FFmpeg 路径也可以正常使用 FFmpeg。
Linux 系统

请使用你所使用的系统的包管理器直接安装
ffmpeg
即可正常使用。
MacOS 系统

由于系统存在沙盒机制，无法运行外部程序，因此暂不支持。
配置 PacketBackend

这是干什么的?

这是用来提供 NTQQ 本身没有的功能的 DLC，以下配置方式二选一即可。
配置 PacketBackend (Native)

TIP
NapCat v3.6.0 及以后的版本在 Linux 平台 (amd64, arm64)，MacOS平台(amd64, arm64)，Windows平台 (amd64)
已内置 PacketBackend 实现
，您
无需进行额外的配置
即可享受 DLC 的欢乐 (/≧▽≦)/
当前支持版本

平台版本
Native
Windows Amd64 28418-36580
✅
Linux Amd64 28498-36580
✅
Linux Arm64 28498-36580
✅
MacOS Arm64 29456-29456
✅
MacOS Amd64 29456-29456
✅
扩展进度

支持
功能
✅
设置群头衔
✅
发送 poke
✅
独立 Rkey 获取
✅
陌生人状态获取
✅
伪造合并转发
✅
文件直链获取
✅
MarkDown
✅
群签到
✅
小程序卡片分享
✅
AI 声聊
✅
高性能 OCR
最后编辑于 9 个月前
查看完整历史
7ec1ed6
-
fix
420c967
-
在中文、英文以及数字混排时添加空格分隔
#2
4c401e3
-
在中文、英文以及数字混排时添加空格分隔
f40204e
-
fix
3b6deae
-
feat: 版本
1110d72
-
feat:33800
abde249
-
fix
dfa8bb4
-
fix
edc4b4b
-
fix
f3cd13c
-
fix
c2d04fb
-
fix
5336215
-
fix
v4.2.29
80d9896
-
fix: 30483
c7b9215
-
30366
c218bea
-
29927
783e7c5
-
MacOS amd64 adapt
4a10b2a
-
fix
f80e6f3
-
fix
907eb77
-
backend info sync
f89f642
-
fix
a14db30
-
fix
f2aa4c1
-
make mac happy
bebc80e
-
fix: 更新 文档
1aabe7b
-
arm64
068c6ae
-
simplify
6004948
-
simplify
1e74692
-
feat: PacketBackend
ef83623
-
fix
4651043
-
fix
f492585
-
fix
6a29533
-
fix
850a447
-
fix
b09dd8d
-
feat: MacOS
d90a798
-
feat: 抬高兼容版本
fdca1a2
-
fix
953a7f8
-
feat: docs
f93a7bf
-
fix: typo
78e19de
-
fix
1967199
-
style lint
09c765c
-
fix
b423203
-
fix
c060565
-
[*] 修复高级配置标题层级错误
7333f88
-
fix
8a39176
-
fix
604f554
-
fix
37f2e02
-
fix
e7563e4
-
fix: 显示
ac82f49
-
重构文档
a98431c
-
feat: support macOS
de3f9ab
-
fix
e79395f
-
chore: docs - 修改文档目录关系 - 修改兼容性情况 - 优化零碎的教程
41e5e80
-
rearrange directory structure
670d937
-
improve docs behavior
f3c3338
-
fix
e9f9949
-
init
在 GitHub 上编辑此页面
最后更新于:
Pager
上一页
基础配置
下一页
接入框架
[result-id: r17]


Here is a comprehensive summary of installing and configuring NapCatQQ on a headless Linux server without Docker, based on the official documentation at napneko.github.io and the GitHub repo.

---

## 1. Latest Installation Method for Headless Linux (No GUI, No Docker)

There are three recommended approaches for Linux without Docker. The **NapCat Installer script** is the easiest; the **semi-automatic method** gives you full control.

### Option A: NapCat Installer Script (Recommended)

A one-line installer that handles QQ installation, NapCat setup, and dependencies automatically:

```bash
curl -o napcat.sh https://nclatest.znin.net/NapNeko/NapCat-Installer/main/script/install.sh && bash napcat.sh
```

Additional modes:
- **TUI visual install** (for SSH/headless): `bash napcat.sh --tui`
- **Force reinstall (Shell, no Docker)**: `bash napcat.sh --docker n --cli n --proxy 0 --force`
- **With TUI-CLI tool** (for CLI-based config management): `bash napcat.sh --docker n --cli y`

After install, run `sudo napcat` to access the TUI-CLI interface for configuration.

### Option B: Linux Launcher (Non-invasive)

Does not modify NTQQ's own files; cache and NapCat live in the current working directory:

```bash
curl -o napcat.sh https://raw.githubusercontent.com/NapNeko/napcat-linux-installer/refs/heads/main/install.sh && bash napcat.sh
```

### Option C: Semi-Automatic Manual Install (Full Control)

Step-by-step:

**1. Install QQ (version 28060+) and xvfb/xauth:**

```bash
# Debian/Ubuntu:
sudo apt install xvfb xauth

# Fedora/CentOS Stream:
sudo dnf install xorg-x11-server-Xvfb xorg-x11-xauth

# Arch:
sudo pacman -S xorg-server-xvfb
```

Important note: RHEL 10+ / CentOS Stream 10+ have completely removed X11, so xvfb will not work there. AlmaLinux 10 is an exception.

**2. Create the loadNapCat.cjs hook file:**

```bash
cat > /opt/QQ/resources/app/loadNapCat.cjs << 'EOF'
const fs = require("fs");
const path = require("path");
const CurrentPath = path.dirname(__filename);
const hasNapcatParam = process.argv.includes("--no-sandbox");
if (hasNapcatParam) {
  (async () => {
    await import("file://" + path.join(CurrentPath, "./napcat/napcat.mjs"));
  })();
} else {
  require("./application/app_launcher/index.js");
  setTimeout(() => {
    global.launcher.installPathPkgJson.main = "./application.asar/app_launcher/index.js";
  }, 0);
}
EOF
```

**3. Install NapCat Shell into QQ's app directory:**

Download `NapCat.Shell.zip` from the [Releases page](https://github.com/NapNeko/NapCatQQ/releases/) and extract it so that `/opt/QQ/resources/app/napcat/napcat.mjs` exists.

**4. Patch package.json:**

```bash
chmod +777 /opt/QQ
sed -i 's/"main": ".*\/index.js"/"main": ".\/loadNapCat.cjs"/' /opt/QQ/resources/app/package.json
```

**5. Launch:**

```bash
xvfb-run -a qq --no-sandbox -q <your_QQ_number>
```

**6. (Optional) Systemd service for auto-start:**

Create `/etc/systemd/system/napcat.service`:

```ini
[Unit]
Description=Napcat QQ Server
Documentation=https://napneko.github.io/guide
After=network.target

[Service]
User=<your_user>
Restart=on-failure
WorkingDirectory=<your_home_dir>
ExecStart=/usr/bin/xvfb-run -a qq --no-sandbox -q <your_QQ_number>

[Install]
WantedBy=multi-user.target
```

Then: `sudo systemctl enable napcat.service --now`

---

## 2. WebUI / CLI Login Support

**Yes, NapCat supports WebUI login on headless servers.** This is the primary way to manage it remotely:

- The WebUI starts automatically with NapCat. Default address: `0.0.0.0`, default port: `6099`.
- On startup, the log shows a URL like: `[info] [NapCat] [WebUi] WebUi User Panel Url: http://127.0.0.1:6099/webui?token=xxxxx`
- The token is also stored in `webui.json` (for Installer-based installs, at `/opt/QQ/resources/app/app_launcher/napcat/config/webui.json`).

**webui.json configuration:**

```json
{
  "host": "0.0.0.0",   // WebUI listen address
  "port": 6099,         // WebUI port
  "token": "xxxx",      // Login key (auto-generated random password)
  "loginRate": 3        // Login attempts per minute limit
}
```

**Login flow:**
1. Access `http://<server_ip>:6099/webui/`
2. Click QRCode to log in via QQ scan
3. After scanning, the WebUI token refreshes -- check the console log or your phone QQ messages for the new token
4. On first login, you are forced to change the password
5. After login, configure network (HTTP/WS) through the WebUI

**TUI-CLI alternative:** If you installed via the Installer with `--cli y`, you can run `sudo napcat` in the terminal for a terminal-based visual configuration interface, useful when WebUI is hard to access.

---

## 3. WebSocket Configuration

NapCat supports four network types. For connecting a local service, you typically use **WebSocket Server (Forward WS)** or **WebSocket Client (Reverse WS)**.

### WebSocket Server (Forward WS) -- NapCat listens, your service connects to it

```json
{
  "network": {
    "httpServers": [],
    "httpClients": [],
    "websocketServers": [
      {
        "name": "WsServer",
        "enable": true,
        "host": "0.0.0.0",
        "port": 3001,
        "messagePostFormat": "array",
        "reportSelfMessage": false,
        "token": "",
        "enableForcePushEvent": true,
        "debug": false,
        "heartInterval": 30000
      }
    ],
    "websocketClients": []
  },
  "musicSignUrl": "",
  "enableLocalFile2Url": false,
  "parseMultMsg": false
}
```

Your local service connects to `ws://localhost:3001`.

### WebSocket Client (Reverse WS) -- NapCat connects to your service

```json
{
  "network": {
    "httpServers": [],
    "httpClients": [],
    "websocketServers": [],
    "websocketClients": [
      {
        "name": "WsClient",
        "enable": true,
        "url": "ws://localhost:8082",
        "messagePostFormat": "array",
        "reportSelfMessage": false,
        "reconnectInterval": 5000,
        "token": "",
        "debug": false,
        "heartInterval": 30000
      }
    ]
  },
  "musicSignUrl": "",
  "enableLocalFile2Url": false,
  "parseMultMsg": false
}
```

NapCat will connect to your service at `ws://localhost:8082`.

### Configuration file locations

- Default config: `./config/onebot11_<QQ_number>.json` (per-account)
- Generic default: `./config/onebot11.json` (v4.5.3+)
- For Installer-based installs: `/opt/QQ/resources/app/app_launcher/napcat/config/`
- You can also configure via the WebUI (recommended) or TUI-CLI.

---

## 4. Prerequisites

| Requirement | Details |
|---|---|
| **QQ (NTQQ)** | Version 28060+ must be installed. The Installer script handles this automatically. |
| **QQ Account** | You need a QQ account. First login requires scanning a QR code with the QQ mobile app. After that, the `-q <QQ_number>` flag enables quick login without re-scanning. |
| **xvfb + xauth** | Required for headless operation (virtual framebuffer). Install via your package manager. Not needed on RHEL10+/CentOS Stream 10+ (X11 removed). |
| **FFmpeg** | Optional. Only needed for voice/video processing. On Linux, install via package manager: `sudo apt install ffmpeg`. NapCat v4.4.11+ includes FFmpeg support by default, except for manual Linux installs. |
| **PacketBackend** | Built-in since v3.6.0 on Linux amd64/arm64. Provides extra features like group title setting, poke, OCR, file direct links, etc. No extra configuration needed. |
| **Node.js** | Included with NapCat Shell; no separate install needed. |

**Important first-time login note:** Even with systemd auto-start, the first login requires scanning a QR code via the WebUI or console. After successful first login, subsequent starts can use quick login (`-q <QQ_number>`).

---

**Key sources:**
- Official docs: https://napneko.github.io/
- GitHub repo: https://github.com/NapNeko/NapCatQQ
- Releases: https://github.com/NapNeko/NapCatQQ/releases/
- Installer repo: https://github.com/NapNeko/NapCat-Installer
- Linux Launcher repo: https://github.com/NapNeko/napcat-linux-installer