NapCat 接入¶
NapCat 是月璃最常用的协议端：支持平台多、社区大。 本篇从下载协议端一路做到 QQ 里收到回复。
前置：月璃后端已经能在本机跑起来（第一次启动与配置）， 并且准备了两个不同的 QQ 号——机器人号用小号。
先看清这四件事¶
接入时最容易卡住的就是这四个问题，动手前先花一分钟看完。
一、要建的是「正向 WebSocket 服务端」¶
这个服务由协议端开出来、等着月璃去连，所以叫正向。 在 NapCat 的界面里要选的是 WebSocket 服务端这个类型：
- 选服务端 —— 对的。NapCat 监听一个端口，月璃主动连上来。
- 选客户端 —— 方向反了，月璃不会去当服务端，连不上。
- 只开 HTTP 服务端 —— 不满足，月璃走的是 WebSocket。
二、一共涉及四个端口，只有一个要填进月璃¶
| 端口 | 谁在用它 | 要填进月璃吗 |
|---|---|---|
| 协议端管理面板端口 | 浏览器打开 NapCat 的 WebUI 改配置 | 不填 |
| 协议端 HTTP 服务端口 | HTTP 上报或 API 调用 | 本接入方式用不到 |
| 正向 WebSocket 端口 | 月璃连过去收发消息 | 要填，就是 [napcat].port，示例用 8095 |
| 月璃后端端口 7999 | 浏览器打开月璃的管理面板 | 不填，和协议端没有关系 |
四个端口互不通兑。只有 WebSocket 那个要出现在月璃的配置里， 另外三个填进去都会连不上。
三、一共三个 token，也只有一个要填进月璃¶
| 名字 | 干什么用 | 填到哪 |
|---|---|---|
| 协议端 WebSocket 访问令牌 | 月璃连协议端时握手用的凭据 | 月璃的 [napcat].token；协议端没设这项就留空 |
| 协议端管理面板密码 | 登录 NapCat 自己的 WebUI | 不填 |
| 月璃面板 token | 登录月璃的管理面板 | 不填 |
前两个都在协议端，但只有第一个是给月璃用的 —— 把管理面板密码填进 token
是接入时最常犯的错，表现是握手返回 401 或 403。
四、月璃这边要改两个文件¶
两个文件都在项目目录下（项目装在 D:\YueLiBot 就是 D:\YueLiBot\config\adapter.toml
与 D:\YueLiBot\adapters\yueli-napcat-adapter\config.toml），用记事本打开即可。
config/adapter.toml：只改plugin一行adapters/yueli-napcat-adapter/config.toml：改[napcat]与[owner]段里的几个值
两个文件的分工，见适配器配置。
第一步：装 NapCat¶
到 NapCatQQ Desktop 的 Releases
下载 NapCatQQ-Desktop-<版本>-x64.msi，双击安装。
这不是协议端本体，而是它的管理器：在这个窗口里就能装 QQ、装 NapCat、 启动与停止、看日志、改配置，不用自己抠命令行。
下载时注意：文件名带
watch-v的是远端监控小工具，不是桌面安装包。
要求 Windows 10 / Server 2016 以上、x64。安装后配置数据在
%ProgramData%\NapCatQQ Desktop，重装不会丢。
打开后按它的引导创建实例、装好依赖组件，把 QQ 和 NapCat 都启动起来。
到 NapCatQQ 的 Releases
下载 NapCat.Shell.zip，解压到一个独立目录——
不要放进月璃的目录里，两者的升级节奏完全不同。
- Windows 11：运行包内
launcher.bat - Windows 10：运行
launcher-win10.bat - Linux：按包内说明运行启动脚本
这种方式需要自己准备与 NapCat 版本匹配的桌面 QQ。
更多的安装形态与注意事项以官方文档为准： NapCat 官方文档。
第二步：登录机器人 QQ¶
启动后按提示用机器人小号扫码登录，保持 NapCat 进程运行。
启动日志里会打印一个 WebUI 地址，用它打开 NapCat 自己的管理界面 （这是协议端的面板，和月璃的管理面板是两个东西）。登录后：
- 按界面要求设置或更新管理密码
- 确认页面上显示的 QQ 号就是你打算当机器人的那个小号
第三步：建一个正向 WebSocket 服务端¶
这一步是把「门」打开，让月璃能连进来。
在 NapCat WebUI 里打开网络配置 → 点新建 → 类型选 WebSocket 服务端。
不同版本的界面字段名略有出入，但只要看到下面这几项，就说明找对地方了：
| 界面上的字段 | 填什么 | 月璃那边对应哪个值 |
|---|---|---|
| 名称 / 备注 | 随便填，只影响你在列表里认不认得出 | 不用填 |
| 启用 | 打开（只保存不启用，端口不会真的监听） | 插件连接段的 enabled = true |
| 主机 / 监听地址 | 127.0.0.1（同机部署） |
host = "127.0.0.1" |
| 端口 | 8095，或任意没被占用的端口 |
port，两边必须一模一样 |
| 令牌 / Token | 自定义；不想设就留空 | 有值就原样填进 token，留空则 token = "" |
| 消息格式 / messagePostFormat | array |
适配器按消息段解析 |
注意端口那一行是唯一需要两边抄一致的数字。上面的管理面板端口、 下面的 HTTP 端口都不要填进月璃，见上面第二节。
messagePostFormat 必须是 array
这一项填成字符串格式（string）会让消息段解析失败，
表现是能连上但收不到正常内容。改成 array 后重新启用服务。
保存后确认服务真的开始监听了——只保存草稿、没有启用，端口是不会开的。
跨机器或容器部署时，监听地址要允许月璃所在的机器访问，端口也要正确映射。
月璃那边填的是连接目标地址，不能填 0.0.0.0（那是监听范围，不是可达地址）。
第四步：在月璃这边选插件、填连接¶
要改两个文件，都在项目目录下，用记事本打开就行（右键 → 打开方式 → 记事本）。
先打开 config/adapter.toml。项目装在 D:\YueLiBot 的话，完整路径就是
D:\YueLiBot\config\adapter.toml。把 plugin 改成：
再打开第二个文件：adapters/yueli-napcat-adapter/config.toml，同样在项目目录下。
它可能还不存在 —— 那就从
连接模板
复制一份内容，存成这个路径。
改下面这几个值，其余字段保留模板里的原样：
[napcat]
enabled = true # 启用前先在协议端把正向 WS 服务端建好
self_qq = "123456789" # 机器人小号，必须与协议端当前登录一致
host = "127.0.0.1" # 协议端所在主机；只填地址，不带 ws:// 和端口
port = 8095 # 与协议端实际监听端口一致
token = "" # 协议端设了访问令牌就填这里，没设留空
[owner]
qq = "987654321" # 你自己的 QQ 号，与上面必须是两个不同的号
token 这一格填的是协议端 WebSocket 服务的访问令牌 ——
协议端第三步里设了就往这里抄，没设就留空。三个 token 的区别见
上面第三节。
第五步：启动并确认¶
保持 NapCat 在线，在月璃项目根目录运行：
后端终端会打印适配器加载、协议连接结果和识别到的登录号。三项都对之后：
- 用你自己的 QQ 私聊机器人号，发一句短消息
- 确认 QQ 里真的收到了回复（不是只在月璃面板里看到）
- 把测试群号写进插件配置的
[group]名单，重启月璃 - 在群里用 QQ 的 @ 功能提及机器人，确认群里有回复
连不上的常见原因¶
| 现象 | 先查这里 |
|---|---|
| 连接被拒绝或超时 | NapCat 在跑吗、正向 WS 服务启用了吗、端口与配置里写的一致吗 |
| 握手返回 401 / 403 | token 填错了，或把管理面板密码当成访问令牌填了进去 |
| 握手失败、方法不可用 | 端口填成了 NapCat WebUI 或 HTTP 服务的端口，不是 WS 端口 |
| 报登录号不匹配 | self_qq 与 NapCat 当前登录的号不一致，或连到了另一个实例 |
| 连上了但消息解析报错 | 服务端的 messagePostFormat 不是 array |
| 你私聊有回复，别人的没有 | 私聊名单是白名单模式且没写他——这是默认的安全行为 |
| 群里 @ 了也不回 | 群号没进 [group].list；或她正在睡眠 |
| 找不到配置段 | 连接文件必须放在所选插件目录下，段名必须是 [napcat] |
断线重连间隔与动作超时改不好这些问题。 端口、令牌、账号错了， 把超时调多大都连不上；这两个参数只影响网络抖动时的表现。
戳一戳要单独确认。 它依赖连接后的能力探测，普通文字收发成功不代表它可用； 群里还要开启对应的动作开关。
只想先看看配置对不对，可以跑只读自检（见适配器配置）， 但它不替代真实的网络与投递验收。
配置能读通、连接能建立、QQ 真收到回复——这三件事要分别确认。