体验时间：2025/06/19
koishi开源链接：koishijs/koishi: Cross-platform chatbot framework made with love
本来想下桌面版，但很遗憾不知道怎么回事刚好赶上开发者在更新，把msi安装包删掉了，所以这里记一下开发者的使用方式。
我用的是Windows，我注意到CSDN上存在过时的（或者单纯是出错了）的教程，所以把我的笔记发布出来。
我参考的教程包括，虽然它是2025年6月17号发布的，但是存在指令错误，会导致无法正常使用：Koishi：十分钟搭建跨平台聊天机器人，让社群运营效率翻倍。
其他参考文献也都在文中列出。
这里以QQ的为例。
文章目录
-
- [1 注册开放中心](#1 注册开放中心)
- [2 创建koishi模板项目](#2 创建koishi模板项目)
- [3 配置Adapter-qq](#3 配置Adapter-qq)
- [4 解决"接口访问源IP不在白名单"](#4 解决“接口访问源IP不在白名单”)
- [5 将机器人拉入测试群](#5 将机器人拉入测试群)
- [6 测试使用情况](#6 测试使用情况)
- 更多
1 注册开放中心
2 创建koishi模板项目
参考官方文档：创建模板项目 | Koishi
安装Node.js，并确保自己的npm能用。如果你能下exe或者下msi，就跳过这个步骤。
如果你不知道怎么安装Node.js，也不知道怎么确保npm能用，请看官方文档：创建模板项目 | Koishi。
之后运行如下指令：
bash
# 创建新项目
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不在白名单"
如果你用的是校园网，网络环境太复杂了，不好用；最好是用服务器或者手机流量。
以下几个网站都试一下：
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。百度和各类采集站皆不可信，搜索请谨慎鉴别。技术类文章一般都有时效性，本人习惯不定期对自己的博文进行修正和更新，因此请访问出处以查看本文的最新版本。