如何搭建一个聊天机器人？#3 初步了解koishi、napcat以及onebot

更新于2025年9月6日，由于napcat默认设置导致的可能的安全性漏洞，请务必在配置的时候详细阅读本教程并好好设置token！否则小孩就要被黑客抓走了哦

从这里开始，我们正式进入了对bot无限可能的探索，并且接触到了框架的概念

由于笔者非常喜欢js系的语言当然也很喜欢使用koishi，那么我们就从koishi开始吧！

观前说明：所有大引号内的部分均为选读，不了解并不会影响你完成整个流程，但是可以让你学到更多知识，方便以后脱离教程

---

koishi简介

什么是koishi？

虽然我在这里看起来很兴奋的叭叭了很多句，但有人不禁要问了：koishi是啥？

首先对于框架的概念，请阅读这篇《如何搭建一个聊天机器人？#0.5 名词解释》，这里不再赘述，而koishi正是我们要接触的第一个机器人框架

引用自koishi官网的介绍——

特性

开箱即用

Koishi 提供了开箱即用的控制台。即便是零基础的用户也能在几分钟之内搭建自己的聊天机器人。

• 提供在线插件市场，即使没有任何编程基础，也能轻松在控制台中下载安装插件
• 支持 QQ，Telegram，Discord 等主流聊天平台，支持多账户和跨平台数据互通
• 随时随地通过控制面板监控运行状态，控制机器人的行为，甚至上号聊天

生态丰富

经过了长达四年的迭代，Koishi 已经发展出了丰富的插件生态和与之匹配的健壮系统。超过 1000 个官方和社区插件覆盖了机器人开发的方方面面，从平台支持、数据库、资源存储、网页控制台、状态管理到具体的业务功能一应俱全。无论你的目标是构建大型交互应用还是轻量级的辅助机器人，Koishi 都为你提供了最佳实践。如果担心在复杂的功能中迷失方向，我们也准备了细致的文档来提供帮助。

专为开发者打造

Koishi 更为开发者准备了众多专业功能，使插件开发者得以在各种复杂需求中构建规模化的解决方案。

• 类型支持：Koishi 完全基于 TypeScript 开发，拥有顶级的类型支持，丰富的代码提示让你在编写代码的时候甚至无需查看文档
• 单元测试：所有核心功能均已经通过单元测试，既确保了可靠性，也为开发者提供了一套测试插件和定位问题的最佳实践
• 模块热重载：开发 Koishi 插件时，只需轻点保存即可热重载，无需频繁重启机器人，如同前端开发一样丝滑顺畅

看起来好像非常复杂全是专业名词看不懂对不对（）其实我们只要知道，koishi作为框架有很丰富的插件市场，就算不会编程也可以使用插件市场里的插件然后对着图形页面简单设置即可；而对于更习惯于和代码打交道的开发者，koishi支持TypeScript语言，只需要了解事件系统的基本运作方式就可以很轻松的写出自己需要的功能

有人可能还是不太理解：那么使用koishi和我之前搭建的海豹骰冲突吗？

答案是：完全不冲突，而为何不冲突、为何可以同时运作都要依靠onebot协议。具体onebot协议是什么也请看上面那篇前置文章，如果不想看，可以理解为一种在聊天机器人开发者之间共用的一套“语言体系”，大家都用这个方式说话，那自然就不会冲突了。更具体的部分我们晚点再讲。

↑上面的描述可能有一些不准确的地方，大家大概看看就好

为什么要用koishi？

在框架的介绍中，我们提到了框架就是毛坯房，而最终的目的是要能住人，虽然我们已经有了一套精装修的房子（海豹骰），但是总感觉哪里还不够——比如我们想做一个好感度系统、签到系统等等，这些靠海豹这个精装修的房子本身是很难做到的。

这时候我们就考虑一个新的方式，那就是买一套新的毛坯房（koishi），自己装修，但是同时又把之前精装修的海豹也一起放进去，这样在有海豹的掷骰功能以外，我们就可以自由拓展了

当然这个毛坯房有很多种选择，koishi只是其中一种比较好的选择，还有用python实现的nonebot，这里暂且不提。

---

Koishi的安装

虽然koishi的官方手册写的已经比较清楚，但是鉴于这是一篇详细的保姆级教程所以我再尝试用更简单的方式教学一遍，如果能看懂官方手册的人建议按照官方手册的步骤完成安装

