QQ Bot

QQ Bot 通过官方 QQ Bot API（WebSocket 网关）连接到 OpenClaw。 C2C 私聊和群组 @ 提及是主要聊天类型，并支持丰富的媒体内容（图片、语音、视频、文件）。频道消息仅支持文本和远程 URL 图片；频道中不支持语音、视频、文件上传以及本地/Base64 图片。任何场景均不支持表情回应和话题串。

状态：官方可下载插件。

安装

openclaw plugins install @openclaw/qqbot

设置

1. 前往 QQ 开放平台，使用手机 QQ 扫描二维码以注册/登录。
2. 点击 Create Bot 创建新的 QQ Bot。
3. 在 Bot 的设置页面找到 AppID 和 AppSecret，并复制它们。

4. 添加渠道：

openclaw channels add --channel qqbot --token "AppID:AppSecret"

5. 重启 Gateway 网关。

交互式设置：

openclaw channels add

除手动输入 AppID/AppSecret 外，向导还提供二维码绑定方式：使用与目标 QQ Bot 关联的手机应用扫描二维码即可完成绑定。OpenClaw 会将返回的凭据持久化到该账户的配置作用域中。

配置

最小配置：

{  channels: {    qqbot: {      enabled: true,      appId: "YOUR_APP_ID",      clientSecret: "YOUR_APP_SECRET",    },  },}

默认账户环境变量（仅限顶层账户）：

• QQBOT_APP_ID
• QQBOT_CLIENT_SECRET

文件支持的 AppSecret：

{  channels: {    qqbot: {      enabled: true,      appId: "YOUR_APP_ID",      clientSecretFile: "/path/to/qqbot-secret.txt",    },  },}

环境变量 SecretRef AppSecret：

{  channels: {    qqbot: {      enabled: true,      appId: "YOUR_APP_ID",      clientSecret: { source: "env", provider: "default", id: "QQBOT_CLIENT_SECRET" },    },  },}

注意：

• openclaw channels add --channel qqbot --token-file ... 仅设置 AppSecret；必须已在配置或 QQBOT_APP_ID 中设置 appId。
• clientSecret 接受明文字符串、文件路径（clientSecretFile）或结构化 SecretRef 对象。
• clientSecret 不接受旧版 secretref:... / secretref-env:... 标记字符串；请改用结构化 SecretRef 对象。

访问策略

• allowFrom / groupAllowFrom 限制谁可以在 C2C / 群组场景中与 Bot 聊天。dmPolicy / groupPolicy（open | allowlist | disabled）控制执行模式。只要 allowFrom 包含具体的非通配符条目，dmPolicy 就默认为 allowlist，否则默认为 open。只要 groupAllowFrom 或 allowFrom 包含具体条目，groupPolicy 就默认为 allowlist，否则默认为 open。
• 无论 dmPolicy / groupPolicy 如何设置，“身份验证：允许列表”斜杠命令都要求 allowFrom 中存在明确的非通配符条目（群组调用则要求 groupAllowFrom 中存在该条目）——参阅斜杠命令。

多账户设置

在单个 OpenClaw 实例下运行多个 QQ Bot：

{  channels: {    qqbot: {      enabled: true,      appId: "111111111",      clientSecret: "secret-of-bot-1",      accounts: {        bot2: {          enabled: true,          appId: "222222222",          clientSecret: "secret-of-bot-2",        },      },    },  },}

每个账户拥有独立的 WebSocket 连接、API 客户端和令牌缓存，并以 appId 为键。日志行会标记所属账户 ID，因此在一个 Gateway 网关下运行多个 Bot 时，各账户的诊断信息仍可区分。

通过 CLI 添加第二个 Bot：

openclaw channels add --channel qqbot --account bot2 --token "222222222:secret-of-bot-2"

群聊

群组支持使用 QQ 群组 OpenID，而不是显示名称。将 Bot 添加到群组，然后提及它，或将群组配置为无需提及即可运行。

{  channels: {    qqbot: {      groupPolicy: "allowlist",      groupAllowFrom: ["member_openid"],      groups: {        "*": {          requireMention: true,          commandLevel: "all",          historyLimit: 50,          tools: { deny: ["exec", "read", "write"] },        },        GROUP_OPENID: {          name: "Release room",          requireMention: false,          ignoreOtherMentions: true,          commandLevel: "safety",          historyLimit: 20,          prompt: "Keep replies short and operational.",        },      },    },  },}

