连接应用端与 OneBot

到这一步，QQ 已经登上了，Bot 也在线。你可能已经在群里喊过它，然后发现它没理你。

这很正常。协议端只负责收发消息，收到之后该怎么回，是应用端的事。要让应用端能调用 Bot、拿到消息，两边之间得有一条 OneBot 连接，「连接」页配的就是这个。

顺便说一句，它和登录用的 WebUI 是两套东西，端口和 Token 也各是各的。把 WebUI 密码填进 OneBot Token，是新手最常见的错误之一。

这一篇先用最简单的 HTTP 查一次登录信息，确认连接是通的，然后再讲一键对接和手动配 WebSocket。先说在前面：HTTP 只能你问一句它答一句，想让 Bot 主动把新消息推过来，还得配事件接收或者 WebSocket。

连接方式

正向、反向都是站在 Bot 这边说的：Bot 开着端口等别人来连，叫正向；Bot 主动去连别人，叫反向。所以应用端文档里如果写的是「反向 WebSocket 服务端」，Bot 这边就该选「WS 反向客户端」。

两边必须一个在监听、一个去连接。要是两边都在等，或者两边都在主动连，那就永远连不上。

跑通本机 HTTP 查询

这里接着用 创建第一个 Bot 里那个本机 NapCat，先确认 QQ 已登录。示例端口用 3000，被占用了就换一个，下面命令里的地址也要跟着改。

1. 添加 HTTP 服务器

1. 打开 Bot 配置，切到「连接」。
2. 在底部的新增工具条选「HTTP 服务器」。
3. 按下表填写。

Bot 的连接配置：选择连接类型，并填写地址、端口与鉴权信息 · 演示数据

4. 点对话框里的「保存连接」。
5. 再点 Bot 配置页右上角的「保存」，确认「未保存」提示消失。
6. 如果提示需要重启，就停止再启动一次 Bot，确认 QQ 已登录。

「保存连接」只是把这条连接放进了表单，右上角的「保存」才会真正把整个 Bot 配置存下来。很多人只点了前一个，然后对着一个根本没生效的连接排查半天。

2. 查询登录信息

在这台电脑上打开 PowerShell，粘贴下面的命令。提示输入的时候，粘贴刚才那条 HTTP 连接的鉴权 Token。

