qq-bridge

让 DeepSeek 智能体住进 QQ 群，像真人一样聊天

开源 🏷️完全免费 🔧 仅开源项目，无在线服务，需自行部署智能体 🍴 复刻 224 🐛 待处理 53 👀 关注 6

GitHub ↗

GitHub 星标 ★ 3595

维护状态活跃

是否开源开源

定价模式 🏷️完全免费开源项目，无官方定价信息

项目预览

项目数据

分类智能体

开发团队Derpyu520

GitHubhttps://github.com/Derpyu520/qq-bridge

定价模式🏷️完全免费

价格说明开源项目，无官方定价信息

访问状态🔧 仅开源项目，无在线服务，需自行部署

是否开源是

开源协议NOASSERTION

主要语言JavaScript

技术栈/模型ai-agent,chatbot,deepseek-harness,dsh,onebot,qq-bot,snowluma

GitHub 星标★ 3595

上线时间2026-08-25 00:00:00

代码更新2026-11-06

仓库体积13.7 MB

本站数据更新2026-11-08

维护状态活跃

收录时间2026-09-25

浏览次数26

项目介绍

qq-bridge 是一个把 QQ 聊天平台与 DeepSeek Harness 智能体框架打通的开源桥接项目。它基于 SnowLuma 的 OneBot v11 协议接入 QQ，让 AI 智能体能够以真实用户身份参与群聊和私聊。项目解决的核心问题是：如何让通用大模型智能体在中文社交场景里自然互动，而不是只会机械回复。它提供社交模拟能力，让智能体理解群聊氛围、模仿人类发言节奏；内置安全的 MCP 工具调用机制，限制智能体可执行的操作范围，避免误操作或滥用；还支持网络用语和黑话的持续学习，使回复更贴近真实网友。整体用 JavaScript 编写，部署门槛不高，适合想快速搭建 QQ 机器人并接入 DeepSeek 能力的开发者。

Star 增长趋势

本站每日记录该项目 GitHub 星标变化，观测越久曲线越完整

数据来源：GitHub API 逐日快照 · 收录于 2026-09-25 · 当前星标 ★ 3595

技术标签

ai-agent chatbot deepseek-harness dsh onebot

使用教程

难度：进阶约 30 分钟部署方式：本地安装 7 步

环境要求

已安装并运行的 DSH（Web 地址默认 http://127.0.0.1:3080）
Node.js 与 npm 环境（用于 npm install / npm start）
下载并解压好的 SnowLuma（OneBot v11 服务端；Win x64 完整版自带 Node 运行时）
可扫码登录的 QQ 账号

安装与启动步骤

1确认 DSH 已运行

打开 http://127.0.0.1:3080 能正常访问即可，DSH 已运行无需其他操作，本步不执行命令。
2克隆并安装依赖

克隆仓库后执行 npm install，postinstall 会自动修补 @snowluma/sdk 的 ESM 打包 bug。
```
git clone https://github.com/Derpyu520/qq-bridge.git
cd qq-bridge
npm install
```
3复制配置模板

从脱敏模板生成 config.json；Windows CMD 用户改用 copy config.example.json config.json。
```
cp config.example.json config.json
```
4安装 DSH 端组件

安装 qq-chat / qq-chat-v2 preset 并挂载 MCP，单机新装也必须执行，装完必须重启 DSH。
```
node scripts/setup-dsh.mjs
```
5下载启动 SnowLuma

下载 releases 里的 SnowLuma-v<版本>-win-x64.zip 完整版，解压到任意目录（如 C:\SnowLuma）后双击 launcher.bat。
6WebUI 引导与填配置

用启动日志里的初始密码登录 WebUI 完成扫码登录，开启 OneBot 的 WebSocket 服务端与 HTTP API，再把端口与 token 回填 config.json 的 snowluma 段和白名单。
7启动桥接

前台运行 npm start（崩溃不自动重启）；Windows 想要崩溃自动重启请双击 start.bat。
```
npm start
```

关键配置

配置项	必填	说明	示例
`dsh.baseUrl`	否	DSH Web 地址，示例与默认值一致。	`http://127.0.0.1:3080`
`dsh.authToken`	否	DSH launch token，通常留空：留空时用 ~/.dsh/.credentials.yaml 签名密钥离线铸造 Cookie。
`snowluma.wsUrl`	是	SnowLuma OneBot WebSocket 地址，端口要与 WebUI 一致。	`ws://127.0.0.1:3001`
`snowluma.httpUrl`	是	OneBot HTTP API 地址，不要填 WebSocket 端口，否则报 HTTP 426。	`http://127.0.0.1:3000`
`snowluma.accessToken`	否	OneBot accessToken，WebUI 里没配置就留空。
`allow.private / allow.groups`	是	白名单 QQ 号/群号数组，示例模板为空数组，空白名单时不响应任何消息。	`["12345678"]`

如何确认成功

启动日志出现「SnowLuma 已连接：ws://127.0.0.1:3001」，再在 QQ 给机器人账号发消息能收到 agent 回复。

常见问题

Q：QQ 上发消息完全没有反应？

A：多半漏了第 2、3 步：DSH 端脚本 scripts/setup-dsh.mjs 没执行或没重启 DSH。缺少 qq-chat preset 时桥接会拒绝建会话，白名单为空也不会响应。

Q：日志报 HTTP 426 错误？

A：snowluma.httpUrl 填成了 OneBot 的 WebSocket 端口。HTTP API 与 WebSocket 是两个端口（默认 3000 / 3001），不要填成同一个。

Q：提示「已有实例在运行」怎么办？

A：桥接有单实例锁，只能跑一个实例。双击 restart.bat 可自动杀旧实例、清理锁并重启守护进程。

Q：重启 DSH 后需要重启桥接吗？

A：通常不用。桥接每 5 秒探活，DSH 不可用期间收到的消息在桥接进程内排队（每会话最多 50 条），恢复后尝试补投；桥接进程退出队列会丢失。

Q：我的 DSH 版本很旧能直接用吗？

A：v0.2.0 适配 DSH 0.2.0-rc.2。DSH 0.1.1-rc.2 及更早请用 v0.1.0，0.1.5-rc.1 用 v0.1.5，0.1.7-rc.2 用 v0.1.7。

注意事项

改 config.json、roles/ 或 state/current-role.json 后要重启桥接生效；改 dsh/agent-presets/ 需先跑 node scripts/build-agent-preset-patches.mjs 再重启 DSH。
桥接不会启动或停止 SnowLuma，SnowLuma 需自行下载启动。
真实 config.json 与 state/ 不会进入公开仓库，仓库只提供脱敏模板。
allowAllWhenEmpty 为 true 时白名单留空会放行全部消息，等于把账号控制权交给模型，建议先填白名单。