对于官方手册已经写的非常明白的部分，这里会直接引用

环境配置/安装Node.js

下载安装包

首先我们现在自己的电脑上前往 Node.js 的官方网站：

点击Get Node.js，在接下来的页面中找到下方，选择(.msi)的格式的安装程序下载

随后，在服务器上，用之前访问本地电脑磁盘的方式，找到下载好的安装包，拖到桌面后运行，根据提示完成整个安装流程即可。

安装包管理器

包管理器是什么？可以非常非常简单粗暴的理解为一个应用商城，用特定的指令就可以下载一些人上传在网上的资源（包）

Node.js 自带名为 npm 的包管理器，你可以直接使用它。虽然koishi官方推荐了使用yarn并且它的安装非常简单，但为了后续讲解统一方便，这里不使用

配置镜像源

如果你是国内用户，从npm上下载可能非常慢。因此，我们推荐你配置一下镜像源，以提升安装速度。

在服务器内按下Win+R，输入powershell来启动powershell，之后我们会经常启动它，简称为启动命令行。在出现的界面里输入下面的指令

npm config set registry https://registry.npmmirror.com

创建项目

依旧在服务器内，在自己喜欢的位置新建文件夹（最好命名为koishi之类的），双击文件夹打开，然后点击下图箭头的地方

输入powershell以启动命令行，以后想要进入某个文件夹下的命令行都使用该方式

输入下面的命令以创建 Koishi 项目：

npm init koishi@latest

跟随提示即可完成全套初始化流程。（一般来说全部按回车即可）如果顺利的话命令行应该会如下图显示，并且弹出浏览器窗口，页面为koishi控制台

启动应用

顺利的话在第一次安装好koishi后就已经自动启动了应用，如果需要退出，请务必用Ctrl+C组合键。

如果退出后需要再次启动，请进入新建的文件夹中名为koishi-app的文件夹下启动命令行，然后输入指令

npm run dev

即可启动，如果不小心关闭了控制台页面，可以在服务器的浏览器内输入127.0.0.1:5140来重新进入

顺带一提，上方的指令实际上是“在开发者模式下启动”，比普通启动更方便调试，所以一般会直接以开发者模式启动

---

初探koishi

初次进入koishi控制台，点击下方的同意，就可以看到控制台全貌了

此时koishi还什么都没有，不过不着急，我们先大概了解一下最重要的插件相关的两个页面，其他我们暂时略过

插件配置

位于第二个图标

在这里我们可以看到所有koishi内安装的插件，如果我们不会自己手写代码的话，那么在插件市场内下载插件然后在此处配置就是最好的选择。默认插件如果不懂的话请最好不要乱动

插件市场

位于第三个图标

在这里有大量官方以及开发者自己编写的插件，你可以随意搜索自己想要的功能看看有没有前人为你铺好道路

比如我们可以试着搜索tarot关键词，就会弹出非常多塔罗相关的插件，基本是即下即用

由此来看，插件为koishi开发带来了极大的便利性，不过究竟怎么样才能真正应用这些插件到bot上呢？怎么样让bot通过koishi处理后说话呢？

---

来把大家连接起来吧！

试想一下，现在我们有很多台电脑，每个电脑都在跑着一个qq，每个qq都在跑着同一个账号，但是背后的操作人员不同——这其实从常理上讲不通，原因是qq不支持多台电脑同时登录一个账号

那现在我们搭建机器人也同理，我们之前已经搭建了一个成型的海豹骰，但是如果我们再独立的使用一个koishi就会导致冲突，现在我们需要把这些操作人员都聚集到一台电脑前，只要一台电脑来登录，操作人员后面怎么七嘴八舌不管。

前面我们又说过，框架会帮你处理好登录逻辑，所以一般来说用谁来处理登录逻辑都无所谓，只是koishi在这方面略显逊色，我们就考虑使用其他更快捷方便的框架来处理登录逻辑，同时还要把那些不负责处理登录的框架接到这个处理登录的框架上——通俗的来讲，就是我们要决定这唯一的一套电脑究竟是谁来提供的，然后再用某种方式，把操作人员聚集在一起，并且让他们能够一起沟通。

连接背后的逻辑

虽然我们接下来会用最简单的方式直接告诉你怎么连接海豹核心和koishi，但是为了知其然并且知其所以然，所以还是讲一下连接背后的非常粗略的逻辑

