Runchuan-BU · cheatthegod · Mar 24, 2026 · Mar 24, 2026
diff --git a/.env.example b/.env.example
@@ -44,6 +44,14 @@ WECOM_SECRET=your-secret
 # WECOM_AGENT_ID=your-agent-id
 # WECOM_CORP_SECRET=your-corp-secret
 
+# ─── QQ Official Bot — Optional ───────────
+
+# Current QQ support covers official QQ Bot text receive/reply over WebSocket.
+# Supported inbound events: private chat messages and group @bot messages.
+# QQ_APP_ID=your-app-id
+# QQ_CLIENT_SECRET=your-client-secret
+# QQ_SANDBOX=false
+
 # ─── Feishu (Lark) — Optional ───────────────
 
 # Current Feishu support covers text receive/reply.

diff --git a/README.md b/README.md
@@ -159,7 +159,7 @@ In any connected chat, simply message:
 
 ## Messaging channels
 
-Supported platforms include **WhatsApp** (default), **Feishu (Lark)**, **WeCom**, **Discord**, **Slack** (Socket Mode), **WeChat Personal** (experimental), and optional **local web** (browser) chat. Full setup steps, env vars, and disabling channels are in **[docs/CHANNELS.md](docs/CHANNELS.md)** (简体中文：[docs/CHANNELS.zh-CN.md](docs/CHANNELS.zh-CN.md)).
+Supported platforms include **WhatsApp** (default), **QQ Official Bot**, **Feishu (Lark)**, **WeCom**, **Discord**, **Slack** (Socket Mode), **WeChat Personal** (experimental), and optional **local web** (browser) chat. Full setup steps, env vars, and disabling channels are in **[docs/CHANNELS.md](docs/CHANNELS.md)** (简体中文：[docs/CHANNELS.zh-CN.md](docs/CHANNELS.zh-CN.md)).
 
 **Lab trace** (SSE timeline, workspace tree) is built into the local web UI — no extra config needed. See **[docs/DASHBOARD.md](docs/DASHBOARD.md)**.
 

diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -38,7 +38,7 @@ BioClaw 将常见的生物信息学任务带到聊天界面中。研究者可以
 - 差异分析可视化（火山图等）
 - 文献检索与摘要
 
-默认通道为 WhatsApp；飞书、企业微信、Discord、Slack、本地网页等配置见 **[docs/CHANNELS.zh-CN.md](docs/CHANNELS.zh-CN.md)**。飞书的完整配置、OpenRouter 设置、群聊限制与排障见 **[docs/FEISHU_SETUP.zh-CN.md](docs/FEISHU_SETUP.zh-CN.md)**。QQ 相关截图仍为路线图示意，详见该文档。
+默认通道为 WhatsApp；QQ 官方 Bot、飞书、企业微信、Discord、Slack、本地网页等配置见 **[docs/CHANNELS.zh-CN.md](docs/CHANNELS.zh-CN.md)**。飞书的完整配置、OpenRouter 设置、群聊限制与排障见 **[docs/FEISHU_SETUP.zh-CN.md](docs/FEISHU_SETUP.zh-CN.md)**；QQ 的完整步骤与排障见 **[docs/QQ_SETUP.zh-CN.md](docs/QQ_SETUP.zh-CN.md)**。
 
 ## 快速开始
 

diff --git a/docs/CHANNELS.md b/docs/CHANNELS.md
@@ -50,6 +50,37 @@ The server IP must be on that app’s trusted IP whitelist.
 
 ---
 
+## QQ Official Bot
+
+BioClaw currently supports **official QQ Bot** text receive/reply over **WebSocket**.
+
+Supported inbound events in the current MVP:
+- `C2C_MESSAGE_CREATE` for private chat messages
+- `GROUP_AT_MESSAGE_CREATE` for group `@bot` messages
+
+1. Create a bot app in the QQ Open Platform (`q.qq.com`).
+2. Enable **WebSocket** event delivery for the bot.
+3. Subscribe the private-chat and group-@bot message events (the current implementation listens with `1 << 25`, the combined group/C2C intent documented by QQ Bot).
+4. Add these variables to `.env`:
+
+   ```bash
+   QQ_APP_ID=your-app-id
+   QQ_CLIENT_SECRET=your-client-secret
+   # Optional: use QQ sandbox gateway/API endpoints
+   # QQ_SANDBOX=true
+   ```
+
+5. Start BioClaw. The first private message or group `@bot` message auto-registers that conversation.
+
+Current limits:
+- Official QQ Bot only; no personal QQ automation
+- Text-only send/receive in this first version
+- Group replies are intended for `@bot` message flows
+
+Chinese setup notes: [QQ_SETUP.zh-CN.md](QQ_SETUP.zh-CN.md)
+
+---
+
 ## Feishu (Lark)
 
 BioClaw currently supports **text receive/reply** for Feishu bots. Start with **WebSocket mode** if possible; use webhook mode only when your deployment requires inbound HTTP callbacks.

