dsh-qq-onebot-bridge

配置

profile 的 cordis.patch.yml 覆盖 id: dsh-qq-onebot-bridge 的 config（完整示例见 examples/cordis.patch.example.yml）：

键	默认	说明
host	127.0.0.1	反向 WS 监听地址
port	6700	反向 WS 监听端口
accessToken	''	OneBot 端须携带的 Bearer token（空=不校验）
allowUsers	[]	用户白名单（空=所有人）
allowGroups	[]	群白名单（空=所有群）
botQq	0	机器人 QQ 号（用于群内 @ 检测；0=任何群消息视为@）
replyOnlyWhenMentioned	true	群聊仅 @机器人 才回复
acceptPrivate	true	是否回复私聊
autoCollectStickers	false	自动收藏消息里的图片表情到本地图库
faceEnabled	true	表情功能总开关（[face:] 标记 + qq_face_* 工具）
sessionMode	chat	群会话分组：chat=每群一会话；user=每群每人一会话
cwd	''	会话工作目录（同时决定 qq-faces/、qq-replies/、qq-bridge-debug.log 的位置）
provider	''	LLM provider 覆盖（空=agent 默认）
model	''	LLM 模型覆盖（空=agent 默认）
maxMessageLength	1700	单条出站消息最大字符数（超出自动分段）
sttEnabled	false	语音转文字总开关
sttBaseUrl	https://open.bigmodel.cn/api/paas/v4	STT 端点（OpenAI 兼容 /audio/transcriptions）
sttModel	glm-asr-2512	STT 模型（智谱 glm-asr-2512 / SiliconFlow FunAudioLLM/SenseVoiceSmall）
sttApiKey	''	STT API Key（可复用智谱 GLM 系列的 key）
privateImageView	true	私聊中主动下载查看对方发送的图片/动画表情（存 cwd/qq-images/，agent 用 describe_image 查看）

用户侧（OneBot 实现）配置

以 NapCat 为例：OneBot11 配置里把 WebSocket 客户端地址填成：

ws://127.0.0.1:6700/

其它实现同理（LLOneBot 填反向 WebSocket、OpenShamrock 填被动 WebSocket、go-cqhttp 填 ws-reverse）。若本插件配了 accessToken，OneBot 端填同一 token。

⚠️ 风险与合规说明（使用前必读）

账号风控风险

• 本插件通过第三方协议实现（NapCat 等）接入 QQ，不是腾讯官方接口，与《QQ 软件许可及服务协议》相悖，QQ 官方明确禁止非官方客户端/协议
• 使用第三方协议存在账号被限制登录、冻结、甚至永久封禁的风险，且可能波及其他正常使用的 QQ 账号（同设备/同 IP）
• 建议使用机器人小号运行，绝不要用大号/常用号
• 常见风控诱因：高频发言、短时间大量消息、发送营销/广告/违规内容、被多人举报、异常登录设备
• 缓解建议：降低回复频率、仅在小群/自用场景运行、不 24 小时刷屏、严格内容合规

内容风控

• agent 生成的一切内容都会以机器人账号身份发出，使用者对该账号发布的内容负全部责任
• 建议在人设/系统提示中约束输出合规内容；违规内容既触发账号处罚，也可能带来法律责任

安全风险

• allowUsers / allowGroups 留空时，任何能给机器人发消息的人都能间接驱动你的 agent（含执行命令能力）——务必配置白名单或 accessToken
• 插件只监听 127.0.0.1，不要改成 0.0.0.0 暴露公网
• 语音与图片会上传到第三方云服务（STT API）处理，敏感语音请勿发送

合规提示

• 仅用于个人学习、内部小范围交流；不得用于批量营销、广告、骚扰、群控等用途
• 遵守所在地区法律法规与腾讯平台规则
• 使用第三方协议风险自负，本插件不提供任何免封号承诺

免责声明

本插件仅供技术学习与个人研究使用。使用者应自行评估并承担使用第三方 QQ 协议的全部风险与后果。