AstrBot NapCat 消息机器人实战教程教学

介绍

这是一个大模型机器人的试验尝试。效果预期就是可以将大模型引入QQ对话。

效果就是：让自己的QQ成为一个机器人客服，别人发消息给自己的QQ，自己的QQ自动就回复别人了，回复依靠的是大模型的语言能力。

项目在这里：https://astrbot.app/deploy/astrbot/docker.html#%E4%BD%BF%E7%94%A8-docker-%E9%83%A8%E7%BD%B2-astrbot

AstrBot 结合 NapCat 做QQ机器人， AstrBot 也可以结合其他消息中间件，做别的平台的机器人，比如微信、QQ、飞书、钉钉。

工作流

AstrBot NapCat 在整个链路中的具体工作流程和如何与其他组件协作的详细说明：

1. 消息接收

NapCat

NapCat 是一个 QQ 机器人框架，它能够通过 QQ 协议（比如基于 Mirai 或其他协议实现）实时监听并捕获消息。当有人向你的 QQ 账号发送消息时， NapCat 会立即接收到这条消息。

NapCat 里面有ws协议，可以和一些插件（aiocqhttp）进行ws链接，这样就可以把消息给插件，插件也可以把消息发给NapCat。

2. 消息预处理

AstrBot 和 aiocqhttp 是结合的，AstrBot得到消息后，要进行一些消息处理，比如白名单的才回复之类的逻辑。

你可以开很多个消息平台，消息平台依靠不同的中间件耦合，比如QQ就是靠aiocqhttp结合，微信、飞书、钉钉都有各自的消息中间件，这样一个AstrBot平台就可以管理很多个应用。

3. 调用大模型

AstrBot 会调用大模型。大模型管理的页面可以让你添加很多个大模型，可以使用命令来控制选择某一个大模型进行回复。

有这些指令：

bash
展开代码
AstrBot v3.5.12(WebUI: v3.5.12)
内置指令:
[System]
/plugin: 查看插件、插件帮助
/t2i: 开关文本转图片
/tts: 开关文本转语音
/sid: 获取会话 ID
/op: 管理员
/wl: 白名单
/dashboard_update: 更新管理面板(op)
/alter_cmd: 设置指令权限(op)

[大模型]
/llm: 开启/关闭 LLM
/provider: 大模型提供商
/model: 模型列表
/ls: 对话列表
/new: 创建新对话
/groupnew 群号: 为群聊创建新对话(op)
/switch 序号: 切换对话
/rename 新名字: 重命名当前对话
/del: 删除当前会话对话(op)
/reset: 重置 LLM 会话
/history: 当前对话的对话记录
/persona: 人格情景(op)
/tool ls: 函数工具
/key: API Key(op)
/websearch: 网页搜索

4. 发送回复

AstrBot

同来时路一样，返回消息，发送给QQ平台。

同时，还有一些监控、记录等增值功能。

部署

如果您想使用 NapCat 将 AstrBot 部署到 QQ（个人号），使用这种方式会同时部署 AstrBot 和 NapCat，更快：

sh
展开代码
mkdir astrbot
wget https://raw.githubusercontent.com/NapNeko/NapCat-Docker/main/compose/astrbot.yml
docker compose -f astrbot.yml up -d

astrbot.yml：

sh
展开代码
# docker-compose.yml
# NAPCAT_UID=$(id -u) NAPCAT_GID=$(id -g) docker-compose -f ./compose/astrbot.yml up -d
services:
  napcat:
    environment:
      - NAPCAT_UID=${NAPCAT_UID:-1000}
      - NAPCAT_GID=${NAPCAT_GID:-1000}
      - MODE=astrbot
    ports:
      - 3000:3000
      - 6099:6099
    container_name: napcat
    restart: always
    image: mlikiowa/napcat-docker:latest
    volumes:
      - ./data:/AstrBot/data
      - ./ntqq:/app/.config/QQ
    networks:
      - astrbot_network
    mac_address: "02:42:ac:11:00:02"
  astrbot:
    environment:
      - TZ=Asia/Shanghai
    image: soulter/astrbot:latest
    container_name: astrbot
    restart: always
    ports:
      - "6185:6185"
      - "6195:6195"
      - "6199:6199"
    volumes:
      - ./data:/AstrBot/data
      - ./napcat/config:/app/napcat/config
      - ./ntqq:/app/.config/QQ
    networks:
      - astrbot_network
networks:
  astrbot_network:
    driver: bridge

查看日志，这里可以看到二维码，QQ扫码登录即可。也可以直接去6099端口的WebUI进行登陆。

sh
展开代码
docker compose -f astrbot.yml logs -f

关闭服务：

sh
展开代码
docker compose -f astrbot.yml down

原理

NapCatQQ

NapCatQQ 是一个基于 NTQQ 本体实现的无头 Bot 框架，其名字寓意为“瞌睡猫QQ”，意味着它像睡着了一样在后台低占用运行，且无需 GUI 界面。该项目旨在提供一种现代化的方式来实现 QQ 机器人，通过基于 OneBot 协议的设计，让开发者能够更加方便地创建和管理 QQ 机器人。

这是绘制的架构图，大概可以看到NapCat做了什么。NTQQ可以理解为一个QQ通信协议，这一部分就掌管QQ的状态。NapCat 可以通过和NTQQ 交互，可以发送消息啥的。而其他的插件或者程序就和NapCat 交互，向NapCat 的接口发消息。NapCat在中间，省略了大家去理解NTQQ的细节，让大家可以直接通过NapCat 接口就可以发QQ消息。

进一步详细了解看这里：https://napcat.napneko.icu/guide/start-install

接口文档在这里：https://napcat.apifox.cn/

