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

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

OpenClaw plugins命令安装

openclaw plugins install @sliverp/qqbot@latest

使用源码安装：

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

前往腾讯QQ开放平台官网，默认无法使用您的QQ账号直接登录，需要新注册QQ开放平台账号。

首次注册之后，可以按照QQ开放平台的指引设置超级管理员。

手机QQ扫码成功后，继续下一步填写主体相关信息。

此处以“个人”为例，按照指引依次输入姓名、身份证号、手机号、验证码，点击继续进入下一步人脸认证。

使用手机QQ扫码进行人脸认证。

人脸识别审核通过后，即可登录进入QQ开放平台。

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

QQ机器人创建完成之后，可选择机器人点击进入管理页面。

在QQ机器人管理页面获取当前机器人的AppID和AppSecret，复制并将其保存到个人记事本或备忘录中（请注意数据安全，勿泄露），后续在“步骤3中配置OpenClaw“中需要使用。

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

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

您可以按照自己的使用场景进行配置，也可以完成后续步骤之后再回到本步骤进行操作。

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

注意：选择“在消息列表配置”时，需要先添加成员，再通过该成员的QQ扫码来添加机器人。 此处注意添加成员成功之后，还需要使用QQ扫码添加

此时您的QQ账号添加机器人之后，还不能与该机器人正常进行对话，会提示“该机器人去火星了，稍后再试吧”，因为QQ机器人此时尚未与OpenClaw应用打通。

您需要继续后面的步骤，为OpenClaw应用配置QQ机器人的AppID和AppSecret。

（可选）您也可以参考前述步骤添加更多成员：首先在成员管理页面中添加新成员，然后在沙箱配置页面中添加成员，之后新成员即可通过QQ扫码添加该QQ机器人。

添加qqbot channel 并将步骤2中获取的AppID和AppSecret

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

编辑 ~/.openclaw/openclaw.json:

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

STT 和 TTS 各支持两级配置，插件会按优先级依次查找，找到有效配置即停止。每一级的 baseUrl / apiKey 均可从 models.providers 自动继承。

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

每一级中，baseUrl 和 apiKey 的解析顺序：本级直接配置 → models.providers.<provider> 继承。两者必须同时有值，该级配置才生效。

方式一（插件专属，优先级最高）：在 channels.qqbot.stt 下配置：

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

方式二（框架级回退）：在 tools.media.audio.models 中添加音频模型条目。当 channels.qqbot.stt 未配置时，插件会自动读取这里的第一个条目：

{
  "tools": {
    "media": {
      "audio": {
        "models": [
          {
            "provider": "your-provider",
            "model": "your-stt-model",
            "baseUrl": "https://your-provider-api-base-url"
          }
        ]
      }
    }
  }
}

• provider — 引用 models.providers 中的 key，继承 baseUrl 和 apiKey
• model — STT 模型名称
• baseUrl / apiKey — 可选，写在本级则覆盖 provider 默认值
• enabled — 设为 false 可禁用
• 配置后，用户发来的语音消息会自动转换（SILK→WAV）并转录为文字

方式一（插件专属，优先级最高）：在 channels.qqbot.tts 下配置：

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

方式二（框架级回退）：在 messages.tts 下配置。当 channels.qqbot.tts 未配置时，插件会自动读取这里的配置：

{
  "messages": {
    "tts": {
      "provider": "your-provider",
      "your-provider": {
        "apiKey": "your-api-key",
        "model": "your-tts-model",
        "voice": "your-voice"
      }
    }
  }
}

注意：messages.tts 的 provider 子配置放在 messages.tts.<provider> 下（如 messages.tts.your-provider），结构与方式一略有不同。

• provider — 引用 models.providers 中的 key，继承 baseUrl 和 apiKey
• model — TTS 模型名称
• voice — 语音音色
• baseUrl / apiKey — 可选，写在本级则覆盖 provider 默认值
• enabled — 设为 false 可禁用（默认：true）；messages.tts 中对应字段为 auto: "disabled"
• 配置后，AI 可使用 <qqvoice> 标签通过兼容的 TTS API 生成并发送语音消息

openclaw gateway

仅适用于通过 openclaw plugins install 安装的场景

openclaw plugins upgrade @sliverp/qqbot@latest

npx -y @sliverp/qqbot@latest upgrade

bash ./upgrade-and-run.sh

不传 --appid / --secret 参数时，脚本会自动读取 ~/.openclaw/openclaw.json（或 ~/.clawdbot/clawdbot.json）中已有的通道配置，无需每次升级都重新输入凭据。

首次配置或需要覆盖时：

bash ./upgrade-and-run.sh --appid YOUR_APPID --secret YOUR_SECRET

完整选项：

选项	说明
--appid <id>	QQ 机器人 AppID
--secret <secret>	QQ 机器人 AppSecret
--markdown <yes|no>	是否启用 Markdown 消息格式（默认: no）
-h, --help	显示帮助

也支持环境变量：QQBOT_APPID、QQBOT_SECRET、QQBOT_TOKEN（AppID:Secret）。

从 GitHub 拉取最新源码，安装依赖并重启：

bash ./pull-latest.sh

如果插件目录已有 .git 仓库，会执行增量 git pull；否则从头克隆。已有的通道配置会自动备份和恢复。

bash ./pull-latest.sh --branch main            # 指定分支（默认 main）
bash ./pull-latest.sh --force                   # 跳过交互，强制更新
bash ./pull-latest.sh --repo <git-url>          # 使用其他仓库地址

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

# 运行升级脚本
bash ./scripts/upgrade.sh

# 重新安装
openclaw plugins install .

# 重新配置
openclaw channels add --channel qqbot --token "AppID:AppSecret"

# 重启 gateway
openclaw gateway restart

英文