QQ-relay-BOT-official

交流群 QQ 940358918

基于 QQ 官方机器人 API 的群聊 AI 机器人。管道模式持续上下文 + 骰子 + 主动发言 + 插件系统 + WebUI 管理面板。

1. 项目概述

基于 QQ 官方 Bot API 的轻量群聊机器人。通过 WebSocket 收事件 + REST API 回消息，无需第三方协议。AI 后端通过 Claude Code CLI 代理到 DeepSeek API，使用 --resume / --session-id 保持跨消息的持续对话上下文。

这不是一个通用转发框架，而是一个"让 AI 活在 QQ 群里"的完整应用。

2. 快速开始

前置依赖

组件	获取方式
QQ 官方机器人	在 q.qq.com 注册并通过审核
Python 3.10+	relay.py + webui.py 运行环境
Node.js（含 npm）	Claude Code CLI 运行环境
Claude Code CLI	`npm install -g @anthropic-ai/claude-code`

安装

pip install -r requirements.txt

配置

复制 .env.example → .env，填写以下变量：

变量	说明
`QQ_APP_ID`	应用 ID（q.qq.com 后台获取）
`QQ_CLIENT_SECRET`	应用密钥
`DEEPSEEK_API_KEY`	DeepSeek API 密钥（AI 后端认证）
`MASTER_OPENID`	主人的 member_openid（留空则无人享有写权限）
`CLAUDE_CMD`	Claude Code CLI 路径（Windows 下通常是 `claude.cmd`）
`BOT_NAME`	机器人显示名称

.env.example 中有完整注释。

启动

确认 .env 填写完毕后，双击 启动中繼.bat（或命令行 py -3.13 -u relay.py --webui）。

正常启动日志：

[Auth] AccessToken 已刷新，有效期至 ...
[中繼] 初始化完成（persona: persona.md）
[中繼] 已加载 N 个插件: [...]
[WS] Hello, heartbeat_interval=30000ms
[中繼] 官方网关连接成功 session=xxx bot=xxx
[中繼] 开始监听...
[中繼] WebUI 启动于 http://127.0.0.1:8800
[图床] http://0.0.0.0:8801

获取 MASTER_OPENID：用主人账号在群里发一条消息（或 @机器人），看终端日志 [群 xxx] 用户XXXX(此处即 member_openid)，把括号里的字符串填到 .env 即可。

3. 核心功能

3.1 AI 对话（管道模式）

所有群统一走 Claude Code CLI 子进程，使用 --resume / --session-id 保持跨消息的持续上下文。子进程退出 = 回复结束，回复通过官方 REST API（POST /v2/groups/{group_openid}/messages）发送。

两种权限模式（互斥）

QQ 官方 Bot API 在群事件中，以下两种接收模式不可同时开启，需要根据使用场景二选一：

权限	可接收事件	效果
`GROUP_MESSAGE_CREATE`（获取全部群消息）	群内所有成员发的每条消息	✅ 能接收群友日常聊天、触发主动发言、响应骰子 `.r` ❌ 无法接收 @机器人的官方回调，无法直接回复 @
`GROUP_AT_MESSAGE_CREATE`（仅接收 @消息）	只有 @机器人的消息	✅ 能接收并回复 @机器人的消息 ❌ 无法接收群友日常聊天，无法触发骰子和主动发言

QQ 官方 API 限制：两种权限互斥。群主需要在 QQ 设置中自行选择机器人开启哪种权限模式。

详细行为

触发方式	行为
@机器人	收到 `GROUP_AT_MESSAGE_CREATE` 事件，带滑动窗口上下文 + prompt 调子进程，HTTP 被动回复（携带 msg_id，5 分钟内有效）
主动发言	需 `GROUP_MESSAGE_CREATE` 权限 + 群主开启"机器人主动发言"开关，每收到一条非 @ 消息计数器 +1，阈值 4~8 条随机触发
回复拆分	超过 30 字按句号拆分多段发送；被动回复上限 5 条
消息去重	基于 msg_id 去重，同一条消息不会重复触发
工具权限	默认只读：WebSearch, Read, Glob；主人 @ 时提升到 WebSearch, Read, Edit, Write, Bash, Grep, Glob

管道上下文

滑动窗口保留最近 30 条消息
每个群独立 session，--session-id 首次创建，后续 --resume 续接
resume 失败自动重建，不会丢群

3.2 骰子（全群通用）

⚠️ 依赖 GROUP_MESSAGE_CREATE 权限。群主需要在 QQ 机器人设置中开启"机器人仅响应 @机器人的消息"以外的另一种模式（即允许机器人获取全部群消息）。如果只开启了 @机器人模式，骰子功能不会触发。

任何人在群里发送 .r <表达式>（支持半角 . 和全角 。），机器人秒回骰子结果。

输入	效果	示例输出
`.r d20`	投 1 个 20 面骰	🎲 1D20 → 15
`.r 3d6`	投 3 个 6 面骰求和	🎲 3D6 → 2 + 5 + 3 = 10
`.r 100`	投 1 个 100 面骰	🎲 1D100 → 73
`.r d100`	同上	🎲 1D100 → 42

