OpenClaw 内置 QQBot:架构解析与接入指南

OpenClaw 20260331最新版本在渠道生态上迎来重要扩展——QQBot插件现已内置打包（充值过后待遇肯定不一样，SVIP必须楼上请），无需额外安装步骤即可接入腾讯 QQ 生态，覆盖私聊、群聊和频道三大场景。这是继企业微信、微信之后，OpenClaw 在腾讯系产品上的又一关键落点。

什么是 QQBot？

QQ Bot 是腾讯官方推出的机器人开放能力，基于 QQ 开放平台（q.qq.com）提供 WebSocket 长连接网关，允许第三方应用以"机器人账号"的身份接入 QQ 的私聊、群聊和频道体系。

OpenClaw 将 QQBot 作为一个 Channel Plugin（渠道插件） 实现，意味着只要你运行 OpenClaw Gateway，QQBot 就能开箱即用地连接到你配置的 AI Agent。

整体架构

下图展示了 QQBot 在 OpenClaw Gateway 中的完整消息流转路径：

OpenClaw QQ Bot 消息流转架构

整个链路的核心有三层：

1.    接入层：QQBot WebSocket 长连接负责接收来自 QQ 生态的事件（消息、@提及、语音等），同时将 AI 回复推送回对应会话。
2.    路由层：Gateway 内置的 Channel Router 根据来源类型（C2C / 群聊 / 频道）建立独立的 Session 上下文，确保多用户、多群并发时互不干扰。
3.    推理层：Session 中的 AI Agent 持有完整的对话历史，向后端大语言模型（工蜂AI / Claude / Gemini 等）发起推理请求，并支持工具调用（Tool Use）。

技术实现细节

1. WebSocket 鉴权机制

QQ Bot 采用 AppID + AppSecret 双因子鉴权。OpenClaw 在启动时自动向 QQ 开放平台换取 Access Token，并在 Token 过期前自动刷新，整个生命周期对用户透明。

AppSecret 支持三种存储方式，安全等级递增：

1.    明文写入配置文件（开发测试用）
2.    通过文件路径引用（clientSecretFile），适合生产环境
3.    SecretRef 引用（接入 Gateway 的 Secrets Manager），适合多机部署

2. 三类 Target 格式与会话隔离

QQ Bot 的消息目标以结构化字符串标识，OpenClaw 据此构建独立 Session：

•    qqbot:c2c:OPENID — 用户私聊，每个用户独立上下文
•    qqbot:group:GROUP_OPENID — 群聊，需要 @ 机器人触发
•    qqbot:channel:CHANNEL_ID — QQ 频道，支持子频道粒度

值得注意的是，每个 Bot 账号有自己独立的 OpenID 命名空间，不同 Bot 收到的 OpenID 不通用，OpenClaw 在多账号模式下自动处理这一隔离。

3. 多账号并发支持

一个 Gateway 实例可以同时挂载多个 QQ Bot 账号，每个账号维护独立的 WebSocket 连接和 Token 缓存，互不影响。配置方式极简：

channels:
  qqbot:
    appId: "111111111"
    clientSecret: "bot-1-secret"
    accounts:
      bot2:
        appId: "222222222"
        clientSecret: "bot-2-secret"

4. 语音能力（STT / TTS）

QQBot 插件内置语音处理管线，支持两级配置回落：

•    STT（语音转文字）：优先读取 channels.qqbot.stt，回落到全局 tools.media.audio.models
•    TTS（文字转语音）：优先读取 channels.qqbot.tts，回落到全局 messages.tts

音频格式转码策略通过 audioFormatPolicy 精细控制，可指定哪些格式直传、哪些需要转码，以平衡质量和延迟。

5 分钟快速接入

1.    前往 QQ 开放平台（q.qq.com），扫码注册并创建机器人，记录 AppID 和 AppSecret。
2.    运行命令添加频道：openclaw channels add --channel qqbot --token "AppID:AppSecret"
3.    重启 Gateway：openclaw gateway restart
4.    在 QQ 中找到你的机器人，发送任意消息，AI 自动回复。

全程不需要修改任何代码，OpenClaw 的插件架构将接入层与 AI 层完全解耦。

内置指令

QQ Bot 插件预置了一批 Slash 指令，在消息路由到 AI 之前拦截处理，可用于快速诊断：

•    /bot-ping：延迟测试
•    /bot-version：查看当前 OpenClaw 版本
•    /bot-help：列出所有可用指令
•    /bot-logs：导出 Gateway 最近日志

小结

QQBot 内置到 OpenClaw 的意义不只是"多了一个渠道"，而是标志着 OpenClaw 的 多渠道 Gateway 设计 正在系统性地覆盖国内主流 IM 生态。同一套 AI Agent、同一份配置、同一个 Gateway 进程，可以同时服务于 WhatsApp、Telegram、企业微信、QQ，以及数十个其他平台。

对于需要在 QQ 生态内落地 AI 助手的团队，这是目前门槛最低、扩展性最强的方案之一。

本文基于 OpenClaw 官方文档整理 · docs.openclaw.ai