我要投稿

重磅！腾讯QQ机器人接入OpenClaw，官方“养虾”指南来了

发布日期：2026-03-16 18:34:43 浏览次数： 1539

作者：腾讯技术工程

微信搜一搜，关注“腾讯技术工程”

作者：腾讯QQ机器人团队

快速注册一个 QQBot

QQ 机器人开放平台提供了快捷创建 QQ 机器人
的通道，三步即可创建一个可用的 QQBot，用于接入 OpenClaw。

PC 端打开：https://q.qq.com/qqbot/openclaw/login.html，QQ 扫码登录。
点击创建机器人。点击后会立刻成功，此时 BOT 会给你 QQ 发一条成功消息，头像昵称可按用户喜好自定义编辑。
复制 AppID 和 AppSecret 到 🦞 部署地配置即可，配置成功后，即可通过 QQ 使唤你的 🦞。

这个 BOT 仅创建人可用，暂时不支持将 BOT 拉入QQ群内。

机器人创建成功后，此时你的 BOT 还没有“灵魂”，需要接入到你自己的 OpenClaw 运行环境，这里也推荐使用腾讯云的 Lighthouse 接入。

“云上养虾”教程：🔥玩转 OpenClaw｜云上 OpenClaw(Clawdbot) 快速接入 QQ 指南
OpenClaw 官方安装教程：OpenClaw — Personal AI Assistant

其实也并不复杂，在终端执行个命令，按部就班配置一些 model、skills、channel 即可。

QQ 作为 OpenClaw 的通讯渠道，需要在 OpenClaw 安装配置 QQBot 插件，才能与 QQBot 通信。多数云平台（如腾讯云）帮你简化了该步骤，用户仅需复制粘贴相关密钥到云上的管理端页面即可。以下内容讲述如何手动安装 QQBot 插件与更新。

QQ Bot 插件消息收发能力总览：

在原生 OpenClaw 中安装 QQBot 插件

本文介绍在原生 OpenClaw 环境中安装或升级 QQBot 插件的几种常见方式。你可以根据自己的使用习惯，选择远程一键执行、本地脚本执行，或手动安装

QQBot 插件官方仓库：

https://github.com/tencent-connect/openclaw-qqbot

欢迎大家前往查看最新代码与更新说明，也欢迎通过 Issue 和 PR 提出问题反馈与改进建议，共同完善插件能力与接入体验。。

方式一：远程一键安装升级（推荐）

适合希望快速完成安装或升级的场景，无需手动 clone 仓库。

首次安装时，需提供 QQBot 通道凭证：

curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.sh \
  | bash -s -- --appid YOUR_APPID --secret YOUR_SECRET

该命令会自动完成以下步骤：

下载安装脚本
清理旧插件
安装新插件
配置 QQBot 通道
启动或重启 OpenClaw 服务

完成后即可打开 QQ 开始使用。

如果此前已经完成过通道配置，后续升级可直接执行：

curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.sh | bash

说明：如果想要升级QQBot官方插件版本，也可以执行该脚本，这个脚本是带升级能力的，而且默认行为是升级到 npm 上的 latest 版本。如果是想安装指定版本，后面可以跟--version命令：

curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.sh | bash -s -- --version 1.5.7 --appid YOUR_APPID --secret YOUR_SECRET

常用参数如下：

参数	说明
`--appid <id> --secret <secret>`	配置通道。首次安装必填，或在更换凭证时使用
`--version <版本号>`	安装指定版本
`--self-version`	升级到当前仓库 package.json 里声明的版本
`-h` / `--help`	查看完整帮助信息

方式二：源码安装升级

适合希望先查看仓库内容、在本地执行脚本，或希望更灵活控制安装流程的场景。

先拉取仓库：

git clone https://github.com/tencent-connect/openclaw-qqbot.git
cd openclaw-qqbot

通过本地脚本进行源码安装或升级（该脚本同样具有升级到最新版本的能力）：

bash ./scripts/upgrade-via-source.sh --appid YOUR_APPID --secret YOUR_SECRET