$token = Read-Host '粘贴 local-http 连接的鉴权 Token'
$headers = @{ Authorization = "Bearer $token" }
$result = Invoke-RestMethod `
  -Uri 'http://127.0.0.1:3000/get_login_info' `
  -Method Post `
  -Headers $headers `
  -ContentType 'application/json' `
  -Body '{}'
$result | ConvertTo-Json -Depth 5

换过端口的话，记得把命令里的 3000 也改掉。这里要粘的是 OneBot Token，不是 NapCat WebUI 的密码。

返回结果里 status 是 ok、retcode 是 0，data 里能看到当前账号的 user_id 和 nickname，就说明连接通了。

这个请求只是读一下信息，不会发出任何消息，可以放心多试几次。确认返回的 QQ 号是你那个号，再往下走。不想敲命令的话，Desktop 的 API 调试台 也能直接点鼠标调接口、看事件。

3. 请求失败时

Desktop 里装的应用端，直接用「对接」

如果应用端也是在 Desktop 里装的，就不用自己一项项去配了，让对接功能来做：

1. 先保存 Bot。新建还没保存的时候，「对接应用端」是用不了的。
2. 按 应用端实例 安装或导入应用框架。
3. 在应用实例卡片或详情里点「对接」，选这个 Bot；也可以从 Bot 的「连接」页进「对接应用端」。
4. 核对连接方向、Bot 主机、应用端主机和端口，确认保存。
5. 启动应用端和 Bot，看两边的日志。再用另一个 QQ 号给 Bot 发一条普通消息，确认应用端收到了事件。
6. 然后按插件的规则测一下指令。AI 类应用要先配好模型提供商和凭据。

Desktop 会按框架支持的方式配好正向或反向 WebSocket，支持的跨机组合还会自动走 SSH 隧道。有一个例外：Docker 部署的 Bot 目前不支持一键对接，需要按 Docker 和框架文档手动配。

名字以 ncd-app: 开头的连接是对接功能在管的。要解绑或者换 Bot，请从对接入口操作。手动改了它的话，下次对接功能写回去，两边就对不上了。

手动配置正向 WebSocket

适合这种情况：应用端支持主动去连 Bot 的 WS 服务端，而你想自己管理两边的配置。

1. 在 Bot「连接」页新增「WS 正向服务器」。
2. 同机测试时，监听 IP 填 127.0.0.1，端口比如 3001，路径 /。
3. 连接角色选 Universal（全双工，API + 事件）。只有应用明确要求拆开时，才选 API 或 Event。
4. 设好鉴权 Token，心跳间隔保持默认的 30000 毫秒，启用。
5. 「保存连接」，再保存 Bot 配置，按提示让配置生效。
6. 在应用端配置正向 WS：地址填 ws://127.0.0.1:3001/，token 和 Bot 这边保持一致。
7. 启动应用端，看到连接成功的日志后，发一条测试消息。

路径两边要一模一样，/ 和 /onebot/v11 是两个不同的地址。端口对上了不代表就配好了。

手动配置反向 WebSocket

适合这种情况：应用端自己开着 OneBot WebSocket 服务，等着 Bot 连过去。

1. 在应用端打开对应适配器的反向 WS 服务，记下它实际的监听地址、端口、路径和 Token。
2. 在 Bot「连接」页新增「WS 反向客户端」。
3. 「服务端 WebSocket URL」填应用端给出的完整地址。比如两边在同一台机器上，应用监听 8080，路径是 /onebot/v11，那就填 ws://127.0.0.1:8080/onebot/v11。
4. 连接角色按应用的要求选，一般是 Universal。心跳默认 30000 毫秒，重连默认 5000 毫秒，两个都不能低于 1000。
5. 两边的 Token 保持一致，开启「启用此连接」，保存连接，再保存 Bot 配置。
6. 先让应用端开始监听，再启动 Bot 或者应用这条连接，看两边的日志。

上面的 8080 和路径只是举个例子，实际以你的应用端配置为准。直接抄别人教程里的地址，是反向连接连不上最常见的原因。

地址、端口和 Token

Bot 和应用端不在同一台机器上的时候，本机测试用的 127.0.0.1 不能照搬过去。127.0.0.1 永远指的是「当前这台机器自己」，在服务器上写它，服务器只会去连它自己。先想清楚是谁去连谁，再从发起连接的那一边检查能不能访问到目标。

新建的连接默认会生成一个随机 Token。只要接口开放给了别的机器，就别把鉴权关掉，开放的范围也是越小越好。截图、贴日志、分享配置之前，记得先把 Token 遮掉。

其他选项

• 消息上报格式：Array 是结构化的消息段，String 是一整个字符串。按应用端适配器的要求来，不确定就用默认的 Array。
• 上报 Bot 自身消息：应用端需要处理 Bot 自己发出去的消息时才开。开之前想一下，插件会不会被 Bot 自己的回复再次触发，结果自己跟自己没完没了地聊下去。
• HTTP Webhook：填接收事件那一方的 http:// 或 https:// 地址。SnowLuma 还可以设请求超时，留空就用默认值。
• HTTP SSE：只有 NapCat 有，给需要持续接收事件流的客户端用。调 API 要不要另外配 HTTP，取决于客户端是怎么实现的。
• 兼任 WebSocket 握手 / CORS / 强制事件推送：按客户端和协议端的需要设置。CORS 只解决浏览器跨域的问题，端口不通、Token 写错，开了它也没用。
• 调试输出：排查连接时临时打开。日志里可能会带上消息内容和请求信息，分享之前检查一下。

端口范围是 1–65535，同一台机器、同一个监听地址上不能重复占用。新建 SSE 和 WS 时默认端口都可能是 3001，同时建的话自己错开。

在远端 WebUI 改过连接，重启后又变回去了

这是因为 Desktop 每次启动远端 Bot，都会用自己保存的配置覆盖远端的 OneBot 文件。所以在 WebUI 里改过的话，重启前先同步回来：

1. 打开这个 Bot 的「配置 → 连接」。
2. 点底部的「从远端读取」。
3. 看看远端比 Desktop 多了、少了、改了哪些连接。
4. 确认后填入表单，点右上角「保存」。

「从远端读取」只对已经保存过的远端 Bot 可用。

下一步，去 应用端实例 装一个应用端。想先多试试接口，可以去 API 调试台。