diff --git a/docs/CHANNELS.zh-CN.md b/docs/CHANNELS.zh-CN.md
@@ -51,6 +51,37 @@ WECOM_CORP_SECRET=应用 Secret
 
 ---
 
+## QQ 官方 Bot
+
+BioClaw 当前已支持 **QQ 官方 Bot** 的**文本消息收发**，接入方式为 **WebSocket**。
+
+当前 MVP 支持的入站事件：
+- `C2C_MESSAGE_CREATE`：QQ 私聊机器人
+- `GROUP_AT_MESSAGE_CREATE`：群里 `@` 机器人
+
+1. 在 QQ 开放平台创建机器人应用。
+2. 在机器人配置里启用 **WebSocket** 接收事件。
+3. 订阅私聊消息和群聊 `@机器人` 消息事件。
+4. 在 `.env` 中至少配置：
+
+   ```bash
+   QQ_APP_ID=your-app-id
+   QQ_CLIENT_SECRET=your-client-secret
+   # 可选：若使用 QQ 沙盒环境
+   # QQ_SANDBOX=true
+   ```
+
+5. 启动 BioClaw 后，第一条私聊消息或群里 `@机器人` 的消息会自动注册该会话。
+
+当前限制：
+- 仅支持 **官方 QQ Bot**，不支持个人 QQ 自动化
+- 第一版只做文本消息
+- 群聊场景按 `@机器人` 触发路径实现
+
+详细中文步骤与排障见 [QQ 接入实操与排障指南](QQ_SETUP.zh-CN.md)。
+
+---
+
 ## 飞书（Lark）
 
 BioClaw 当前已支持**飞书文本消息收发**。优先建议使用 **WebSocket / 长连接**；只有在部署环境必须走公网回调时，再切到 webhook。
