NapCat 通过 OneBot v11 接入 AstrBot。顺序是先在 AstrBot 里创建适配器,再部署 NapCat,最后在 NapCat 里填 WebSocket 地址。
1. 在 AstrBot 中创建 OneBot v11 适配器
打开 AstrBot WebUI,进入「机器人 → 创建机器人」:
创建适配器
创建机器人
消息平台类别选
OneBot v11,机器人名称填qq。填写反向 WebSocket
反向 WebSocket 主机填
0.0.0.0,端口填6199,Token 留空。
消息平台类别 OneBot v11,反向 WebSocket 主机 0.0.0.0,端口 6199 保存并启用
保存后回到机器人列表,确认
qq处于运行中。NapCat 后面连的就是这个6199。
qq 使用 aiocqhttp,反向 WebSocket 端口 6199
2. 部署 NapCat
2.1 Windows 部署
Windows 上不只有一个包,先按用途选:
| 包 / 工具 | 运行方式 | 需要预装 | 和日常 QQ 的关系 | 适合 |
|---|---|---|---|---|
NapCat.Framework | 以插件/注入方式挂到已安装的 QQNT | QQNT | 共用桌面 QQ 的登录态 | 已经有桌面 QQ,想直接复用 |
NapCat.Shell | 独立无头进程 | 自己装 QQ + Node.js | 独立 | Linux/Docker、手动部署 |
NapCat.Shell.Windows.Node | 自带 QQ + 便携 Node 的整合包 | 无 | 独立于日常 QQ | Windows 想解压即用 |
NapCat.Shell.Windows.OneKey | 一键安装器,生成 NapCat.XXXX.Shell | 无,安装器会准备 | 取决于版本,可能和桌面 QQ 共用 | Windows 想按向导安装 |
| NapCatQQ Desktop | 单 EXE 图形管理器 | 由工具引导安装 | 取决于底层 NapCat | Windows 桌面用户,推荐 |
方式一:Windows OneKey
Windows OneKey 启动
下载并解压
下载
NapCat.Shell.Windows.OneKey.zip,解压到普通目录,不要放Program Files或需要管理员权限的路径。运行安装器
双击
NapCatInstaller.exe,等待它生成NapCat.XXXX.Shell文件夹。首次运行需要联网准备文件。启动 NapCat
进入
NapCat.XXXX.Shell,双击napcat.bat。控制台会打印 WebUI Token。登录 WebUI 和 QQ
浏览器打开
http://127.0.0.1:6099,用日志里的 Token 登录,扫码登录 QQ。下一步
Windows 上的 NapCat 和 AstrBot 通常不在同一 Docker 网络,WebSocket 地址见 不同网络下的 OneBot WebSocket 通信。
方式二:NapCatQQ Desktop(推荐)
NapCatQQ Desktop
下载单文件工具
下载
NapCatQQ-Desktop的 EXE。它不依赖额外运行库,双击即可打开。按引导准备环境
在工具里按引导安装或选择 QQ 与 NapCat;它会自动检测环境并给出安装入口。
启动账号
新建或选择账号,启动 NapCat,扫码登录 QQ。托盘可以后台托管,多账号在左侧切换。
下一步
Windows 上的 NapCat 和 AstrBot 通常不在同一 Docker 网络,WebSocket 地址见 不同网络下的 OneBot WebSocket 通信。
2.2 Linux Docker 部署
方式一:1Panel 容器部署
创建 NapCat 容器
基本信息
1Panel 里进入「容器 → 创建容器」,镜像填
mlikiowa/napcat-docker:latest,名称填napcat,重启策略选always。端口
映射
6099给 NapCat WebUI。3000/3001是 OneBot HTTP/WS 服务,用反向 WS 接入 AstrBot 时可以不映射。环境变量
NAPCAT_UID=0NAPCAT_GID=0如果服务器用非 root 用户运行 Docker,把
0换成id -u/id -g的实际值。挂载
/opt/astrbot/napcat/config→/app/napcat/config:NapCat 配置/opt/astrbot/ntqq→/app/.config/QQ:QQ 数据astrbot-data→/AstrBot/data:共享 AstrBot 数据,发文件时才能读到
在 NapCat 容器的「网络」里选择 AstrBot 容器所在的网络,例如 astrbot_astrbot-network。同一网络不需要主机映射,也不用暴露 AstrBot 的 6199。

