QQ机器人一键部署 EiyoV/qq-bot-oneclick

QQ 机器人 · 一键启动器

把 qq-bridge 那套「QQ ↔ DSH agent」接起来，做成下载后双击一次就能用的形式。

用的是 SnowLuma（QQ 协议网关）+ qq-bridge（桥接）+ DSH（AI 大脑）。

它做了什么

| 你双击 | 它自动完成 |
| 一键部署.bat | 下载 SnowLuma → 克隆 qq-bridge → 装依赖 → 接进 DSH（2 个 preset + 3 个 MCP）→ 配置向导 |
| 启动(静默).vbs | 拉起 SnowLuma（没跑的话）→ 补齐 token → 后台守护运行 qq-bridge，没有任何窗口 |
| 停止机器人.bat | 停掉机器人（SnowLuma 留着，下次启动不用重新扫码） |
| 重新配置.bat | 改 QQ 号 / 群号 / SnowLuma token（回车 = 保留原值） |

前置条件

这三样必须自己先装好（脚本会检查并提示，但不会替你装）：

| # | 需要 | 为什么要 | 缺了会怎样 |
| 1 | Node.js ≥ 22.13 — nodejs.org 装 LTS | 所有脚本和 qq-bridge 都跑在 Node 上 | 双击 .vbs 会弹窗告诉你「Node.js was not found」 |
| 2 | Git for Windows | 用来克隆 qq-bridge | 部署窗口打印「没找到 git」并退出 |
| 3 | DSH 桌面版，并且至少启动过一次 | 脚本要往 ~/.dsh/profiles/*/cordis.patch.yml 写配置 | 打印「没找到 DSH profile」并退出 |

⚠️ 第 3 条最容易忽略。 光装好 DSH 不够 —— 必须真的打开过一次，它才会生成 ~/.dsh/profiles/ 目录。没跑过的话脚本无处可写，会直接报错。

正确顺序：装好 DSH → 打开一次（看到界面就行）→ 关掉 → 再来跑一键部署。

可选但推荐：先装 llm-router 插件 ——脚本会自动检测并配置「免费池」路由（多 API 自动切换 + 免费额度熔断，省钱）。
没装也能用，只是会退回 DSH 的默认 API，并且每次开新会话会提醒你一次。

怎么用

第一次

0. 只要认一个按钮也行：直接双击 启动(静默).vbs └─ 它发现你没部署过，会自己弹出部署窗口，跑完自动接着启动（下面按"分开来做"写，方便你知道每一步在干嘛）

1. 双击 一键部署.bat └─ 跟着提示填：管理员 QQ 号 / 群号（token 这步留空，见第 5 步）

2. 重启 DSH（关掉再打开）—— 新的 preset 和 MCP 只在启动时加载

3. 双击 启动(静默).vbs └─ 自动拉起 SnowLuma、自动打开浏览器到 WebUI └─ 自动把初始登录密码抄到「SnowLuma首次登录密码.txt」并弹出来

4. 在 SnowLuma 的 WebUI 里：
· 用那个密码登录（建议立刻改掉，初始密码关掉就找不回）
· 扫码登录 QQ
· 网络配置 → OneBot 协议端点 → 打开 WS 服务端(3001) 和 HTTP API(3000) → 点保存

5. 再启动一次 —— 这一步是把手上的 token 交给机器人：
· 双击 停止机器人.bat
· 双击 启动(静默).vbs └─ 这次它发现缺 token，会弹一个窗口让你填（token 在 WebUI → OneBot 协议端点 → WS 服务端那一行的铅笔图标里）

6. 完事。在 QQ 里私聊机器人（或 @ 它）就能聊了

为什么要有第 5 步？ 部署的时候 SnowLuma 还没登录，那时候根本没有 token 可填。
所以启动器会在每次启动时检查：先试着从 SnowLuma 自己的配置里自动读，读不到（有些版本不落盘）才弹窗让你手动填一次。填过之后就不再问了。

想改 QQ 号 / 群号 / token，随时双击 重新配置.bat。

以后

- 开机用：双击 启动(静默).vbs
- 不用了：双击 停止机器人.bat

改人格 / 调功能

最省事的入口是控制台：机器人跑起来后打开 <http://127.0.0.1:3100> （令牌在 vendor/qq-bridge/state/console-token，启动日志里也会打印）。
白名单、人格、运行模式、思考强度、token 花费都在里面点，即时生效不用重启。

人格在控制台的「人格与角色」页直接新建/编辑，不用手写文件。
想在 QQ 里切：发 /role <角色名>（仅管理员号），/role off 清除。

细项配置（表情包、语音、潜水唤醒、黑话、主动发言、省钱……）见 功能配置说明.md，里面还有一张管理员命令速查表。

出问题看哪里

| 现象 | 先看 | 常见原因 |
| 双击没反应 | logs/launcher.log | Node 没装 / 没先跑 一键部署.bat（静默启动本来就没窗口） |
| QQ 里没反应 | logs/bridge.log | 白名单是空的（fail-closed）/ SnowLuma 没连上 |
| 它明明看懂了却不说话 | logs/bridge.log 里找 unauthorized | ⭐ accessToken 填成了 WS token —— 见下面专门一节 |
| 连不上 SnowLuma | logs/bridge.log 里找 401 | access token 没填 → 双击 重新配置.bat 填一次 |
| WebUI 密码不知道 | 目录里的 SnowLuma首次登录密码.txt | 启动器会自动生成；没有就去 logs/snowluma.log 搜 initial credentials |
| DSH 报 bundle 解析失败 | — | 重跑一次 一键部署.bat（它会补 pnpm install） |
| 模型没用上免费池 | logs/bridge.log 里找 does not support reasoning effort | DSH 路由的模型缺 reasoningEfforts → 重启 DSH 前先按报错补上 |

空白名单 = 什么都不回，这是 qq-bridge 的安全默认值。
群里要回话，必须把群号填进配置 —— 双击 重新配置.bat 即可改。

⭐ SnowLuma 有两个不同的 token（最容易踩的坑）

SnowLuma 同一个账号的这两个 token 是两个不一样的值：

| 端口 | 用途 | 对应 |
| 3000 | HTTP API —— 发消息 | config.json 的 snowluma.accessToken ← 要填这个 |
| 3001 | WebSocket —— 收消息 | 桥接会自己从 SnowLuma 配置里读出来自愈，不用你管 |

填错的症状非常隐蔽：日志显示 SnowLuma 已连接、消息收得到、AI 也正常回复了，但每条 send_private_msg 都返回 unauthorized —— 看起来像"它懂了但不理你"。

- 两个 token 都在 snowluma-pkg/app/config/onebot_<QQ号>.json 里：
networks.httpServers[0].accessToken（3000）和 networks.wsServers[0].accessToken（3001）
- 一键启动器现在会自动读 HTTP 那个，并在保存前真实调用接口验证，所以新装不会再踩
- 已经装错了：双击 重新配置.bat，把 HTTP 那个填进去即可（向导会当场告诉你对不对）

目录说明

qq-bot-oneclick/
├── 一键部署.bat ← 首次运行 ├── 启动(静默).vbs ← 日常启动 ├── 停止机器人.bat ← 停止 ├── 重新配置.bat ← 改 QQ 号 / 群号 / token ├── 功能配置说明.md ← ⭐ 各项功能怎么配 + 命令速查 ├── scripts/ │ ├── bootstrap.mjs ← 部署主流程 │ ├── setup.mjs ← 配置向导 │ ├── launcher.mjs ← 守护启动器 │ ├── install-snowluma.mjs │ └── lib/ │ ├── dsh.mjs ← 把 qq-bridge 接进 DSH │ └── util.mjs ├── vendor/qq-bridge/ ← 自动克隆（不进仓库） ├── snowluma-pkg/ ← 自动下载（不进仓库） ├── logs/ ← 运行日志 └── config.json ← 你的配置（不进仓库）

关于 DSH 侧的修改

脚本会动 DSH 的 profile 配置（不是插件源码）：

- ~/.dsh/profiles/<profile>/package.json — 注册 2 个 bundle
- ~/.dsh/profiles/<profile>/cordis.patch.yml — 追加 3 个 MCP 条目（标记块方式，保留注释和 !!js；原文件会备份成 .bak-launcher）
- ~/.dsh/plugins/ 和 profile 的 node_modules/ — 建 4 个 junction 软链接

这些是 qq-bridge 官方 setup-dsh.mjs 干的事。之所以自己实现：官方脚本用 YAML 解析器重写整个 cordis.patch.yml，注释和 DSH 特有的 !!js 表达式都会丢，遇到 !!js 甚至直接解析失败。所以这里只替换标记块，绝不碰文件其他内容。

致谢

- SnowLuma — QQ 协议网关
- Derpyu520/qq-bridge — QQ ↔ DSH 桥接
- DeepSeek Harness — AI 运行时