QQ Bot

QQ Bot 通过官方 QQ Bot API（WebSocket 网关）连接 OpenClaw。养了一只龙虾想接入 QQ？这是你需要的配置指南。

插件支持 C2C 私聊、群组 @消息和频道消息，含富媒体（图片、语音、视频、文件）。

状态：内置插件。支持私聊、群聊、频道和媒体；不支持消息回应和线程。

内置插件

当前 OpenClaw 版本已内置 QQ Bot，正常打包版本无需额外 openclaw plugins install。

初始设置

1. 前往 QQ 开放平台 并用手机 QQ 扫码注册/登录
2. 点击创建机器人创建新 QQ Bot
3. 在 Bot 设置页找到 AppID 和 AppSecret 并复制

AppSecret 不会以明文保存——如果离开页面未保存，需要重新生成

4. 添加渠道：

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

5. 重启 Gateway

交互式设置：

openclaw channels add
openclaw configure --section channels

配置

最简配置：

{
  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",
    },
  },
}

clientSecret 也支持 SecretRef 格式，不限于明文字符串

多账号配置

在单个 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 连接，Token 缓存按 appId 隔离。

通过 CLI 添加第二个 Bot：

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

语音（STT / TTS）

STT 和 TTS 支持两层配置，优先级递减：

设置	插件专用	框架回退
STT	channels.qqbot.stt	tools.media.audio.models[0]
TTS	channels.qqbot.tts	messages.tts

{
  channels: {
    qqbot: {
      stt: {
        provider: "your-provider",
        model: "your-stt-model",
      },
      tts: {
        provider: "your-provider",
        model: "your-tts-model",
        voice: "your-voice",
      },
    },
  },
}

设置 enabled: false 可禁用其中一项。

目标格式

格式	说明
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-upgrade	显示 QQBot 升级指南链接
/bot-logs	以文件形式导出最近的 Gateway 日志

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

故障排查

• Bot 回复"去火星了"：凭证未配置或 Gateway 未启动
• 没有入站消息：检查 appId 和 clientSecret 是否正确，以及 Bot 是否在 QQ 开放平台已启用
• --token-file 设置后仍显示未配置：--token-file 只设置 AppSecret，仍需在配置或 QQBOT_APP_ID 中设置 appId
• 主动消息未送达：如果用户最近未交互，QQ 可能会拦截 Bot 主动发起的消息
• 语音未转录：确认 STT 已配置且提供商可达

相关文档

• 渠道概览 — 所有支持的渠道
• 配对 — DM 认证和配对流程
• 群组 — 群聊行为和提及门控