说明：脚本执行到后面会让选择 是否后台重启 openclaw 网关服务？[Y/n]，一般选择 Y。如果后台启动正常，会执行 openclaw logs --follow 持续输出 OpenClaw 运行日志。后面看到有日志持续输出代表已经正常启动了，不代表还没升级完，可以 Ctrl+C 关掉前台日志。

正常执行脚本到最后会输出日志：

方式三：npm方式手动安装升级

适合希望完全手动控制安装步骤，或需要排查安装问题的场景。

安装命令：

# （首次安装可跳过）卸载qqbot旧插件，卸载openclaw-qqbot旧版本插件
openclaw plugins uninstall qqbot
openclaw plugins uninstall openclaw-qqbot

# 安装openclaw-qqbot最新版本
openclaw plugins install @tencent-connect/openclaw-qqbot@latest

# 配置通道（首次安装必做）
openclaw channels add --channel qqbot --token "AppID:AppSecret"

# 启动 / 重启服务
openclaw gateway restart

已安装官方openclaw-qqbot，升级版本命令：

# 通过npm 包升级（适用于之前插件本身就是通过可更新来源安装的情况：openclaw plugins install @tencent-connect/openclaw-qqbot）
openclaw plugins update openclaw-qqbot

# 启动 / 重启服务
openclaw gateway restart

安装选择建议

想快速安装：优先使用方式一：远程一键安装升级
想先查看脚本再执行：使用方式二：本地源码安装升级
想自行控制每一步：使用方式三：npm方式手动安装升级

安装结果检查

QQBot 插件是否正常加载

安装完成后，可通过以下命令检查插件是否已成功加载：

openclaw plugins list | grep openclaw-qqbot

如果输出中存在对应插件条目，且状态为 loaded，说明 QQBot 插件已经安装好了，而且已经被 OpenClaw 成功加载。但并不能说明通道一定连上了。

QQBot 通道是否正常连通

执行以下命令查看通道状态：

openclaw channels status

openclaw channels status 中 QQ Bot 通道显示为 enabled, configured, running，且机器人实际可以正常收发消息或 in/out 时间持续更新时，可认为QQBot 通道已正常连通。

这里的 in:2m ago, out:2m ago 说明：

in:2m ago：2 分钟前还有入站消息
out:2m ago：2 分钟前还有出站消息

插件的能力及消息示例

OpenClaw QQBot 插件提供了富媒体收发支持，覆盖图片、语音、视频、文件的双向交互。需要声明的是，QQ Bot 插件仅作为消息通道使用——负责在 QQ 与 OpenClaw 之间中转消息。诸如图像理解、语音转录、绘图等功能，取决于您所配置的 AI 模型以及 OpenClaw 内部已安装的技能，而非本插件本身。

AI 能接收什么

除了接收日常的文本消息以外，QQBot 通道还支持接收多种媒体消息。

接收语音配置示例

其中语音消息（STT）需要单独配置模型能力，用于语音转文字后交给文本大模型处理，配置方式如下：

STT 支持两级配置，按优先级查找：channels.qqbot.stt（插件专属）-> tools.media.audio.models[0]（框架级回退）。以框架级配置为例：

{
  "tools": {
    "media": {
      "audio": {
        "models": [
          { "provider": "xxx", "model": "模型名称" }
        ]
      }
    }
  }
}

这里的 provider 引用 models.providers 中的 key，自动继承 baseUrl 和 apiKey，支持任何 OpenAI 兼容的 STT 接口，也可在条目中直接写 baseUrl / apiKey 覆盖。

另外，插件版本1.5.6已经支持当 STT 未配置或转写失败时，使用 QQ 平台内置 ASR 文本作为低置信度兜底结果，方便没有STT模型的用户可以使用QQ机器人平台侧提供的语音转文本结果。

AI 能发送什么

除了常用的 markdown 消息、文本消息以外，QQBot 插件通道支持发送语音、文件、图片、视频等常用的多媒体消息。

发送语音配置示例

语音（TTS）需要单独配置模型能力，把文字转成语音通过 QQ 发给你。配置 TTS 后，AI 可以把文字变成语音消息发出来。比如让它讲个笑话，回复直接就是一条语音。

