Appearance
QQ Bot 渠道通过官方 QQ Bot API 将 OpenClaw 接入 QQ，支持私聊、群聊和频道消息。配置需在 QQ 开放平台创建机器人并获取 AppID/AppSecret，然后执行 openclaw channels add --channel qqbot --token "AppID:AppSecret" 并重启 Gateway。群聊支持 @ 提及或始终回复，可设置每个群独立的行为规则。如果遇到“去火星了”或无入站消息，先检查凭证是否配置正确、Gateway 是否启动；主动消息不送达通常是 QQ 平台对近期无互动的用户拦截导致。
OpenClaw QQ Bot 配置与故障排查：AppID/AppSecret 获取及群聊语音设置
QQ Bot 通过官方 QQ Bot API（WebSocket 网关）连接 OpenClaw。本插件支持 C2C 私聊、群组 @ 消息和频道消息，并可发送图片、语音、视频、文件等富媒体。
状态：可下载插件。支持私聊、群聊、频道和富媒体；不支持消息回应和线程。
安装
QQ Bot 需要手动安装后再配置：
bash
openclaw plugins install @openclaw/qqbot设置
- 前往 QQ 开放平台 并用手机 QQ 扫码注册或登录。
- 点击 创建机器人 创建新的 QQ Bot。
- 在 Bot 设置页找到 AppID 和 AppSecret 并复制。
AppSecret 不会以明文保存——如果离开页面未保存，必须重新生成。
- 添加渠道：
bash
openclaw channels add --channel qqbot --token "AppID:AppSecret"- 重启 Gateway。
交互式设置路径：
bash
openclaw channels add
openclaw configure --section channels配置
最简配置：
json5
{
channels: {
qqbot: {
enabled: true,
appId: "YOUR_APP_ID",
clientSecret: "YOUR_APP_SECRET",
},
},
}默认账号环境变量：
QQBOT_APP_IDQQBOT_CLIENT_SECRET
文件形式的 AppSecret：
json5
{
channels: {
qqbot: {
enabled: true,
appId: "YOUR_APP_ID",
clientSecretFile: "/path/to/qqbot-secret.txt",
},
},
}环境变量 SecretRef 形式的 AppSecret：
json5
{
channels: {
qqbot: {
enabled: true,
appId: "YOUR_APP_ID",
clientSecret: { source: "env", provider: "default", id: "QQBOT_CLIENT_SECRET" },
},
},
}注意：
- 环境变量回退仅适用于默认 QQ Bot 账号。
openclaw channels add --channel qqbot --token-file ...只提供 AppSecret；AppID 必须已在配置或QQBOT_APP_ID中设置。clientSecret也接受 SecretRef 格式（结构化对象），不限于明文字符串。- 旧的
secretref:/...标记字符串不是有效的clientSecret值；请使用上述示例中的结构化 SecretRef 对象。
多账号配置
在单个 OpenClaw 实例下运行多个 QQ Bot：
json5
{
channels: {
qqbot: {
enabled: true,
appId: "111111111",
clientSecret: "secret-of-bot-1",
accounts: {
bot2: {
enabled: true,
appId: "222222222",
clientSecret: "secret-of-bot-2",
},
},
},
},
}每个账号拥有独立的 WebSocket 连接和 Token 缓存（按 appId 隔离）。
通过 CLI 添加第二个 Bot：
bash
openclaw channels add --channel qqbot --account bot2 --token "222222222:secret-of-bot-2"群聊配置
QQ Bot 群聊使用群 OpenID，不显示名字。将 Bot 加入群后，可以设置 @ 提及后回复，或配置为始终回复。
json5
{
channels: {
qqbot: {
groupPolicy: "allowlist",
groupAllowFrom: ["member_openid"],
groups: {
"*": {
requireMention: true,
historyLimit: 50,
toolPolicy: "restricted",
},
GROUP_OPENID: {
name: "Release room",
requireMention: false,
ignoreOtherMentions: true,
historyLimit: 20,
prompt: "Keep replies short and operational.",
},
},
},
},
}groups["*"] 设置所有群的默认值，具体的 groups.GROUP_OPENID 覆盖该群的部分设置。群设置项包括：
requireMention：需要 @ 提及 Bot 才回复。默认true。ignoreOtherMentions：如果消息提及了别人但没有提及 Bot，则丢弃该消息。historyLimit：保留未提及的群消息作为下次提及时的上下文数量。设为0禁用。toolPolicy：full、restricted或none，控制群内工具的使用范围。name：友好标签，用于日志和群上下文。prompt：每个群的自定义行为提示，附加到智能体上下文中。
激活模式分为 mention（提及）和 always（始终）。requireMention: true 对应 mention，false 对应 always。如果会话级别有激活模式覆盖，则优先于配置。
入站队列按 peer 隔离。群聊 peer 拥有更大的队列容量，满时优先保留人类消息而非 Bot 自身消息，并将普通群消息的突发合并为一次带归属的轮次。斜杠命令仍依次执行。
语音（STT / TTS）
STT 和 TTS 支持两层配置，优先级递减：
| 设置 | 插件专用 | 框架回退 |
|---|---|---|
| STT | channels.qqbot.stt | tools.media.audio.models[0] |
| TTS | channels.qqbot.tts，channels.qqbot.accounts.<id>.tts | messages.tts |
json5
{
channels: {
qqbot: {
stt: {
provider: "your-provider",
model: "your-stt-model",
},
tts: {
provider: "your-provider",
model: "your-tts-model",
voice: "your-voice",
},
accounts: {
"qq-main": {
tts: {
providers: {
openai: { voice: "shimmer" },
},
},
},
},
},
},
}设置 enabled: false 可禁用其中某一项。账号级别的 TTS 覆盖使用与 messages.tts 相同的格式，并与通道/全局 TTS 配置深度合并。
入站 QQ 语音附件会以音频媒体元数据的形式暴露给智能体，同时将原始语音文件排除在通用 MediaPaths 之外。当 TTS 配置后，[[audio_as_voice]] 纯文本回复会合成 TTS 并发送为原生 QQ 语音消息。
出站音频的上传/转码行为可通过 channels.qqbot.audioFormatPolicy 调整：
sttDirectFormatsuploadDirectFormatstranscodeEnabled
目标格式
| 格式 | 说明 |
|---|---|
qqbot:c2c:OPENID | 私聊（C2C） |
qqbot:group:GROUP_OPENID | 群聊 |
qqbot:channel:CHANNEL_ID | 频道 |
每个 Bot 有自己的用户 OpenID 集。Bot A 收到的 OpenID 不能用于 Bot B 发送消息。
斜杠命令
以下命令在进入 AI 队列前被直接拦截处理：
| 命令 | 说明 |
|---|---|
/bot-ping | 延迟测试 |
/bot-version | 显示 OpenClaw 框架版本 |
/bot-help | 列出所有命令 |
/bot-me | 显示发送者的 QQ 用户 OpenID（用于 allowFrom/groupAllowFrom 设置） |
/bot-upgrade | 显示 QQBot 升级指南链接 |
/bot-logs | 以文件形式导出最近的 Gateway 日志 |
/bot-approve | 批准待处理的 QQ Bot 操作（例如确认 C2C 或群上传），通过原生流程完成 |
在任意命令后加 ? 查看用法帮助（例如 /bot-upgrade ?）。
管理命令（/bot-me、/bot-upgrade、/bot-logs、/bot-clear-storage、/bot-streaming、/bot-approve）仅限私聊，且发送者的 OpenID 必须在非通配符的 allowFrom 白名单中。通配符 allowFrom: ["*"] 允许聊天但不授予管理命令权限。群聊消息先匹配 groupAllowFrom，再回退到 allowFrom。在群聊中运行管理命令会返回提示而非静默丢弃。
引擎架构
QQ Bot 插件内部包含一个独立的引擎：
- 每个账号拥有独立的资源栈（WebSocket 连接、API 客户端、Token 缓存、媒体存储根目录），按
appId分隔。账号之间不共享入站/出站状态。 - 多账号日志器会标识日志行所属的账号，便于在单个 Gateway 下运行多个 Bot 时隔离诊断。
- 入站、出站和 Gateway 桥接路径共享一个媒体根目录
~/.openclaw/media，上传、下载和转码缓存集中管理，而非分散到各个子系统。 - 富媒体发送通过统一的
sendMedia路径处理 C2C 和群目标。大文件或缓冲区超过大文件阈值时使用 QQ 的分块上传端点，较小负载使用一次性媒体 API。 - 凭证可作为标准 OpenClaw 凭证快照的一部分备份和恢复；恢复时引擎会重新附着每个账号的资源栈，无需重新进行二维码配对。
二维码绑定
除了手动粘贴 AppID:AppSecret，引擎还支持通过二维码将 QQ Bot 绑定到 OpenClaw：
- 运行 QQ Bot 设置路径（例如
openclaw channels add --channel qqbot），在提示时选择二维码流程。 - 用与目标 QQ Bot 绑定的手机应用扫描生成的二维码。
- 在手机上批准配对。OpenClaw 将返回的凭证持久化到
credentials/下的对应账号范围中。
Bot 自身生成的批准提示（例如 QQ Bot API 暴露的“允许此操作？”流程）会以原生 OpenClaw 提示形式呈现，可以通过 /bot-approve 接受，而无需在原始 QQ 客户端中回复。
故障排查
- Bot 回复“去火星了”：凭证未配置或 Gateway 未启动。
- 没有入站消息：检查
appId和clientSecret是否正确，以及 Bot 是否在 QQ 开放平台已启用。 - 反复自回复：OpenClaw 会记录 QQ 出站消息的 ref 索引并标记为 Bot 作者，忽略当前
msgIdx匹配同一 Bot 账号的入站事件。这防止了平台回显循环，同时允许用户引用或回复之前的 Bot 消息。 - 使用
--token-file设置后仍显示未配置：--token-file只设置 AppSecret，仍需在配置或QQBOT_APP_ID中设置appId。 - 主动消息未送达：如果用户最近未与 Bot 交互，QQ 可能会拦截 Bot 主动发起的消息。
- 语音未转录：确认 STT 已配置且提供商可达。
常见问题
QQ Bot 报错“去火星了”怎么解决？
“去火星了”表示 OpenClaw Gateway 没有收到消息，原因是 AppID 或 AppSecret 填错、Gateway 未启动，或者插件未安装。检查配置中的 appId 和 clientSecret 是否与 QQ 开放平台一致，确认 openclaw gateway 在运行，如果尚未安装 QQ Bot 先执行 openclaw plugins install @openclaw/qqbot。
AppSecret 丢失了如何重新获取？
AppSecret 在 QQ 开放平台不会以明文保留，离开页面后无法找回。需要进入 Bot 设置页点击“重新生成 AppSecret”，获得新密钥后更新 OpenClaw 配置中的 clientSecret 字段，然后重启 Gateway。旧密钥会立即失效。
群聊中机器人不回复消息怎么办？
检查群聊配置：确认 groups 中没有将该群设置为 requireMention: true（需要 @ 提及），或者你对机器人发了 @ 消息。如果调用了管理命令（如 /bot-me）但未配置白名单，群内会返回提示而非执行。另外，确认机器人已在群内且被腾讯审核通过。