groups["*"] 为所有群组设置默认值；具体的 groups.GROUP_OPENID 条目会覆盖某个群组的这些默认值。群组设置：

commandLevel 接受以下值：

旧版 QQ Bot toolPolicy 条目已停用。运行 openclaw doctor --fix 将其迁移到 tools。

激活模式为 mention 和 always。requireMention: true 映射到 mention；requireMention: false 映射到 always。如果存在会话级激活覆盖设置，则其优先级高于配置。

入站队列按对端划分。群组对端的队列容量上限更大（50，直接对端为 20）；队列已满时，会先逐出 Bot 发出的消息，再逐出用户消息；连续涌入的普通群组消息会合并为一个注明来源的轮次。斜杠命令逐个运行，不受任何合并批次影响。

语音（STT / TTS）

STT 和 TTS 支持具有优先级回退的两级配置：

{  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 配置之上。

STT 请求默认在 60 秒后超时。插件专属 STT 使用所选 models.providers.<id>.timeoutSeconds 覆盖值。框架音频 STT 依次使用 tools.media.audio.models[0].timeoutSeconds、tools.media.audio.timeoutSeconds，然后使用所选提供商的覆盖值。

入站 QQ 语音附件会作为音频媒体元数据提供给智能体，同时避免将原始语音文件放入通用 MediaPaths。配置 TTS 后，在纯文本回复中使用 [[audio_as_voice]] 会合成 TTS 并发送原生 QQ 语音消息。

还可通过 channels.qqbot.audioFormatPolicy 调整出站音频上传/转码行为：

• sttDirectFormats
• uploadDirectFormats
• transcodeEnabled

目标格式

斜杠命令

在进入 AI 队列前截获的内置命令：

在任何命令后附加 ? 可查看用法帮助（例如 /bot-upgrade ?）。

“身份验证：允许列表”命令还要求发送者的 OpenID 位于明确的非通配符 allowFrom 列表中（群组中发出的命令优先使用 groupAllowFrom，否则回退到 allowFrom）。通配符 allowFrom: ["*"] 允许聊天，但不允许使用这些命令。在私聊之外运行这些命令或未获得授权时，系统会返回提示，而不是静默丢弃消息。

/bot-me、/bot-version 和 /bot-upgrade 仅限私聊使用，但不要求加入允许列表——任何 C2C 发送者都可以运行它们。

当 QQ Bot Exec 审批使用默认的同聊天回退时，点击原生审批按钮会遵循同一份显式的非通配符命令允许列表。若只授予审批权限而不授予更广泛的命令访问权限，请配置 channels.qqbot.execApprovals.approvers。原生 Exec 审批默认启用。

媒体和存储

• 入站、出站和 Gateway 网桥媒体共用 ~/.openclaw/media/qqbot 下的同一个载荷根目录（设置 OPENCLAW_HOME 时会遵循该设置），因此上传、下载和转码缓存都位于同一个受保护目录下。
• 面向 C2C 和群组目标的富媒体投递统一通过 sendMedia 路径进行。大小为 5 MiB 或以上的本地文件和内存缓冲区使用 QQ 的分块上传端点；较小的载荷以及远程 URL/Base64 来源使用单次上传 API。
• 如果热升级在 Gateway 网关完成写入 openclaw.json 前将其中断，插件会在下次启动时从内部快照恢复该账户最后已知的 appId / clientSecret（绝不会覆盖有意进行的配置更改），因此无需重新扫描二维码。

故障排查

• **Gateway 网关无法启动/没有入站消息：**请验证 appId 和 clientSecret 是否正确，并确认该机器人已在 QQ 开放平台启用。缺少凭据时会显示“QQBot 未配置（缺少 appId 或 clientSecret）”。
• 使用 --token-file 设置后仍显示未配置：--token-file 只设置 AppSecret。仍必须在配置或 QQBOT_APP_ID 中设置 appId。
• **突发的群组回复发生冲突：**当某个对端的队列已满时，入站队列会优先淘汰机器人发送的消息，而不是人类发送的消息；它还会将突发的普通（非命令）群组消息合并成一个注明发送者的轮次，因此大量机器人消息不应导致人类消息得不到处理。
• **主动消息未送达：**如果用户最近没有互动，QQ 可能会阻止机器人主动发起的消息。
• **语音未转录：**请确保已配置 STT，并且提供商可访问。

相关内容

• 配对
• 群组
• 渠道故障排查