用途：跑团、随机决策、气氛活跃。骰子功能不经过 AI 管道，纯本地计算秒回。

3.3 主动发言

依赖 GROUP_MESSAGE_CREATE 权限。每收到一条非 @ 消息计数器 +1，阈值范围 4~8 条随机触发，触发后重置。

触发 prompt 要求自然接话，不要太正式。

权限说明：主动发言功能依赖 GROUP_MESSAGE_CREATE 权限，需在 q.qq.com 后台申请此权限；同时群主需在群内开启"机器人主动在群聊内发言"开关。未开通权限或未开启开关时，该功能静默不工作。

3.4 主人权限提升

主人（MASTER_OPENID）@ 机器人时，工具权限从 WebSearch, Read, Glob 提升到 WebSearch, Read, Edit, Write, Bash, Grep, Glob，其余人保持只读。

3.5 表情包系统（暂停）

官方 Bot API 暂不支持 OneBot CQ 码图片，表情包功能默认关闭（MEME_ENABLED=false）。图床服务器仍保留，供后续接入官方富媒体上传 API 时复用。

4. 插件系统

在 plugins.py 中注册异步处理函数，支持分群开关，配置持久化到 memory/plugins.json。

注册插件

import plugins

async def my_plugin(bot, gid, uid, nick, text, is_at, msg_id=None):
    """返回 True = 拦截本条消息（AI 不再回复），返回 None/False = 放行
    gid/uid 为 group_openid/member_openid 字符串；msg_id 用于被动回复（带它调 bot.send_group）。
    """
    if "你好" in text:
        await bot.send_group(gid, f"{nick} 你好！", msg_id=msg_id)
        return True
    return None

plugins.register("my_plugin", "回复'你好'", my_plugin, default_enabled=True)

钩子时机

消息进入后、AI 回复前调用。插件拦截 = 不计入主动发言计数。

WebUI 管理

插件管理页面可查看所有插件、全局开关、各群独立开关。无需重启即可生效。

5. WebUI 管理面板

默认地址：http://127.0.0.1:8800

页面	功能
仪表盘	连接状态、在线时长、实时消息流、快捷统计
群设置	调整主动发言阈值、查看对话历史
管道状态	各群的计数器、阈值、滑动窗口内容实时查看
知识库	创建/编辑/删除 Markdown 知识文件
插件管理	查看所有插件、全局开关、分群开关
发消息	手动向任意群发送消息
环境配置	在线编辑环境变量（需重启生效）

WebUI 通过 /ws WebSocket 接收实时事件。默认绑定 127.0.0.1，仅本机可访问。

6. 常见问题

claude 命令未找到 确认 Claude Code 已安装，Windows 下 CLAUDE_CMD 设为 claude.cmd 或完整路径。

机器人不响应 @

确认启动日志中 官方网关连接成功 是否出现
确认 QQ_APP_ID / QQ_CLIENT_SECRET 正确且 AccessToken 刷新成功
确认开启的是 GROUP_AT_MESSAGE_CREATE 权限（不是 GROUP_MESSAGE_CREATE）

收不到群友消息

确认开启了 GROUP_MESSAGE_CREATE 权限（不是 GROUP_AT_MESSAGE_CREATE）
群主是否在 q.qq.com 后台申请了权限

@ 没有上下文记忆

首次 @ 用 --session-id 创建会话，后续 --resume 续接
手动 claude 不要占用同样的 session ID
代码有回退逻辑：resume 失败自动 --session-id 重建

Windows 下换行符丢失 消息通过 stdin 传入（非命令行参数），已修复。

7. 关联项目

QQ-relay-Chatbot（插件系统 + WebUI + AGPL 版）：https://github.com/Soenchin/QQ-relay-Chatbot

QQ 群：940358918

Name		Name	Last commit message	Last commit date
docs		docs
memes		memes
static		static
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
plugins.py		plugins.py
relay.py		relay.py
requirements.txt		requirements.txt
webui.py		webui.py
启动中繼.bat		启动中繼.bat

Navigation Menu

Repository navigation

About

Repository files navigation

QQ-relay-BOT-official

目录

1. 项目概述

2. 快速开始

前置依赖

安装

配置

启动

3. 核心功能

3.1 AI 对话（管道模式）

两种权限模式（互斥）

详细行为

管道上下文

3.2 骰子（全群通用）

3.3 主动发言

3.4 主人权限提升

3.5 表情包系统（暂停）

4. 插件系统

注册插件

钩子时机

WebUI 管理

5. WebUI 管理面板

6. 常见问题

7. 关联项目

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

QQ-relay-BOT-official

目录

1. 项目概述

2. 快速开始

前置依赖

安装

配置

启动

3. 核心功能

3.1 AI 对话（管道模式）

两种权限模式（互斥）

详细行为

管道上下文

3.2 骰子（全群通用）

3.3 主动发言

3.4 主人权限提升

3.5 表情包系统（暂停）

4. 插件系统

注册插件

钩子时机

WebUI 管理

5. WebUI 管理面板

6. 常见问题

7. 关联项目

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages