2137 字
11 分钟
AstrBot 接入 QQ:NapCat(OneBot v11)

NapCat 通过 OneBot v11 接入 AstrBot。顺序是先在 AstrBot 里创建适配器,再部署 NapCat,最后在 NapCat 里填 WebSocket 地址。

1. 在 AstrBot 中创建 OneBot v11 适配器#

打开 AstrBot WebUI,进入「机器人 → 创建机器人」:

创建适配器

  1. 创建机器人

    消息平台类别选 OneBot v11,机器人名称填 qq。

  2. 填写反向 WebSocket

    反向 WebSocket 主机填 0.0.0.0,端口填 6199,Token 留空。

    AstrBot 创建 OneBot v11 机器人
    消息平台类别 OneBot v11,反向 WebSocket 主机 0.0.0.0,端口 6199
  3. 保存并启用

    保存后回到机器人列表,确认 qq 处于运行中。NapCat 后面连的就是这个 6199。

    AstrBot 机器人列表
    qq 使用 aiocqhttp,反向 WebSocket 端口 6199

2. 部署 NapCat#

2.1 Windows 部署#

Windows 上不只有一个包,先按用途选:

包 / 工具运行方式需要预装和日常 QQ 的关系适合
NapCat.Framework以插件/注入方式挂到已安装的 QQNTQQNT共用桌面 QQ 的登录态已经有桌面 QQ,想直接复用
NapCat.Shell独立无头进程自己装 QQ + Node.js独立Linux/Docker、手动部署
NapCat.Shell.Windows.Node自带 QQ + 便携 Node 的整合包无独立于日常 QQWindows 想解压即用
NapCat.Shell.Windows.OneKey一键安装器,生成 NapCat.XXXX.Shell无,安装器会准备取决于版本,可能和桌面 QQ 共用Windows 想按向导安装
NapCatQQ Desktop单 EXE 图形管理器由工具引导安装取决于底层 NapCatWindows 桌面用户,推荐

方式一:Windows OneKey#

Windows OneKey 启动

  1. 下载并解压

    下载 NapCat.Shell.Windows.OneKey.zip,解压到普通目录,不要放 Program Files 或需要管理员权限的路径。

  2. 运行安装器

    双击 NapCatInstaller.exe,等待它生成 NapCat.XXXX.Shell 文件夹。首次运行需要联网准备文件。

  3. 启动 NapCat

    进入 NapCat.XXXX.Shell,双击 napcat.bat。控制台会打印 WebUI Token。

  4. 登录 WebUI 和 QQ

    浏览器打开 http://127.0.0.1:6099,用日志里的 Token 登录,扫码登录 QQ。

  5. 下一步

    Windows 上的 NapCat 和 AstrBot 通常不在同一 Docker 网络,WebSocket 地址见 不同网络下的 OneBot WebSocket 通信。

方式二:NapCatQQ Desktop(推荐)#

NapCatQQ Desktop

  1. 下载单文件工具

    下载 NapCatQQ-Desktop 的 EXE。它不依赖额外运行库,双击即可打开。

  2. 按引导准备环境

    在工具里按引导安装或选择 QQ 与 NapCat;它会自动检测环境并给出安装入口。

  3. 启动账号

    新建或选择账号,启动 NapCat,扫码登录 QQ。托盘可以后台托管,多账号在左侧切换。

  4. 下一步

    Windows 上的 NapCat 和 AstrBot 通常不在同一 Docker 网络,WebSocket 地址见 不同网络下的 OneBot WebSocket 通信。

2.2 Linux Docker 部署#

方式一:1Panel 容器部署#

创建 NapCat 容器

  1. 基本信息

    1Panel 里进入「容器 → 创建容器」,镜像填 mlikiowa/napcat-docker:latest,名称填 napcat,重启策略选 always。

  2. 端口

    映射 6099 给 NapCat WebUI。3000/3001 是 OneBot HTTP/WS 服务,用反向 WS 接入 AstrBot 时可以不映射。

  3. 环境变量

    NAPCAT_UID=0
    NAPCAT_GID=0

    如果服务器用非 root 用户运行 Docker,把 0 换成 id -u / id -g 的实际值。

  4. 挂载

    • /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。

同一网络下两个容器的 IP
AstrBot 172.19.0.2,NapCat 172.19.0.3,说明在同一网络

方式二:Docker Compose 部署#

