Channel - QQ Bot

QQ Bot 通过官方 QQ Bot API（WebSocket gateway）连接 OpenClaw。支持 C2C 私聊、群 @消息、频道消息及富媒体（图片、语音、视频、文件）。状态：可下载插件。

安装

openclaw plugins install @openclaw/qqbot

配置步骤

前往 QQ 开放平台注册/登录
点击创建机器人
在 bot 设置页找到 AppID 和 AppSecret
添加 channel：

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

重启 Gateway

最小配置

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

环境变量：QQBOT_APP_ID、QQBOT_CLIENT_SECRET

多账号配置

{
  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 隔离）。

群聊配置

{
  channels: {
    qqbot: {
      groupPolicy: "allowlist",
      groups: {
        "*": { requireMention: true, historyLimit: 50 },
        GROUP_OPENID: {
          name: "Release room",
          requireMention: false,
          historyLimit: 20,
          prompt: "Keep replies short.",
        },
      },
    },
  },
}

关键参数：

requireMention：是否需要 @mention（默认 true）
historyLimit：保留最近 N 条消息作为上下文
toolPolicy：full、restricted 或 none
prompt：每个群的专属行为提示

消息目标格式

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

注意：每个 bot 有独立的用户 OpenID，Bot A 的 OpenID 不能用于 Bot B 发消息。

内置 Slash 命令

命令	说明
`/bot-ping`	延迟测试
`/bot-version`	显示 OpenClaw 版本
`/bot-me`	显示发送者 QQ openid
`/bot-logs`	导出最近 gateway 日志
`/bot-approve`	审批待处理的 QQ Bot 操作

管理命令（/bot-me、/bot-logs 等）仅限私聊，且发送者 openid 必须在非通配符 allowFrom 列表中。

语音（STT/TTS）

支持两级配置，优先使用插件级配置，回退到框架级：

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

故障排查

Bot 无响应：检查凭证配置和 Gateway 是否启动
无入站消息：验证 appId 和 clientSecret，确认 bot 在 QQ 开放平台已启用
重复自回复：OpenClaw 记录出站 ref index 并忽略匹配的入站事件，防止平台回声循环

Wiki AI

目录