本页内容
本页内容
区域平台
QQ 机器人
QQ Bot 通过官方 QQ Bot API(WebSocket 网关)连接到 OpenClaw。 C2C 私人聊天和群组 @- 提及是主要的聊天类型,具有丰富的媒体(图像、语音、视频、文件)。公会频道消息仅支持文本和远程-URL 图像;公会频道不支持语音、视频、文件上传和local/Base64图片。任何地方都不支持反应和线程。
状态:官方可下载插件。
安装
如果机器人在插件 ID qqbot、openclaw plugins update qqbot 和 openclaw update 下安装为 @openclaw/qqbot,则将其重写为插件 ID openclaw-qqbot 下的 @tencent-connect/openclaw-qqbot。通道配置保留在 channels.qqbot 下。
设置
- Go转QQ 打开Platform,用手机QQ扫描QR码进行注册/登录。
- 点击 创建机器人 创建一个新的 QQ bot。
- 在机器人设置页找到 AppID 和 AppSecret,并复制它们。
- 添加频道:
- 检查
openclaw channels status --probe;如果网关离线,则启动网关。配置更改遵循 hot reload。
入站持久性
对于 QQ 网关转发事件,OpenClaw 会在推进已保存的网关恢复序列之前先持久化原始事件。待处理或可重试的转发在 Gateway 重启后仍会保留,且会按会话序列化,并在活跃或保留的完成记录存在时使用提供方事件 ID 来抑制重复的队列条目。
如果持久准入失败,OpenClaw 终止当前网关套接字而不推进序列。然后,reconnect/resume 路径可以再次请求未提交的事件。跨队列到代理边界的传递仍然至少一次,因此切换期间的崩溃可能会重播一个回合。
交互式设置:
该向导还提供 QR- 代码绑定,作为手动键入 AppID/AppSecret 的替代方法:使用与目标 QQ 机器人绑定的手机应用程序扫描代码以完成绑定。 OpenClaw 将返回的凭据保留在帐户的配置范围下。
配置
最小配置:
这些示例使用 dmPolicy: "open" 保持直接消息打开,而 openclaw:approval-disabled 标记则禁用本机审批操作。要启用这些操作,请将标记替换为特定批准者 QQ OpenIDs。
默认账号环境变量(仅顶层账号):
QQBOT_APP_IDQQBOT_CLIENT_SECRET
使用 SecretRef 将 AppSecret 排除在通道配置之外。对于环境支持的秘密:
对于文件支持的 AppSecret,配置 singleValue 文件提供程序:
注意:
openclaw channels add --channel qqbot --token-file ...仅设置 AppSecret;appId必须已在配置或QQBOT_APP_ID中设置。随后运行openclaw doctor --fix以迁移旧文件设置。clientSecret接受明文或环境、文件、执行或存储支持的 SecretRef。 OpenClaw 在将凭证交给 QQ Bot 插件之前解析引用。clientSecretFile是仅迁移的旧设置。openclaw doctor --fix将其替换为文件支持的clientSecretSecretRef。新配置应直接使用clientSecret。- 顶级凭据和环境回退仅属于默认帐户。命名帐户配置自己的
appId和clientSecret。
流式输出
streaming.mode: "off"会为该账号禁用块流式传输。streaming.nativeTransport: true通过 QQ 的官方stream_messagesAPI 流式传输 C2C (DM) 回复; group/channel 目标不受影响。- 旧版的
streaming: true|false标量以及streaming.c2cStreamApi键可通过openclaw doctor --fix迁移为此结构。 /bot-streaming on|off会从 DM 中切换同样的配置。
访问策略
allowFrom/groupAllowFrom门可以在 C2C / 组上下文中与机器人聊天。dmPolicy/groupPolicy(open|allowlist|disabled)控制强制模式。一旦allowFrom具有具体(非通配符)条目,dmPolicy默认为allowlist,否则为open。一旦groupAllowFrom或allowFrom有具体条目,groupPolicy默认为allowlist,否则为open。contextVisibility控制 QQ 作为补充上下文提供的引用消息文本。默认值"all"会保留收到的引用文本。 设为"allowlist"时,仅在被引用发送者通过配置的发送者策略时才包含引用正文, 或设为"allowlist_quote"以保留显式引用,同时过滤其他补充上下文。参见 群聊。- “Auth:白名单”斜杠命令需要在
allowFrom(或用于组调用的groupAllowFrom)中显式非通配符条目,无论dmPolicy/groupPolicy— 请参阅 斜杠命令。
多账号设置
在单个 OpenClaw 实例下运行多个 QQ 机器人:
每个账号都拥有独立的 WebSocket 连接、API 客户端和 token 缓存,并按 appId 作为键区分。 日志行会标记所属账号 id,因此当你在同一个 Gateway 下运行多个 bot 时,诊断信息仍然可以分开查看。
启动时,缺少 SecretRef 值仅使其帐户不可用;健康的兄弟姐妹和网关仍然可用。显式失败的引用不会回退到环境或插件备份凭据。格式错误的引用和未知的秘密提供程序仍然无法启动或重新加载。重新加载时,未更改的帐户可以保留其最后已知的良好凭据;请参阅 Secrets 运行时模型。
通过 CLI 添加第二个 bot:
群聊
组支持使用 QQ 组 OpenIDs,不显示名称。将机器人添加到组中,然后提及它或将组配置为在不提及的情况下运行。
groups["*"] 为所有群设置默认值;具体的 groups.GROUP_OPENID 条目会覆盖某个群的这些默认值。群设置如下:
| 字段 | 默认值 | 描述 |
|---|---|---|
requireMention |
true |
在机器人回复之前需要提及 @-。 |
commandLevel |
all |
群内可运行哪些内置斜杠命令(见下文)。 |
ignoreOtherMentions |
false |
丢弃提及了别人但没有提及机器人的消息。 |
historyLimit |
50 |
为下一次被提及时保留的最近非提及消息上下文数量。0 可禁用历史记录。 |
tools |
— | Allow/deny 整个组的工具。 |
toolsBySender |
— | 每个发送者工具覆盖;请参阅 Groups。 |
name |
openid 前缀 | 日志和群上下文中使用的友好名称。 |
prompt |
内置默认值 | 附加到代理上下文中的群级行为提示词。 |
commandLevel 接受:
| 等级 | 行为 |
|---|---|
all |
现有内置命令保持可用。部分命令会在菜单中隐藏,但授权用户仍可在群里运行它们。 |
safety |
/help、/btw、/stop 在群里保持可见;敏感命令(/config、/tools、/bash 等)必须在私聊中运行。 |
strict |
仅允许严格运行所需的群会话控制命令。/stop 仍然可用,因此授权发送者可以中断当前运行。 |
旧版 QQBot 的 toolPolicy 条目已弃用。运行 openclaw doctor --fix 将其迁移到 tools。
激活模式为 mention 和 always。requireMention: true 映射到 mention;requireMention: false 映射到 always。当存在会话级激活覆盖时,其优先级高于配置。
入站队列按对端(peer)划分。群对端的队列上限更大(50,而私聊对端为 20),满时会优先驱逐机器人发送的消息而不是人类消息,并将普通群消息的短时间突发合并为一个带归属的轮次。斜杠命令逐个运行,不受任何合并批次影响。
语音(STT / TTS)
STT 和 TTS 支持两级配置,并按优先级回退:
| 设置 | 插件专用 | 框架回退 |
|---|---|---|
| STT | channels.qqbot.stt |
tools.media.models[] 中第一个支持音频的条目 |
| TTS | channels.qqbot.tts, channels.qqbot.accounts.<id>.tts |
tts |
将 enabled: false 设置为禁用。帐户级别 TTS 覆盖使用与 tts 相同的形状,并深度合并 channel/global TTS 配置。
STT 请求默认在 60 秒后超时。插件专用 STT 使用所选 models.providers.<id>.timeoutSeconds 覆盖值。框架音频 STT 使用所选支持音频的 tools.media.models[] 条目的 timeoutSeconds,然后再使用所选提供方覆盖值。
进入的 QQ 语音附件会作为音频媒体元数据暴露给代理, 同时不会将原始语音文件放入通用的 MediaPaths 中。[[audio_as_voice]] 出现在纯文本回复中时,会合成 TTS,并在配置了 TTS 时发送原生 QQ 语音消息。
出站音频 upload/transcode 行为也可以使用 channels.qqbot.audioFormatPolicy 进行调整:
sttDirectFormatsuploadDirectFormatstranscodeEnabled
目标格式
| 格式 | 描述 |
|---|---|
qqbot:c2c:OPENID |
私聊(C2C) |
qqbot:group:GROUP_OPENID |
群聊 |
qqbot:channel:CHANNEL_ID |
频道 |
斜杠命令
在 AI 队列之前拦截的内置命令:
| 命令 | 认证 | 范围 | 描述 |
|---|---|---|---|
/bot-ping |
— | 任意 | 延迟测试 |
/bot-help |
— | 任意 | 列出所有命令 |
/bot-me |
— | 仅限私聊 | 显示发送者的 QQ 用户 ID(openid),用于 allowFrom / groupAllowFrom 配置 |
/bot-version |
— | 仅限私聊 | 显示 OpenClaw 框架版本和插件版本 |
/bot-upgrade |
— | 仅限私聊 | 显示 QQBot 升级指南链接 |
/bot-approve |
允许名单 | 仅限私聊 | 管理命令执行审批配置(on / off / always / reset / status) |
/bot-logs |
允许名单 | 仅限私聊 | 将最近的网关日志导出为文件 |
/bot-clear-storage |
允许名单 | 仅限私聊 | 删除 QQBot 媒体目录下的缓存下载 |
/bot-streaming |
允许名单 | 仅限私聊 | 切换 C2C 流式回复 |
/bot-group-allways |
允许名单 | 仅限私聊 | 切换默认群激活模式(需要提及 vs. 始终开启) |
在任何命令后追加 ? 可查看用法帮助(例如 /bot-upgrade ?)。
“Auth: allowlist”命令还要求发送者的 openid 必须出现在一个明确的非通配符 allowFrom 列表中(群消息命令优先使用 groupAllowFrom, 否则回退到 allowFrom)。allowFrom: ["*"] 这种通配符允许聊天,但不允许这些命令。在私聊之外运行这些命令,或未获授权时, 会返回提示信息,而不是静默丢弃消息。
/bot-me、/bot-version 和 /bot-upgrade 仅限私聊,但不需要 allowlist——任何 C2C 发送者都可以运行它们。
当 QQ Bot 执行审批使用默认的同聊回退时,原生审批按钮点击遵循相同的明确非通配符命令 allowlist。若要在不授予更广泛命令权限的情况下仅授予审批访问权限,请配置 channels.qqbot.execApprovals.approvers。原生执行审批默认已启用。
媒体与存储
- 入站、出站和网关桥接媒体共享一个载荷根目录,位于
~/.openclaw/media/qqbot(在设置了OPENCLAW_HOME时会遵循该配置),因此上传、下载和转码缓存都保留在一个受保护的目录下。 - 面向 C2C 和群目标的富媒体发送都通过同一个
sendMedia路径。大小为 5 MiB 或以上的本地文件和内存缓冲区使用 QQ 的分块上传端点;较小的载荷以及远程 URL/Base64 来源则使用一次性上传 API。 - 如果热升级在完成写入
openclaw.json之前中断了网关,则该插件会在下次启动时从内部快照恢复该帐户的最后已知的appId/clientSecret(永远不会覆盖有意的配置更改),因此不需要重新扫描 QR 代码。
故障排查
- 网关未启动/没有入站消息: 验证
appId和clientSecret是否正确,并且机器人已在 QQ 开放平台上启用。 缺少凭据时会显示为“QQBot 未配置(缺少 appId 或 clientSecret)”。 - 使用
--token-file设置后仍显示未配置:--token-file仅设置 AppSecret。appId仍必须在配置或QQBOT_APP_ID中设置。 - 突发的群组回复发生冲突: 当对端队列满时,入站队列会优先驱逐机器人发送的消息而不是人类消息,并将突发的普通(非命令)群消息合并为一次带归属的轮次,因此大量机器人聊天不应饿死人类消息。
- 主动消息未送达: 如果用户最近没有互动,QQ 可能会阻止机器人发起的消息。
- 语音未转录: 检查 STT 是否已配置并且提供程序是否可访问。