一般来说，我们首先要确立一个服务端，然后其余的则是客户端。服务端的作用正是处理登录逻辑、然后收发消息，而消息内容的处理则交给客户端来处理。有的时候，服务端也可以不仅仅只处理登录和收发，也可以帮忙处理一部分逻辑。

而这个“交给”的动作是怎么实现的呢，这里有两个要点：一是确立一套标准的对话模式、二是确立一条对话的路线或是说方式。

对话模式则是我们在前置知识里已经了解到的协议的概念，具体到这个场景下指的就是onebot协议

而对话的方式有两种，一是HTTP，二是WebSocket（ws），我们一般常用ws

为什么使用WebSocket？

http的通信方式是单向的、临时的，而ws则是双向的、长时间的。

你可以理解为ws的连接一旦建立，两个人就像打电话一样，可以你一嘴我一嘴，而不会出现只能一个人说另一个人听的情况

对于qqbot，收发消息肯定是一个长期的过程，并且双发都需要“做些什么”，所以ws的好处就在这里体现了。反而http在此时显得更加效率低下、占用资源更多

现在，我们确立了对话模式以及对话方式，那么下一步就是实践地把大家连接在一起

具体的操作

此处，我们引入一个新的框架NapCat，让它来担任服务端的角色，处理登录逻辑以及收发消息

关于napcat如何工作请查看https://napneko.github.io/guide/napcat这里不对原理做阐述

NapCat的安装与配置

为了方便安装和使用，我们决定使用napcat提供的可视化管理工具

https://github.com/NapNeko/NapCatQQ-Desktop/releases/tag/v1.5.4

在此链接中下滑找到NapCatQQ-Desktop.exe，点击即可下载

如果发现上方链接加载许久都无法加载出来，请考虑魔法上网

将下载后的文件用之前的老方法传进服务器内，并在服务器内双击打开，进入安装界面，选择我是新手，一路点击安装即可，最后进入控制台页面

首先为了确保环境完整，我们可以点击左下角的组件，查看三个组件是否都完整，否则按照指引安装即可

点击左侧添加，在基本配置内填写信息（音乐url留空），填写完成后点击右上角添加

接着进入左侧列表，选择自己刚刚添加的bot，点击右上角添加连接配置，选择WebSocket服务器，并按照下图填写

其中token是一个自定义的连接密码，请务必填写高安全性的密码并牢记！！

最后点击启动，查看NapCat日志里是否在正常输出，一般稍后会弹出一个二维码，请用bot的账号扫码登录后点击ok即可，正常的话此时bot应该已经能接受到信息了！

至此，服务端就算配置完毕啦

客户端的配置

连接海豹核心

进入海豹控制台，点击左侧账号设置，按照下图设置，请在访问令牌处填写刚刚设置的token密码

点击下一步，此时可以发现已经成功连接了！

连接koishi

有了先前连接海豹的经验，koishi的连接方式也类似，不过koishi默认并不带onebot的适配器——可以说koishi天生并不会onebot这门语言，我们需要到插件市场下载一个适配器，让它“学会”

进入koishi的插件市场，搜索onebot，找到下图插件，点击添加、安装

安装完成后回到插件配置，找到右上角一个插头的图标添加插件，找到适配器选项，将刚刚安装的adapter-onebot加入。理论来说所有在插件市场下载的插件都需要用这种方式进行添加。

在左侧找到adapter-onebot插件，按照下图方式填写，同样不要忘记填写token！

完成后点击右上角小三角启用插件，如果看到日志中有adapter connect to server字样、右下角亮起小绿灯，就说明连接成功了！

现在，客户端我们也配置完毕，成功实现了napcat+海豹核心+koishi的连接！

---

结语

这篇教程开始摸索到了一点大多数bot教学不会深入讲解的地方，尤其是关于ws连接的部分

可能初次接触的开发者们会觉得有很多地方非常晦涩，但如果能够跟着上手一遍，说不定就能稍微理解一点！尤其是当看到几个框架都能顺利连接在一起的时候，会有一种“孩子终于出生终于会说话了”的感动感（）

从这篇教程往后，我们就要开始讲如何利用插件、甚至如何编写自己需要的功能

在下一篇教程出来之前，大家也可以尽情探索koishi的插件市场，感受其他开发者提供的方便的插件

如果有对这篇文章疑惑的地方，可以在评论区或者qq上私聊我