QQ Bot

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

安装

openclaw plugins install @openclaw/qqbot

设置

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

AppSecret 不会以明文存储。如果未保存就离开页面，则必须重新生成一个。

添加渠道：

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

重启 Gateway 网关。

入站持久性

对于 QQ Gateway 网关轮次事件，OpenClaw 会先持久化原始事件，然后再推进已保存的 Gateway 网关恢复序列。待处理或可重试的轮次可在 Gateway 网关重启后继续保留，按会话维持串行处理，并在有效或保留的完成记录存在期间，使用提供商事件 ID 避免重复的队列条目。如果持久化接纳失败，OpenClaw 会终止当前 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； appId 必须已在配置或 QQBOT_APP_ID 中设置。
clientSecret 接受明文字符串、文件路径（clientSecretFile）或结构化 SecretRef 对象。
clientSecret 不接受旧版 secretref:... / secretref-env:... 标记字符串；请改用结构化 SecretRef 对象。

流式传输

{
  channels: {
    qqbot: {
      streaming: {
        mode: "partial", // 分块流式传输："partial"（默认）或 "off"
        nativeTransport: true, // 对私信使用 QQ 官方 C2C stream_messages API
      },
    },
  },
}

streaming.mode: "off" 会禁用该账号的分块流式传输。
streaming.nativeTransport: true 通过 QQ 官方 stream_messages API 流式传输 C2C（私信）回复；不影响群组/频道目标。
旧版 streaming: true|false 标量和 streaming.c2cStreamApi 键通过 openclaw doctor --fix 迁移到此结构。
/bot-streaming on|off 可从私信中切换同一项配置。

访问策略

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 条目会覆盖某个群组的这些默认值。群组设置：

字段	默认值	描述
`requireMention`	`true`	Bot 回复前要求存在 `@` 提及。
`commandLevel`	`all`	可在群组中运行哪些内置斜杠命令（见下文）。
`ignoreOtherMentions`	`false`	丢弃提及其他人但未提及 Bot 的消息。
`historyLimit`	`50`	保留近期未提及消息，作为下一次提及轮次的上下文。`0` 会禁用历史记录。
`tools`	—	为整个群组允许/拒绝工具。
`toolsBySender`	—	按发送者覆盖工具设置；参见群组。
`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。会话级激活覆盖设置（如果存在）优先于配置。入站队列按对端划分。群组对端的队列容量更大（50，而直接对端为 20），队列满时会先淘汰 Bot 编写的消息，再淘汰人类消息，并将连续的一般群组消息合并为一个带来源标注的轮次。斜杠命令逐个运行，不受任何合并批次影响。

语音（STT / TTS）

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

设置	插件专用	框架回退
STT	`channels.qqbot.stt`	第一个支持音频的 `tools.media.models[]` 条目
TTS	`channels.qqbot.tts`、`channels.qqbot.accounts.<id>.tts`	`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 覆盖使用与 tts 相同的结构，并深度合并到渠道/全局 TTS 配置之上。 STT 请求默认在 60 秒后超时。插件专用 STT 使用选定的 models.providers.<id>.timeoutSeconds 覆盖设置。框架音频 STT 使用选定的支持音频的 tools.media.models[] 条目的 timeoutSeconds，然后使用选定的提供商覆盖设置。入站 QQ 语音附件会作为音频媒体元数据提供给智能体，同时避免将原始语音文件放入通用 MediaPaths。配置 TTS 后，纯文本回复中的 [[audio_as_voice]] 会合成 TTS 并发送原生 QQ 语音消息。还可以使用 channels.qqbot.audioFormatPolicy 调整出站音频上传/转码行为：

sttDirectFormats
uploadDirectFormats
transcodeEnabled

目标格式

格式	描述
`qqbot:c2c:OPENID`	私聊（C2C）
`qqbot:group:GROUP_OPENID`	群聊
`qqbot:channel:CHANNEL_ID`	频道

每个 Bot 都有自己的一组用户 OpenID。通过 Bot A 收到的 OpenID 不能用于通过 Bot B 发送消息。

斜杠命令

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

命令	身份验证	范围	描述
`/bot-ping`	—	任意	延迟测试
`/bot-help`	—	任意	列出所有命令
`/bot-me`	—	仅私聊	显示发送者的 QQ 用户 ID（openid），用于 `allowFrom` / `groupAllowFrom` 设置
`/bot-version`	—	仅私聊	显示 OpenClaw 框架版本和插件版本
`/bot-upgrade`	—	仅私聊	显示 QQ Bot 升级指南链接
`/bot-approve`	允许列表	仅私聊	管理命令执行审批配置（on / off / always / reset / status）
`/bot-logs`	允许列表	仅私聊	将最近的 Gateway 网关日志导出为文件
`/bot-clear-storage`	允许列表	仅私聊	删除 QQ Bot 媒体目录下缓存的下载内容
`/bot-streaming`	允许列表	仅私聊	切换 C2C 流式回复
`/bot-group-allways`	允许列表	仅私聊	切换默认群组激活模式（需要提及与始终开启）

在任何命令后附加 ? 可查看用法帮助（例如 /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，并且提供商可访问。

概览

消息平台

Developer and self-hosted

Regional platforms

配置

安装

设置

入站持久性

配置

流式传输

访问策略

多账号设置

群聊

语音（STT / TTS）

目标格式

斜杠命令

媒体和存储

故障排查

相关内容

​安装

​设置

​入站持久性

​配置

​流式传输

​访问策略

​多账号设置

​群聊

​语音（STT / TTS）

​目标格式

​斜杠命令

​媒体和存储

​故障排查

​相关内容

安装

设置

入站持久性

配置

流式传输

访问策略

多账号设置

群聊

语音（STT / TTS）

目标格式

斜杠命令

媒体和存储

故障排查

相关内容