初略安装流程

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

AstrBot

什么是 AstrBot？

AstrBot 是一个易于上手的多平台聊天机器人及开发框架。通过它，你能够在多种消息平台上部署一个支持大语言模型（LLM）的聊天机器人。并以此实现但不限于 AI 知识库问答、角色扮演、群聊管理、LLM Agent 等功能。

架构：

实战操作

docker compose 部署后，登录 NapCat 6099去登录qq。比如我是浏览器打开： http://10.100.80.98:6099/

NapCat 初始的token是 napcat（日志里写了）.

NapCat 登录后是这样：

在NapCat 网络配置里。网络配置就是可以配置很多插件，每个插件都可以和外界通信（靠不同的端口）。

在这个docker compose 镜像里，会默认有一个这个NapCat ws客户端和 AstrBot 那边一个默认的插件耦合，所以不用删这个也是OK的：

进去AstrBot 的Webui，在服务提供商管理中新增服务提供商。

比如我用sgalang部署了一个大模型： https://www.dong-blog.fun/post/2119

也可以用Ollama部署小模型进行测试，AstrBot 平台支持各种大模型部署框架的通信协议。

我填写我的大模型服务如下。对于weclone项目，训练模型后，把模型部署为兼容openai格式的api服务，也可以在这里填写。

看到这里接入就是OK了：

重点：我部署的模型没有工具调用能力，所以需要在消息里关掉这个！不然会通信失败。

点击消息，可以看到LLM大模型是蓝色的，代表配置是成功的。然后发送消息： /tool off_all ，没收到回复就刷新一些网页，这里可能有点BUG。关于函数调用更多的说明看这里：https://astrbot.app/use/function-calling.html

/tool ls 查看当前具有的工具列表
/tool on 开启某个工具
/tool off 关闭某个工具
/tool off_all 关闭所有工具

在消息里，可以测试大模型是否工作正常，可以在这里发送消息，收到大模型回复就是OK的。

接下来要配置 AstrBot 的消息中间件，还要配置 NapCat 的网络插件。让 AstrBot 去和 NapCat 耦合起来工作。

在 AstrBot 中部署消息平台。

选择 aiocqhttp(OneBotv11)

弹出的配置项填写：

配置项填写：

ID(id)：随意填写，用于区分不同的消息平台实例。
启用(enable): 勾选。
反向 WebSocket 主机地址：请填写你的机器的 IP 地址。一般情况下请直接填写 0.0.0.0
反向 WebSocket 端口：填写一个端口，例如 6200 。

额外说一句，这里来配置 aiocqhttp 是纯属教学，因为这个镜像里默认有个aiocqhttp已经和NapCat 那边耦合上了。我们这里aiocqhttp 填写6200端口，再多开一个，纯属教学。

如图：

配置管理员

填写完毕后，进入配置页，点击其他配置选项卡，找到管理员 ID，填写你的 QQ 号（不是机器人的 QQ 号）。

切记点击右下角保存，AstrBot 重启并会应用配置。

再解释一下什么意思，在NapCat 登陆的QQ是小号，准备用小号来当机器人。当别人对机器人发消息，机器人会回复。但为了可以控制机器人的行为（比如开启一些工具调用），就需要一个管理员QQ角色，我填写一个大号QQ，大号对机器人发消息（指令形），机器人会被设置。所以这里填写的管理员，不是机器人的QQ，一定要注意。

接下来在 NapCatQQ 中添加 WebSocket ，去网页 http://10.100.80.98:6099/webui/network

切换回 NapCatQQ 的管理面板，点击网络配置->新建->WebSockets客户端。

在新弹出的窗口中：

勾选启用。
URL 填写 ws://astrbot:6200/ws
消息格式：Array
心跳间隔: 5000
重连间隔: 5000

点击保存。

URL 要注意了，一定是NapCat 可以访问到的网络，我一开始启动是docker compose 启动的，可以借助docker 的网络，所以写了 ws://astrbot:6200/ws ，后面的/ws 必须要填写，是ws通信协议的路径。

如果你的部署方式千奇百怪的，你要注意，你的NapCat 需要可以访问到你 AstrBot 的网络才行。

如图这个配置：

回到 AstrBot WebUI 控制台，如果出现 aiocqhttp(OneBot v11) 适配器已连接。相关蓝色的日志，说明连接成功。

此时，你的 AstrBot 和 NapCatQQ 应该已经连接成功。

你在NapCat登陆的那个QQ已经成为机器人。你可以用别的QQ对这个机器人发消息。

如图：

作为管理员QQ，可以对机器人QQ发一些设置命名：

总结

这是一个绝对有潜力的方向，你是否觉得你家里小爱同学音响里的小爱太笨了？你可以用AstrBot 接入强大的模型，有一个贴心助手来帮助你。
在本质上，你会得到一个大模型机器人，AstrBot 可以接入MCP，具备工具调用的能力，这意味着一切皆有可能：MCP可以联网搜资料查天气、MCP可以连接物联网操控实际生活的闹钟窗帘空调、MCP可以连接RAG数据库查询，你的大模型会非常贴心，靠一些消息平台进入你的生活，帮助你的生活。
在WeClone项目里，可以提取出自己微信聊天记录，然后用于训练大模型，大模型会学习到你的说话方式，这样大模型就是你的数字分身。然后借助AstrBot 的部署，别人找你聊天，你的数字分身在回复别人，但别人难以察觉这个人不是你。
在客服领域，这个链路非常有潜力，比如淘宝店铺的无人值守。

目录

介绍

工作流

1. 消息接收

2. 消息预处理

3. 调用大模型

4. 发送回复

部署

原理

NapCatQQ

AstrBot

实战操作

总结