TTS 同样支持两级配置：channels.qqbot.tts（插件专属）-> messages.tts（框架级回退）。以插件专属配置为例：

{
  "channels": {
    "qqbot": {
      "tts": {
        "provider": "xxx",
        "model": "模型名称",
        "voice": "模型名称:音色名称"
      }
    }
  }
}

provider 引用 models.providers 中的 key，自动继承 baseUrl 和 apiKey。可通过 voice 选择音色，设置 enabled: false 可禁用。

另外如果没有现成可使用的 TTS 模型，也可以使用 TTS/Edge（OpenClaw 原生支持的一种 TTS provider），配置如下（在messages里增加tts的配置）：

{
  "messages": {
    "tts": {
      "auto": "inbound",
      "provider": "edge",
      "edge": {
        "enabled": true,
        "voice": "zh-CN-XiaoxiaoNeural",
        "lang": "zh-CN"
      }
    }
  }
}

验证通道发送图片或者文件正常

可以用以下方式验证 QQ Bot 通道发送图片/文件能力是否正常：发给模型一张图片，让模型把这张图回给你。如果能正常回复，说明通道能力正常。注意，生成图片或者对文件进行理解等都是 OpenClaw 自己的能力，需要配置对应的模型或者 Skills，QQ Bot 插件只负责传输。

体验演示场景

以下是几个可以直接复现的玩法：

如何配置 Skills

在腾讯云 Lighthouse 安装 clawhub 的 Skills

在 Lighthouse 实例的应用管理页面上可以直接安装 skills，如图：

点击页面上【获取更多 skills】的链接跳到开源社区 ClawHub 的官网，选择你需要的 skills。注意这里 skills 的名字，就是点击跳转某个 skills 的页面链接 URL 最后的内容：

确定名字后，直接在 Lighthouse 应用管理页面上点击【安装技能】即可。

手动安装 clawhub 的 Skills

如果想手动安装 ClawHub 上的 skills，具体步骤如下：

# 1. 安装 clawhub cli
npm i -g clawhub

# 2. 装完确定下是否可用：
clawhub --help

# 3. 进入 OpenClaw workspace
cd ~/.openclaw/workspace

# 4. 搜索 skill
clawhub search "你想要的功能关键词"

# 5. 安装 skill
clawhub install <skill-slug>

# 6. 检查是否识别到
openclaw skills list
openclaw skills check

# 7. 如需配置 API Key，则编辑配置文件
vi ~/.openclaw/openclaw.json

# 8. 重启 gateway
openclaw gateway restart

# 9. 看日志
openclaw logs --follow

# 10. 检查目前已经安装了哪些 skills
openclaw skills list --eligible
openclaw skills info <这里填 list 里显示的某个 skills 的名字>

如果完成以上安装后，Agent 提示仍找不到对应 skills，可以通过和 agent 对话的方式让 OpenClaw 分析问题并完成安装：

也推荐大家遇到各种包括 skills 安装在内的问题时，尝试习惯通过和 agent 交流，让它帮你分析并解决问题。

手动安装自己写的 Skills

安装自己写的 skills，最主要的就是把你的 skills 建一个文件夹放在 ~/.openclaw/workspace/skills/ 目录下。

这里提供了一个安装 my-demo-skill 的简单示例：

# 1. 创建 skills 目录，假设这里的 skills 叫 my-demo-skill
mkdir -p ~/.openclaw/workspace/skills/my-demo-skill

# 2. 写入 skills，或者把已经写好的 skills 放在对应目录下
cat > ~/.openclaw/workspace/skills/my-demo-skill/SKILL.md <<'SKILL_EOF'
---
name: my_demo_skill
description: A simple custom skill for testing.
---

# My Demo Skill

当用户要求测试自定义 skill 时，优先遵循这里的说明。

触发示例：
- “调用 my demo skill”

行为：
- 回复：“已命中 my_demo_skill”
SKILL_EOF

# 3. 让 OpenClaw 重新发现这个 skill，可以通过对话让 agent “refresh skills”，或者直接重启 gateway
openclaw gateway restart
openclaw skills list
openclaw skills info my_demo_skill