dsh-qq

让 DeepSeek Harness 接入你的 QQ：聊天、看图看视频、查记录、发消息，都在一个插件里。

安装使用 · SnowLuma 一键部署 · 原生迁移 · 高级配置 · 反馈问题

能做什么

功能	实际用法
QQ 对话	群里 @ 机器人、引用它的消息，或私聊它
图片、动图、视频	发给机器人，让它看内容；也能展开合并转发里的聊天和媒体
在 DSH 里操作 QQ	让助手发消息、查群成员、找历史聊天、查看人物档案
统一面板	查看在线状态、会话和日志，修改配置，开关自动聊天；打开 QQ 登录页人工登录
按需扩展	表情包、生图、学习、资讯分享、QQ 空间和群管理

部分扩展取决于后端权限和外部服务；看图需要视觉模型，动图/视频需要 ffmpeg。

安装使用

1. 准备好这三样

• DSH，运行环境 Node.js 22.13 或更新版本。
• NapCat / SnowLuma / OneBot 后端，拿到 HTTP、正向 WebSocket 地址和 Token。NapCat 可直接在官方 WebUI 扫码，不需要 VNC。详见 NapCat 接入。
• 模型接口：OpenAI 兼容的接口地址、模型名和 API Key。

没有 QQ 后端？ 安装插件后打开 DSH 设置 → QQ 机器人 → 接入与部署 → 一键部署 SnowLuma。支持运行 DSH 的 Linux / Windows 宿主；缺少 Docker 时，可单独授权准备依赖。所有确认框默认不勾选，点击并确认后才部署；已有容器核对复用，不重建、不重置密码或登录。Windows 的 UAC、Docker Desktop 许可、WSL2、重启及 QQ 登录可能需要本人操作，不能全自动完成。详见一键部署与手动脚本。插件不捆绑镜像、不隐式安装、不代取得所需部署授权或接受上游 / QQ 条款。NapCat 仍可作为已有后端连接。

2. 安装插件

在 DSH 对话里把这句话发给助手：

帮我从 https://github.com/oka-rin/dsh-qq 安装这个插件。

安装来源为这个 GitHub 仓库，不是 npm 上的同名包。也可以下载源码，再在 DSH 插件管理器中用本地目录安装。

3. 连接 QQ 和模型

打开 DSH 设置 → QQ 机器人 → 接入与部署。使用上方一键部署后，先在原版网页登录 QQ，并按 SnowLuma 原版流程人工审阅条款、配置网关 hook，再检测连接；新建部署只保存本机 OneBot 接入信息，不代表已在线。已有后端可直接填写：

填什么	示例
OneBot HTTP 地址	http://127.0.0.1:3000
OneBot WebSocket 地址	ws://127.0.0.1:3001/event
OneBot Token	你在后端设置的令牌，不是 QQ 密码
模型接口 / 模型名 / API Key	你的模型服务提供的内容

示例端口不是固定要求，以你的后端设置为准。向导只直接连接本机后端；远程后端见高级配置。

NapCat 还没登录？ 在插件配置选择 gatewayBackend: napcat，填好服务名、WebUI 端口与私有配置文件路径；点 复制 NapCat 登录令牌，再打开官方 WebUI，粘贴令牌后扫描 QQ 登录二维码。普通 HTTP 可用，但令牌和扫码信息仍可能被窃听；页面依赖 NapCat 自身鉴权，不继承 DSH 会话。不要把令牌或密码发到聊天。然后将机器人「连接」里的 onebot.gateway 设为 napcat 并填写实际 HTTP / WS 地址，检测并重启。

既有 SnowLuma 登录：点 打开 QQ 登录页；Docker 模式恢复使用已有 SnowLuma 原版 noVNC，可先点 复制远程桌面密码，再打开登录页，在原版 VNC 提示中粘贴 VNC 密码（不是 QQ 密码），然后操作真实 QQ；原生模式如已由操作者部署原版 noVNC，可在插件配置设置 snowLumaDesktopPort 为该端口以沿用原版入口（默认 0 不启用）；未设置的原生 / external 模式仍使用现有登录桥接。DSH 认证只保护 Docker 的跳转入口，目标桌面依赖原版 VNC 密码和现有访问规则，不受 DSH Cookie 或 10 分钟会话限制保护。支持你已接受风险的普通 HTTP；原版提示 “Connected (unencrypted)” 是传输未加密的警告，不是认证失败，可继续操作，但画面和输入可能被窃听，可信 HTTPS 更安全，不强制改用 HTTPS/SSH。复制按钮仅在已认证浏览器中显式读取，普通 HTTP 也有兼容复制；权限被浏览器拒绝时可短时手动复制，界面临时值 30 秒后清除，不写入模型工具或日志。不要把 VNC 或 QQ 密码发到聊天里。入口不会启动后端、接受条款或完成迁移；详见登录说明。

点击 检测 OneBot 连接 → 检测成功，保存接入配置，然后到「运维」重启机器人。这一步只检测 QQ 连接，模型是否可用要靠下一步试聊确认。

4. 开启聊天，发一条试试

新安装默认不开口。在配置里开启聊天，按需开启私聊回复；用于群聊时先填允许的群，再启用。群白名单留空表示不限制群。

在 QQ 私聊机器人，或在允许的群里 @ 它，发一句“你好”。收到了回复，再按需打开视觉、动图、视频和转发展开开关，试发对应消息；这些能力新安装也默认关闭。

装好后可以这样用

在 DSH 对话里直接说，不需要背工具名：

• “看看 QQ 机器人在线没有。”
• “列出机器人加入的群。”
• “看看这个群最近在聊什么。”
• “查一下之前聊过的视频。”
• “给这个群发一条消息：今晚八点开始。”（指定目标群）
• “为什么机器人刚才没回复？”

常见问题

连接检查通过，但不回复？ 先检查聊天开关、私聊开关和群范围，再让助手查“为什么没回复”；连接成功不会自动开启发言。

看不到图片或视频？ 图片需要支持视觉的模型；动图和视频还需要 ffmpeg / ffprobe。大视频下载和抽帧需要时间，没拿到画面时不应编造内容。

已经用 Docker 跑着 SnowLuma？ 可继续连接原实例，使用 Docker 兼容模式。想迁到原生时按备份、切换与回滚步骤操作；安装脚本不会停止容器、复制登录态或删除卷，扫码登录和验收仍需人工完成。

更新会丢聊天记录吗？ 配置、聊天归档和学习数据放在独立数据目录，不在插件代码里。沿用原 dataDir 并先备份，不要另开一个机器人实例。一键部署的网关选择保存在 dataDir/gateway-deployment.json，优先于旧插件后端选择；不会搬迁聊天和档案数据。迁移与回滚

更多

• 原生安装与 Docker 迁移：只读预览、显式安装、受保护的登录、切换与回滚。
• 高级配置与运维：配置字段、systemd、Docker、数据目录和安全边界。
• 参与开发 · 报告安全问题 · 更新记录
• 源码采用 MIT。NapCat、SnowLuma、QQ 和模型服务遵循各自条款；插件安装或连接不会隐式运行后端安装脚本。