OpenClaw QQ Bot 接入指南

📌 背景

QQ 是一款覆盖广泛用户群体的即时通讯平台，提供文字、语音、图片、文件等多种沟通能力，并支持群聊、频道等协作场景，适用于个人交流与团队协同。

该接入方式可将 OpenClaw 与 QQ Bot 进行连接，通过平台的长连接事件订阅机制接收消息与事件回调，从而在不对外暴露公网 Webhook 地址的情况下实现稳定、安全的消息收发与自动化能力集成。

---

📖 正文

1. 安装 QQ Bot 插件

使用 openclaw plugins 命令安装：

openclaw plugins install @sliverp/qqbot@latest

使用源码安装：

git clone https://github.com/sliverp/qqbot.git && cd qqbot
openclaw plugins install .

2. 注册 QQ 开放平台账号

前往 腾讯 QQ 开放平台官网 注册账号。

注意事项：

• 默认无法使用您的 QQ 账号直接登录，需要新注册 QQ 开放平台账号
• 首次注册之后，可以按照 QQ 开放平台的指引设置超级管理员

主体信息填写（以”个人”为例）：

1. 按照指引依次输入姓名、身份证号、手机号、验证码
2. 点击继续进入下一步人脸认证
3. 使用手机 QQ 扫码进行人脸认证
4. 人脸识别审核通过后，即可登录进入 QQ 开放平台

3. 创建 QQ 机器人

在 QQ 开放平台的 QQ 机器人页面，可以创建机器人。

创建完成后：

1. 选择机器人点击进入管理页面
2. 获取当前机器人的 AppID 和 AppSecret
3. 复制并将其保存到个人记事本或备忘录中（请注意数据安全，勿泄露）

⚠️ 注意： 出于安全考虑，QQ 机器人的 AppSecret 不支持明文保存，首次查看或忘记 AppSecret 需要重新生成。

4. 配置沙箱环境

在 QQ 机器人的”开发管理”页面，在”沙箱配置”中，设置单独聊天（选择”在消息列表配置”）。

配置步骤：

1. 先添加成员
2. 再通过该成员的 QQ 扫码来添加机器人
3. 添加成员成功之后，还需要使用 QQ 扫码添加

⚠️ 重要提示：

• 此处已创建的 QQ 机器人无需进行发布上架对所有 QQ 用户公开使用
• 在开发者私人的（沙箱）调试下使用体验即可
• QQ 开放平台不支持机器人的”在 QQ 群配置”操作，只支持单独和 QQ 机器人聊天

此时您的 QQ 账号添加机器人之后，还不能与该机器人正常进行对话，会提示”该机器人去火星了，稍后再试吧”，因为 QQ 机器人此时尚未与 OpenClaw 应用打通。您需要继续后面的步骤，为 OpenClaw 应用配置 QQ 机器人的 AppID 和 AppSecret。

5. 配置 OpenClaw

添加 qqbot channel 并将步骤 3 中获取的 AppID 和 AppSecret 配置好：

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

编辑 ~/.openclaw/openclaw.json：

{
  "channels": {
    "qqbot": {
      "enabled": true,
      "appId": "你的 AppID",
      "clientSecret": "你的 AppSecret"
    }
  }
}

6. STT 和 TTS 配置（可选）

STT 和 TTS 各支持两级配置，插件会按优先级依次查找，找到有效配置即停止。

能力	优先级 1（插件专属）	优先级 2（框架级回退）
STT	channels.qqbot.stt	tools.media.audio.models[0]
TTS	channels.qqbot.tts	messages.tts

STT 配置方式一（插件专属，优先级最高）：

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

TTS 配置方式一（插件专属，优先级最高）：

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

配置后：

• 用户发来的语音消息会自动转换（SILK→WAV）并转录为文字
• AI 可使用标签通过兼容的 TTS API 生成并发送语音消息

7. 重启 Gateway

openclaw gateway restart

---