QQ 接入
Alice 通过 NapCat / OneBot 11 WebSocket 接入 QQ。普通 Windows 用户默认使用应用内 NapCat desktop；Docker 和 external 仅面向了解网络与凭据管理的高级用户。
需求
- 已安装并启动 Windows Alice。
- 一个专用 QQ 账号；第三方协议登录存在平台风控风险。
- 已在 Alice UI 中添加并测试模型。
- 明确允许的私聊、群聊、管理员和
@触发范围。 - 高级模式另需 Docker Desktop，或一个已部署的外部 OneBot WebSocket 服务。
架构
QQ 用户 ↔ NapCat / OneBot WebSocket ↔ Alice QQ 账号
↓
QQ 智能体模型
└─ 可选：主智能体与 Minecraft部署模式：
| 模式 | 定位 | 说明 |
|---|---|---|
desktop | 默认 | Alice 向导自动或手动安装 NapCat，并托管本机进程 |
docker | 高级 | 由 Docker 容器运行 NapCat，需要自行维护端口和数据卷 |
external | 高级 | Alice 连接现有 OneBot WebSocket，需要正确地址和 Token |
纯 QQ 对话不要求 Minecraft 在线；只有转交游戏操作时才需要主智能体及工作区在线。
执行
默认 desktop 路径
- 在 Alice“模型”页面添加模型并测试连接。
- 创建智能体，选择主模型及可选 QQ 模型。
- 打开“机器人”页面，选择桌面版 NapCat。
- 优先使用自动安装；失败时下载 Windows 包并在向导中选择正确的解压目录进行验证。
- 启动账号流程，扫码或按提示登录，等待账号显示在线。
- 将账号绑定到智能体，配置私聊、群聊、白名单、管理员和
@规则。 - 从允许范围发送普通问候进行验证。
高级 docker / external 路径
仅在具备运维能力时选择。Docker 模式需持久化 NapCat 数据并限制管理端口；external 模式需在 UI 中填写正确的 ws/wss 地址和访问令牌。不要把 OneBot 或 WebUI 管理端口直接暴露到公网。
验收与安全
成功标志是账号在线、入站消息可见、绑定的 QQ 智能体返回回复。账号在线但不回复时检查模型、绑定、白名单和 @ 规则。不要分享二维码、Token、登录态、API Key 或私人聊天记录。