OpenClaw QQ 机器人渠道
即时通讯
中等
通过社区插件 @openclaw-china/qqbot 将 OpenClaw 连接到 QQ（非 OpenClaw 官方内置渠道）。QQ 插件由社区开发和维护，与 OpenClaw 核心分离安装，功能和兼容性由插件作者负责。此集成支持私聊、群聊（@触发）、频道消息和频道私信四种消息场景，并提供图片、音频、视频、文件等富媒体消息能力。支持 Markdown 投递模式（被动/主动）、分块策略、语音转文字（需配置腾讯云 ASR）。安装插件、在 QQ 开放平台创建机器人应用、通过 openclaw china setup 交互式配置即可启动。
快速信息
难度中等
分类即时通讯
支持功能数4 / 6
QQ 支持的功能
文本消息
支持
媒体与文件
支持
消息反应
不支持
消息线程
不支持
语音消息
支持
群聊
支持
QQ 前置条件
- 拥有 QQ 开放平台开发者账号（q.qq.com）
- 已安装 QQ 插件：openclaw plugins install @openclaw-china/qqbot
- OpenClaw Gateway 已运行并配置
- 服务器已安装 Node.js 18+
QQ 快速设置
1
安装 QQ 机器人插件
在终端中运行 'openclaw plugins install @openclaw-china/qqbot' 安装社区插件。该插件来自 BytePioneer-AI/openclaw-china 项目（GitHub 3.2k stars），社区活跃度高。也可以安装国产 IM 整合包 'openclaw plugins install @openclaw-china/channels'（含 QQ、飞书、钉钉等）。
2
在 QQ 开放平台创建机器人应用
登录 QQ 开放平台（q.qq.com），进入机器人管理后台，点击「创建机器人」。填写机器人名称、描述和头像。创建完成后在应用详情页获取 AppID 和 ClientSecret。
3
配置 OpenClaw
推荐使用交互式向导：运行 'openclaw china setup'，按提示输入 AppID 和 ClientSecret 即可完成配置。也可以快速配置：'openclaw channels add --channel qqbot --token "AppID:ClientSecret"'。或手动编辑 ~/.openclaw/openclaw.json，在 channels.qqbot 下填入 appId 和 clientSecret。
4
测试连接
运行 'openclaw gateway restart' 重启 Gateway。在 QQ 中找到机器人发送消息测试，群聊中需要 @机器人触发。运行 'openclaw logs --follow' 查看实时日志确认消息收发正常。
QQ 配置示例
config.json
{
"channels": {
"qqbot": {
"enabled": true,
"appId": "your-app-id",
"clientSecret": "your-client-secret",
"markdownSupport": true,
"c2cMarkdownDeliveryMode": "proactive-all",
"c2cMarkdownChunkStrategy": "markdown-block",
"autoSendLocalPathMedia": false
}
}
}QQ 集成详解
OpenClaw QQ 架构概述
OpenClaw 通过 QQ 开放平台的 WebSocket 连接接收和发送消息。插件启动后主动与 QQ 服务器建立长连接，实时接收事件推送。
消息流程：用户在 QQ 中发送消息 → QQ 开放平台 → WebSocket 推送至 Gateway → OpenClaw 使用 AI 处理 → 通过 QQ Bot API 回复 → 消息在 QQ 中送达。
QQ 机器人支持四种消息场景：
• **私聊（C2C）** — 用户直接与机器人对话
• **群聊（Group）** — 群内 @机器人触发回复
• **频道消息（Channel）** — QQ 频道中的公开消息
• **频道私信（Channel DM）** — QQ 频道内的私密对话
插件数据存储路径：
• 引用索引：~/.openclaw/qqbot/data/ref-index.jsonl
• 已知目标：~/.openclaw/qqbot/data/known-targets.json
WebSocket 长连接由 Gateway 主动发起，无需公网 IP 或 SSL 证书。
QQ 渠道为社区插件提供，非 OpenClaw 官方内置渠道。插件与 OpenClaw 核心分离安装和维护，OpenClaw 版本升级后可能需要等待插件适配更新。
OpenClaw QQ 插件选择
QQ 机器人接入有两个插件可选：
• **@openclaw-china/qqbot（推荐）** — openclaw-china 社区维护（BytePioneer-AI/openclaw-china），GitHub 3.2k stars，社区活跃度高。一个项目同时支持飞书、钉钉、QQ、企业微信、个人微信等多个平台。配置键名为 qqbot，支持 Markdown 投递模式、分块策略、腾讯云 ASR 语音转文字等高级功能。
• **@sliverp/qqbot（备选）** — 腾讯官方 GitHub 组织（tencent-connect）下的社区插件，GitHub 186 stars。专注 QQ 单平台，配置方式与 @openclaw-china/qqbot 不同。
本页面以 @openclaw-china/qqbot 为主要参考。如果需要同时接入多个国内 IM 平台，可选择安装整合包 @openclaw-china/channels。
terminal
# 安装 openclaw-china 的 QQ 插件（推荐）
openclaw plugins install @openclaw-china/qqbot
# 或安装 openclaw-china 国产 IM 整合包（含 QQ、飞书、钉钉等）
openclaw plugins install @openclaw-china/channels
# 备选：安装 QQ 专用插件
openclaw plugins install @sliverp/qqbotOpenClaw QQ 开放平台应用创建与凭证获取
设置 QQ 机器人集成需要在 QQ 开放平台创建应用：
1. 访问 QQ 开放平台（q.qq.com），使用 QQ 号登录并完成开发者身份实名认证（审核通常需要 1-2 个工作日）。
2. 进入「机器人」管理页面，点击「创建机器人」。
3. 填写机器人基本信息：名称、头像、简介。名称需审核通过后才能使用。
4. 创建完成后，在「开发设置」页面获取 **AppID** 和 **ClientSecret**。
5. 配置使用场景：在「功能配置」中勾选需要的消息场景（私聊、群聊、频道等）。
6. 配置消息 URL：如使用 WebSocket 模式，无需填写回调地址；如使用 Webhook 模式，填写服务器公网地址。
7. 提交审核，QQ 平台会在 1-3 个工作日内完成审核。审核期间可使用沙箱模式测试。
terminal
# 推荐：使用交互式向导配置
openclaw china setup
# 或快速配置
openclaw channels add --channel qqbot --token "AppID:ClientSecret"
# 或手动设置单个配置项
openclaw config set channels.qqbot.appId "your-app-id"
openclaw config set channels.qqbot.clientSecret "your-client-secret"请妥善保管 ClientSecret。切勿将其提交到版本控制系统。生产环境请使用环境变量。如果泄露，请立即在 QQ 开放平台控制台重新生成。
OpenClaw QQ Markdown 投递模式与分块策略
@openclaw-china/qqbot 支持三种 Markdown 投递模式（c2cMarkdownDeliveryMode）：
**passive（被动模式）**：
• 仅在回复用户消息时使用 Markdown 格式
• 最稳定，不受主动消息限制
• 适合大多数场景
**proactive-table-only（主动-仅表格）**：
• 被动消息使用 Markdown，主动消息仅在包含表格时使用 Markdown
• 平衡模式，减少主动消息配额消耗
**proactive-all（主动-全部）**：
• 所有消息均使用 Markdown 格式
• 显示效果最好，但会消耗主动消息配额
**分块策略（c2cMarkdownChunkStrategy）**：
当消息超过 QQ 平台长度限制时，插件会自动将消息分块发送：
• **markdown-block（默认）** — 按 Markdown 结构（段落、代码块、列表等）智能分块，保持格式完整性
• **length** — 按固定长度切割，简单粗暴但可能破坏 Markdown 格式
openclaw.json
{
"channels": {
"qqbot": {
"markdownSupport": true,
"c2cMarkdownDeliveryMode": "proactive-all",
"c2cMarkdownChunkStrategy": "markdown-block"
}
}
}推荐使用 markdown-block 分块策略，它能保持代码块、表格等 Markdown 结构的完整性。
如果不确定选哪种投递模式，建议从 passive 开始，避免浪费主动消息配额。
OpenClaw QQ 富媒体消息与语音转文字
OpenClaw QQ 插件支持丰富的消息类型：
**接收支持**：
• 文本消息
• 图片（自动识别并传给 AI 分析）
• 语音（需配置腾讯云 ASR 才能转文字）
• 视频
• 文件（.docx、.pdf、.txt、.xlsx 等）
**发送支持**：
• 文本和 Markdown 格式
• 图片（AI 生成的图表、截图等）
• 音频和视频
• 文件附件
**语音转文字（需额外配置）**：
语音转文字功能需要配置腾讯云 ASR（自动语音识别）服务。在腾讯云控制台开通语音识别服务，获取 AppId、SecretId 和 SecretKey，然后在配置中启用 asr。未配置 ASR 时，语音消息将无法被转为文字处理。
**autoSendLocalPathMedia**：
• 设为 true 时，AI 回复中的本地文件路径会自动作为媒体发送
• 默认 false，避免意外发送服务器上的文件
openclaw.json
{
"channels": {
"qqbot": {
"asr": {
"enabled": true,
"appId": "tencent-cloud-app-id",
"secretId": "tencent-cloud-secret-id",
"secretKey": "tencent-cloud-secret-key"
}
}
}
}语音转文字需要额外配置腾讯云 ASR 服务，不是开箱即用的。
发送富媒体消息需要在 QQ 开放平台授予相应的媒体上传权限。
Markdown 格式回复在 QQ 客户端中渲染效果良好，推荐开启 markdownSupport。
OpenClaw QQ 沙箱模式与正式环境
QQ 开放平台提供沙箱模式用于开发测试：
**沙箱模式**：
• 仅限开发者和测试成员使用
• 消息不受频率限制
• 无需通过审核即可使用
• 适合开发调试阶段
• 注意：自 2026 年 1 月起，沙箱模式不再支持 QQ 群聊测试，仅支持频道和私聊场景
**正式环境**：
• 所有 QQ 用户可使用
• 需要通过 QQ 平台审核
• 主动消息有严格的频率限制（见下方）
• 被动消息有回复时间窗口限制
**主动消息限制（正式环境）**：
• 私聊：每用户每月仅 4 条主动消息
• 群聊：每群每月仅 4 条
• 频道：每子频道每天 20 条，每天限 2 个子频道
• 频道私信：每用户每天 2 条，每天总计 200 条
**被动消息回复窗口**：
• 私聊（C2C）：收到用户消息后 60 分钟内可回复，最多 5 条
• 群聊：收到 @消息后 5 分钟内可回复，最多 5 条
• 频道/频道私信：收到消息后 5 分钟内可回复
建议开发阶段使用沙箱模式，功能验证完毕后切换到正式环境。
正式环境中，主动消息有严格的频率限制（私聊和群聊每月仅 4 条）。建议以被动回复为主，注意在回复窗口内及时响应。使用 passive 投递模式可避免消耗主动消息配额。
OpenClaw QQ 常用命令
OpenClaw 提供多个命令来管理 QQ 机器人：
• openclaw china setup — 交互式配置向导（推荐）
• openclaw channels add --channel qqbot --token "AppID:ClientSecret" — 快速添加渠道
• openclaw config set channels.qqbot.* — 设置单个配置项
• openclaw config show — 查看当前配置
• openclaw gateway status — 检查 Gateway 连接状态
• openclaw gateway restart — 重启 Gateway 服务
• openclaw logs --follow — 查看实时日志
• openclaw plugins list — 查看已安装插件
• openclaw plugins update @openclaw-china/qqbot — 更新 QQ 插件
• openclaw doctor — 综合诊断
QQ 配置参考
| Key | Type | Default | Description |
|---|---|---|---|
| enabled | boolean | true | 启用或禁用 QQ 渠道 |
| appId | string | "" | QQ 机器人的 AppID，从 QQ 开放平台获取 |
| clientSecret | string | "" | QQ 机器人的 ClientSecret，从 QQ 开放平台获取（注意不是 appSecret） |
| markdownSupport | boolean | true | 启用 Markdown 格式消息支持 |
| c2cMarkdownDeliveryMode | string | "proactive-all" | Markdown 投递模式。选项：passive（被动）、proactive-table-only（主动-仅表格）、proactive-all（主动-全部） |
| c2cMarkdownChunkStrategy | string | "markdown-block" | 消息分块策略。选项：markdown-block（按 Markdown 结构分块，推荐）、length（按固定长度切割） |
| autoSendLocalPathMedia | boolean | false | 是否自动将 AI 回复中的本地文件路径作为媒体发送 |
| asr.enabled | boolean | false | 启用语音转文字功能（需腾讯云 ASR 服务） |
| asr.appId | string | "" | 腾讯云 ASR 的 AppId |
| asr.secretId | string | "" | 腾讯云 ASR 的 SecretId |
| asr.secretKey | string | "" | 腾讯云 ASR 的 SecretKey |
enabled
Type: booleanDefault: true
启用或禁用 QQ 渠道
appId
Type: stringDefault: ""
QQ 机器人的 AppID，从 QQ 开放平台获取
clientSecret
Type: stringDefault: ""
QQ 机器人的 ClientSecret，从 QQ 开放平台获取（注意不是 appSecret）
markdownSupport
Type: booleanDefault: true
启用 Markdown 格式消息支持
c2cMarkdownDeliveryMode
Type: stringDefault: "proactive-all"
Markdown 投递模式。选项：passive（被动）、proactive-table-only（主动-仅表格）、proactive-all（主动-全部）
c2cMarkdownChunkStrategy
Type: stringDefault: "markdown-block"
消息分块策略。选项：markdown-block（按 Markdown 结构分块，推荐）、length（按固定长度切割）
autoSendLocalPathMedia
Type: booleanDefault: false
是否自动将 AI 回复中的本地文件路径作为媒体发送
asr.enabled
Type: booleanDefault: false
启用语音转文字功能（需腾讯云 ASR 服务）
asr.appId
Type: stringDefault: ""
腾讯云 ASR 的 AppId
asr.secretId
Type: stringDefault: ""
腾讯云 ASR 的 SecretId
asr.secretKey
Type: stringDefault: ""
腾讯云 ASR 的 SecretKey
QQ 常见问题
QQ 故障排查
机器人完全不回复
应用可能未通过审核、AppID 或 ClientSecret 错误、插件未正确安装、或配置键名错误。
逐步排查：1) 确认应用已通过审核或已开启沙箱模式；2) 核对 AppID 和 ClientSecret（注意是 clientSecret 不是 appSecret）；3) 运行 openclaw plugins list 确认 @openclaw-china/qqbot 已安装；4) 确认配置键名为 channels.qqbot（不是 channels.qq）；5) 运行 openclaw gateway status 检查连接状态。
WebSocket 连接失败或频繁断开
网络不稳定、防火墙拦截出站 WebSocket 连接、或 AppID/ClientSecret 无效导致鉴权失败。
检查网络连接是否稳定，确保防火墙允许出站 WebSocket 连接。核对凭证是否正确（clientSecret 而非 appSecret）。Gateway 会自动处理断线重连，查看 openclaw logs --follow 获取详细错误信息。
发送消息报权限错误
QQ 开放平台未授予相应权限，或消息场景未在平台侧启用。
登录 QQ 开放平台，检查机器人的权限配置。确保已勾选消息发送、媒体上传等必要权限。权限修改后可能需要重新提交审核。群聊场景需要确认机器人已被管理员添加到群中。
富媒体消息（图片/文件）发送失败
媒体上传权限未授予，文件超过大小限制，或 autoSendLocalPathMedia 未开启。
确认已在 QQ 开放平台授予媒体上传权限。如需自动发送本地文件，将 autoSendLocalPathMedia 设为 true。检查文件大小是否超过限制。查看日志获取详细错误信息。
语音消息无法转文字
未配置腾讯云 ASR 服务，或 ASR 凭证错误。
语音转文字需要配置腾讯云 ASR。在腾讯云控制台开通语音识别服务，获取 appId、secretId 和 secretKey，在配置中设置 channels.qqbot.asr.enabled 为 true 并填入凭证。运行 'openclaw config set channels.qqbot.asr.enabled true' 启用。
沙箱模式正常但正式环境不工作
应用审核未通过，或正式环境的频率限制触发了消息过滤。
确认应用审核已通过。检查是否触发了频率限制（正式环境有消息频率上限）。将 c2cMarkdownDeliveryMode 设为 passive 可避免消耗主动消息配额。查看 QQ 开放平台的运营数据面板了解消息投递情况。