部署 NapCat

  1. 保存 NapCat 配置

    同一网络不需要改 AstrBot 的 ports,6199 只在容器网络内部使用。

    services:
    napcat:
    image: mlikiowa/napcat-docker:latest
    container_name: napcat
    restart: always
    environment:
    - NAPCAT_UID=0
    - NAPCAT_GID=0
    ports:
    - "6099:6099"
    volumes:
    - ./napcat/config:/app/napcat/config
    - ./ntqq:/app/.config/QQ
    - astrbot-data:/AstrBot/data
    networks:
    - astrbot-network
    networks:
    astrbot-network:
    external: true
    name: astrbot_astrbot-network # 改成 AstrBot 实际使用的网络名
    volumes:
    astrbot-data:
    external: true

    保存为 /opt/astrbot/compose.napcat.yml。

  2. 启动

    Terminal window
    cd /opt/astrbot
    docker compose -f compose.napcat.yml up -d

方式三:AstrBot + NapCat 一起部署#

如果还没有单独部署 AstrBot,可以直接用一份 Compose 把两者一起拉起。两个容器都在 astrbot-network,共享 astrbot-data,6199 不映射到宿主机。

一起部署

  1. 保存配置

    services:
    astrbot:
    image: soulter/astrbot:latest
    container_name: astrbot
    restart: always
    security_opt:
    - no-new-privileges:true
    ports:
    - "6185:6185" # AstrBot WebUI
    environment:
    - TZ=Asia/Shanghai
    volumes:
    - astrbot-data:/AstrBot/data
    - /etc/localtime:/etc/localtime:ro
    networks:
    - astrbot-network
    napcat:
    image: mlikiowa/napcat-docker:latest
    container_name: napcat
    restart: always
    environment:
    - NAPCAT_UID=0
    - NAPCAT_GID=0
    ports:
    - "3000:3000"
    - "3001:3001"
    - "6099:6099" # NapCat WebUI
    volumes:
    - ./napcat/config:/app/napcat/config
    - ./ntqq:/app/.config/QQ
    - astrbot-data:/AstrBot/data
    networks:
    - astrbot-network
    networks:
    astrbot-network:
    driver: bridge
    volumes:
    astrbot-data:
    name: astrbot-data

    保存为 /opt/astrbot/compose.napcat.yml。

  2. 启动

    Terminal window
    cd /opt/astrbot
    docker compose -f compose.napcat.yml up -d

3. 配置 NapCat WebSocket#

NapCat 启动并登录 QQ 后,在 NapCat WebUI 里新建 WebSocket 客户端。同一网络填:

ws://astrbot:6199/ws

添加 WebSocket 客户端

  1. 新建客户端

    打开 NapCat WebUI,进入「网络配置 → 新建 → Websocket客户端」。

    NapCat 新建 WebSocket 客户端
    在网络配置里新建 Websocket客户端
  2. 填写名称和 URL

    名称填 astrbot,URL 填 ws://astrbot:6199/ws,Token 留空。

  3. 保存并启用

    保存后确认客户端处于启用状态。

同一网络的填写示例:

同一网络下填写 ws://astrbot/ws
名称 astrbot,URL ws://astrbot:6199/ws,Token 留空

4. 登录 NapCat#

登录 NapCat

  1. 获取 Token

    浏览器打开 http://<服务器IP>:6099/webui。登录用的 Token 在容器日志里:

    Terminal window
    docker logs napcat 2>&1 | grep -i -E "webui|token"

    也可以到挂载出来的 ./napcat/config/webui.json 里找 token 字段。

    1Panel 中 NapCat 日志里的 WebUi Token 和访问地址
    红框中是带 token 的 WebUI 地址,token 就是登录凭证

    截图中的 Token 仅作示例,请以自己日志里的值为准。

  2. 登录 WebUI

    把日志里的 Token 填进 WebUI:

    NapCat Web Login 输入 Token
    在 Token 输入框填入日志里的 WebUi Token
  3. 扫码登录 QQ

    如果 QQ 还没登录,NapCat 会要求扫码:

    NapCat 扫码登录 QQ
    用手机 QQ 扫描二维码完成登录

    登录成功后进入 NapCat 面板:

    NapCat 面板首页
    在基础信息里确认 NapCat 版本、QQ 版本和运行状态

5. 验证连接#

验证连接

  1. 看 NapCat 日志

    日志里出现反向 WebSocket 已启动,说明客户端在尝试连接。

    NapCat 日志中的反向 WebSocket 服务
    日志里能看到 WebSocket 反向服务已启动
  2. 看 AstrBot 日志

    出现下面这行,说明连接成功:

    aiocqhttp(OneBot v11) 适配器已连接。
    AstrBot 日志显示适配器已连接
    看到 aiocqhttp(OneBot v11) 适配器已连接即可
  3. 发一条测试消息

    在 QQ 里私聊机器人发一条消息,AstrBot 日志出现 收到 ... 测试,说明消息已经从 NapCat 送到 AstrBot:

    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。

第 1 篇,共 3 篇本文属于系列

分享文章

生成精美分享图或复制链接,与更多人分享本文。

继续阅读

沿着主题读

基于共同的标签与分类

换条路线

从其他文章中稳定抽取