方式二:Docker Compose 部署
部署 NapCat
保存 NapCat 配置
同一网络不需要改 AstrBot 的
ports,6199只在容器网络内部使用。services:napcat:image: mlikiowa/napcat-docker:latestcontainer_name: napcatrestart: alwaysenvironment:- NAPCAT_UID=0- NAPCAT_GID=0ports:- "6099:6099"volumes:- ./napcat/config:/app/napcat/config- ./ntqq:/app/.config/QQ- astrbot-data:/AstrBot/datanetworks:- astrbot-networknetworks:astrbot-network:external: truename: astrbot_astrbot-network # 改成 AstrBot 实际使用的网络名volumes:astrbot-data:external: true保存为
/opt/astrbot/compose.napcat.yml。启动
Terminal window cd /opt/astrbotdocker compose -f compose.napcat.yml up -d
方式三:AstrBot + NapCat 一起部署
如果还没有单独部署 AstrBot,可以直接用一份 Compose 把两者一起拉起。两个容器都在 astrbot-network,共享 astrbot-data,6199 不映射到宿主机。
一起部署
保存配置
services:astrbot:image: soulter/astrbot:latestcontainer_name: astrbotrestart: alwayssecurity_opt:- no-new-privileges:trueports:- "6185:6185" # AstrBot WebUIenvironment:- TZ=Asia/Shanghaivolumes:- astrbot-data:/AstrBot/data- /etc/localtime:/etc/localtime:ronetworks:- astrbot-networknapcat:image: mlikiowa/napcat-docker:latestcontainer_name: napcatrestart: alwaysenvironment:- NAPCAT_UID=0- NAPCAT_GID=0ports:- "3000:3000"- "3001:3001"- "6099:6099" # NapCat WebUIvolumes:- ./napcat/config:/app/napcat/config- ./ntqq:/app/.config/QQ- astrbot-data:/AstrBot/datanetworks:- astrbot-networknetworks:astrbot-network:driver: bridgevolumes:astrbot-data:name: astrbot-data保存为
/opt/astrbot/compose.napcat.yml。启动
Terminal window cd /opt/astrbotdocker compose -f compose.napcat.yml up -d
3. 配置 NapCat WebSocket
NapCat 启动并登录 QQ 后,在 NapCat WebUI 里新建 WebSocket 客户端。同一网络填:
ws://astrbot:6199/ws添加 WebSocket 客户端
新建客户端
打开 NapCat WebUI,进入「网络配置 → 新建 → Websocket客户端」。

在网络配置里新建 Websocket客户端 填写名称和 URL
名称填
astrbot,URL 填ws://astrbot:6199/ws,Token 留空。保存并启用
保存后确认客户端处于启用状态。
同一网络的填写示例:

4. 登录 NapCat
登录 NapCat
获取 Token
浏览器打开
http://<服务器IP>:6099/webui。登录用的 Token 在容器日志里:Terminal window docker logs napcat 2>&1 | grep -i -E "webui|token"也可以到挂载出来的
./napcat/config/webui.json里找token字段。
红框中是带 token 的 WebUI 地址,token 就是登录凭证 截图中的 Token 仅作示例,请以自己日志里的值为准。
登录 WebUI
把日志里的 Token 填进 WebUI:

在 Token 输入框填入日志里的 WebUi Token 扫码登录 QQ
如果 QQ 还没登录,NapCat 会要求扫码:

用手机 QQ 扫描二维码完成登录 登录成功后进入 NapCat 面板:

在基础信息里确认 NapCat 版本、QQ 版本和运行状态
5. 验证连接
验证连接
看 NapCat 日志
日志里出现反向 WebSocket 已启动,说明客户端在尝试连接。

日志里能看到 WebSocket 反向服务已启动 看 AstrBot 日志
出现下面这行,说明连接成功:
aiocqhttp(OneBot v11) 适配器已连接。
看到 aiocqhttp(OneBot v11) 适配器已连接即可 发一条测试消息
在 QQ 里私聊机器人发一条消息,AstrBot 日志出现
收到 ... 测试,说明消息已经从 NapCat 送到 AstrBot:
日志里出现「收到 ... 测试」,说明消息发送成功 如果下面还提示
未找到任何对话模型(提供商),只说明还没配置模型,不影响这次连接验证;配置好模型后再发消息就能收到回复。
常见问题
NapCat 日志一直提示连接失败
检查两个容器是不是在同一个网络,URL 里的 astrbot 必须能解析成 AstrBot 容器。不在同一网络时见 不同网络下的 OneBot WebSocket 通信。
AstrBot 和 NapCat 一起部署时出现 Network 错误
检查 compose 里的网络名是否和 AstrBot 实际使用的网络一致;同一份 compose 里的两个服务必须加入同一个网络。
AstrBot 提示 Token 不匹配
AstrBot 的反向 WebSocket Token 和 NapCat 的 WebSocket 客户端 Token 必须一致;不想校验就两边都留空。
NapCat 发文件时提示找不到文件
AstrBot 和 NapCat 没有共享 astrbot-data;两个容器都要把同一个卷挂到 /AstrBot/data。
6199 要不要开放到公网
不要。同一网络不需要映射;跨网络的做法见 不同网络下的 OneBot WebSocket 通信,且只放行客户端 IP。
分享文章
生成精美分享图或复制链接,与更多人分享本文。
继续阅读
换条路线
从其他文章中稳定抽取