【工具】Koishi｜koishi跨平台聊天机器人开发平台使用方式（开发者方式）

体验时间：2025/06/19
koishi开源链接：koishijs/koishi: Cross-platform chatbot framework made with love

本来想下桌面版，但很遗憾不知道怎么回事刚好赶上开发者在更新，把msi安装包删掉了，所以这里记一下开发者的使用方式。

我用的是Windows，我注意到CSDN上存在过时的（或者单纯是出错了）的教程，所以把我的笔记发布出来。

我参考的教程包括，虽然它是2025年6月17号发布的，但是存在指令错误，会导致无法正常使用：Koishi：十分钟搭建跨平台聊天机器人，让社群运营效率翻倍。

其他参考文献也都在文中列出。

这里以QQ的为例。

1 注册开放中心

参考官方教程：@koishijs/plugin-adapter-qq | Koishi

1. 前往 QQ 开放平台 注册账号
2. 登陆进入 机器人管理后台 并创建官方机器人
3. 创建完成后，在「开发设置」界面获取机器人三项基本数据 [id, token, key]

2 创建koishi模板项目

参考官方文档：创建模板项目 | Koishi

安装Node.js，并确保自己的npm能用。如果你能下exe或者下msi，就跳过这个步骤。

如果你不知道怎么安装Node.js，也不知道怎么确保npm能用，请看官方文档：创建模板项目 | Koishi。

之后运行如下指令：

# 创建新项目
mkdir koishi-app
cd koishi-app# 创建模板项目
npm init koishi@latest

跟随提示输入项目名字和其他的，即可完成全套初始化流程。

之后再用的时候，在对应目录下输入npm start即可。

正常情况你可以通过访问http://127.0.0.1:5140/打开这个页面：

3 配置Adapter-qq

设置里找到adapter分组，选择adapter-qq，修改相关的配置项，填入在开放中心的「开发设置」界面获取的机器人三项基本数据 [id, token, key]：

之后的操作都参考：QQ开放平台接入koishi教程（2024） | 冬涛殇雪 Blog

之后，在 机器人类型 （type）栏选择公域（public），不要开启沙箱模式。

填写完毕后，点击右上角的「保存」按钮!

接下来，翻到下方的「intents」配置项

如果你准备在 QQ 群中使用，勾选 USER_MESSAGE。
如果你准备在 QQ 频道的 频道私信 列表中使用，勾选 DIRECT_MESSAGES。
如果你准备在 QQ 频道中使用，且你的机器人是公域机器人，勾选 PUBLIC_GUILD_MESSAGES。
勾选 MESSAGE_AUDIT。
切记 MESSAGE_AUDIT 为必勾选选项
注意此处若填写错误将会直接导致机器人无法接入。填写时请务必仔细。

填写完毕后，点击右上角的「保存」按钮。

最后，点击右上角播放图标的「启动」按钮。插件会输出一条成功连接的日志，同时，Koishi 窗口的右下角已点亮绿灯

结论：你成功将 Koishi 对接了 QQ 机器人。

4 解决“接口访问源IP不在白名单”

如果你用的是校园网，网络环境太复杂了，不好用；最好是用服务器或者手机流量。

以下几个网站都试一下：
http://api.ipify.org
https://www.whatismyip.com/
https://whatismyipaddress.com/
https://www.whatismyip.com.tw/

获取真实且唯一的出口IP，如果你实在要用校园网，那你找个访问速度稍微快点的IP获取网站，多获取几个IP全填进去就好了，我多填了两个，就好了。

5 将机器人拉入测试群

你可以选择在 QQ 群 中测试你的机器人

首先，将你的手机 QQ 升级至最新版（不低于 8.9.90），并在手 Q 内创建一个自己为群主的测试群

之后，回到 QQ开放平台中QQ 机器人的网页后台，点击左侧的「沙箱配置」，翻到页面最下方，在「在 QQ 群配置」一栏选择刚刚创建的测试群：

接着，在手 Q 中打开测试群，点击右上角的菜单图标，向下翻动找到「群机器人」选项，进入并添加刚刚创建的机器人。现在，你已可以在 QQ 使用自己的机器人。输入「@」并选择机器人，然后在后面输入「help」并发送。你可以看到机器人正常工作。

结论：你已将自己的机器人拉入测试群，并能够正常使用机器人

恭喜，你刚刚创建了自己的机器人。

6 测试使用情况

输入@机器人 help，有反应就是好机器人。

更多

更多插件可以看下官方的教程，或者其他的教程，例如：Koishi+Napcat 快速搭建 QQ 机器人 | 一叶轻舟。

本账号所有文章均为原创，欢迎转载，请注明文章出处：https://shandianchengzi.blog.csdn.net/article/details/148769556。百度和各类采集站皆不可信，搜索请谨慎鉴别。技术类文章一般都有时效性，本人习惯不定期对自己的博文进行修正和更新，因此请访问出处以查看本文的最新版本。