@@ -189,21 +220,3 @@ BioClaw 使用 **[Socket Mode](https://api.slack.com/apis/socket-mode)** 长连
 - 只关 WhatsApp：`DISABLE_WHATSAPP=1` 或 `ENABLE_WHATSAPP=false`。
 - 不用的通道：对应 token 留空或不配置即可（飞书、企业微信、Discord、Slack 都是如此；Slack 需同时配置 `SLACK_BOT_TOKEN` 与 `SLACK_APP_TOKEN`）。
 
----
-
-## QQ 说明（路线图）
-
-以下截图用于展示**QQ 通道**这一产品扩展方向；当前仓库内**仍没有**可直接启用的 QQ 通道实现，请勿按 QQ 文档期待开箱即用。
-
-### QQ + DeepSeek（示意）
-
-<div align="center">
-<img src="images/qq/qq-deepseek-1.jpg" width="420" alt="QQ DeepSeek demo 1">
-</div>
-
-<div align="center">
-<img src="images/qq/qq-deepseek-2.jpg" width="420" alt="QQ DeepSeek demo 2">
-</div>
-
-
-任务类演示仍见 [ExampleTask/ExampleTask.md](../ExampleTask/ExampleTask.md)。
diff --git a/docs/QQ_SETUP.zh-CN.md b/docs/QQ_SETUP.zh-CN.md
@@ -0,0 +1,171 @@
+# QQ 接入实操与排障指南
+
+本文档对应当前 BioClaw 中已经落地的 **QQ 官方 Bot 文本版**。
+
+当前支持范围：
+- QQ 官方 Bot
+- WebSocket 长连接接收事件
+- 私聊消息：`C2C_MESSAGE_CREATE`
+- 群里 `@机器人` 消息：`GROUP_AT_MESSAGE_CREATE`
+- 文本回复
+
+当前不支持：
+- 个人 QQ 自动化
+- 图片 / 文件发送
+- webhook 模式
+- 频道场景的完整适配
+
+## 1. 前提
+
+1. 你使用的是 **QQ 开放平台 / 官方 Bot**，不是个人 QQ 号自动化。
+2. 服务器可以访问：
+   - `https://bots.qq.com`
+   - `https://api.sgroup.qq.com`
+3. BioClaw 已能正常启动，模型提供商配置正确。
+
+## 2. 在 QQ 开放平台里做什么
+
+1. 创建机器人应用。
+2. 记录：
+   - `App ID`
+   - `Client Secret`
+3. 在机器人配置里启用 **WebSocket** 接收事件。
+4. 订阅这两个事件：
+   - 私聊消息
+   - 群聊 `@机器人` 消息
+5. 如果平台区分沙盒与正式环境，先确认你当前使用的是哪一个。
+
+说明：当前 BioClaw 的 QQ 通道监听的是官方文档中的 group/C2C 组合 intent（`1 << 25`），对应私聊和群里 `@机器人` 两类消息事件。
+
+## 3. 写入服务器 `.env`
+
+在服务器执行：
+
+```bash
+cd /home/ubuntu/cqr_files/Bioclaw_new/BioClaw
+
+[ -f .env ] || cp .env.example .env
+cp .env ".env.bak.$(date +%F-%H%M%S)"
+
+upsert_env() {
+  key="$1"
+  value="$2"
+  if grep -q "^${key}=" .env; then
+    sed -i "s|^${key}=.*|${key}=${value}|" .env
+  else
+    printf '%s=%s\n' "$key" "$value" >> .env
+  fi
+}
+
+read -rp 'QQ App ID: ' QQ_APP_ID_INPUT
+read -rsp 'QQ Client Secret: ' QQ_CLIENT_SECRET_INPUT
+echo
+
+upsert_env QQ_APP_ID "$QQ_APP_ID_INPUT"
+upsert_env QQ_CLIENT_SECRET "$QQ_CLIENT_SECRET_INPUT"
+# 如使用沙盒环境，再打开这一行
+# upsert_env QQ_SANDBOX true
+
+unset QQ_APP_ID_INPUT QQ_CLIENT_SECRET_INPUT
+
+grep -E '^(QQ_APP_ID|QQ_SANDBOX)=' .env || true
+grep '^QQ_CLIENT_SECRET=' .env | sed 's/=.*/=***hidden***/'
+```
+
+## 4. 启动
+
+```bash
+cd /home/ubuntu/cqr_files/Bioclaw_new/BioClaw
+source /home/ubuntu/.nvm/nvm.sh
+nvm use 22
+npm run build
+npm start
+```
+
+如果 QQ 长连接成功，终端里应出现：
+
+```text
+Connected to QQ (websocket)
+```
+
+## 5. 如何测试
+
+### 5.1 私聊测试
+
+直接给机器人发：
+
+```text
+你好
+```
+
+期望日志：
+
+```text
+QQ direct message received
+QQ message sent
+```
+
+### 5.2 群聊测试
+
+把机器人加入群后，在群里发送：
+
+```text
+@机器人 你好
+```
+
+期望日志：
+
+```text
+QQ group message received
+QQ message sent
+```
+
+## 6. 常见问题
+
+### 6.1 没有任何 QQ 日志
+
+重点检查：
+- 机器人应用是否真的启用了 WebSocket
+- 私聊 / 群里 `@机器人` 事件是否已订阅
+- 服务器是否能访问 `bots.qq.com` 与 `api.sgroup.qq.com`
+- `.env` 中 `QQ_APP_ID` / `QQ_CLIENT_SECRET` 是否对应同一个应用
+
+### 6.2 提示模型 API key 无效
+
+这不是 QQ 问题，而是模型提供商配置问题。优先检查：
+- `MODEL_PROVIDER`
+- `OPENROUTER_API_KEY`
+- 或 `ANTHROPIC_API_KEY`
+
+### 6.3 群里发普通消息机器人不回
+
+当前实现按官方 `GROUP_AT_MESSAGE_CREATE` 路径工作。第一版默认只保证：
+- 私聊消息
+- 群里 `@机器人` 的消息
+
+所以群里测试时请先显式 `@机器人`。
+
+### 6.4 这是个人 QQ 机器人吗
+
+不是。当前实现只支持 **官方 QQ Bot**。
+
+## 7. 当前实现边界
+
+当前版本为了稳妥，只做了最小可用集：
+- 自动注册 QQ 会话
+- 文本收发
+- 私聊与群 `@机器人`
+
+后续如果需要，再扩展：
+- 图片 / 文件
+- webhook 模式
+- 更完整的富消息
+- 更细的群资料同步
+
+## 8. 参考
+
+- QQ 机器人官方文档：<https://bot.q.qq.com/wiki/develop/api-v2/>
+- WebSocket 接入说明：<https://bot.q.qq.com/wiki/develop/api-v2/dev-prepare/interface-framework/reference.html>
+- 事件订阅与通知：<https://bot.q.qq.com/wiki/develop/api-v2/dev-prepare/interface-framework/event-emit.html>
+- 消息事件：<https://bot.q.qq.com/wiki/develop/api-v2/server-inter/message/send-receive/event.html>
+- 发送消息：<https://bot.q.qq.com/wiki/develop/api-v2/server-inter/message/send-receive/send.html>
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -33,6 +33,7 @@
     "pino": "^9.6.0",
     "pino-pretty": "^13.0.0",
     "qrcode-terminal": "^0.12.0",
+    "ws": "^8.19.0",
     "weixin-agent-sdk": "^0.1.0",
     "zod": "^4.3.6"
   },