重磅！腾讯QQ机器人接入OpenClaw，官方“养虾”指南来了
作者：腾讯QQ机器人团队
快速注册一个 QQBot
QQ 机器人开放平台提供了快捷创建 QQ 机器人的通道，三步即可创建一个可用的 QQBot，用于接入 OpenClaw。
1. PC 端打开：https://q.qq.com/qqbot/openclaw/login.html，QQ 扫码登录。
2. 点击创建机器人。点击后会立刻成功，此时 BOT 会给你 QQ 发一条成功消息，头像昵称可按用户喜好自定义编辑。
3. 复制 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
常用参数如下：
![50S0`HR]))40}R5$5S7R$70.png](http://sy0.img.pcpop.com/copy/1773712834/1773712834435/1773712834435247.png)
方式二：源码安装升级
适合希望先查看仓库内容、在本地执行脚本，或希望更灵活控制安装流程的场景。
先拉取仓库：
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
# 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
通过对话验证 my-demo-skill 触发成功：
FAQ（持续更新）
Q：为什么一直输出“你好，我不能提供相关信息”？
A：模型输入输出内容会进行安全审查，可以尝试以下方法：
• 通过 /new 开启新对话
• 更换模型后再试
Q：为什么设置好 QQ 机器人信息后，与机器人对话时小灰条提示“我的灵魂不在线”等错误？
A1：如果是第一次配置，OpenClaw 与机器人建立联系可能需要一点时间，可以尝试重启几次 openclaw gateway restart
A2：如果原来已经有机器人，又重新更换配置了新的APPID，如果机器人无法回复：
● 解决方式1：删除 ~/.openclaw/qqbot/sessions/session-default.json 然后重启
● 解决方式2：更新 QQBot 插件（见前文插件更新教程）
A3：如果一直提示此错误，是因为机器人没有在线，检查机器人APPID和密钥配置是否正常。
Q：机器人提示已经被注销怎么办？
A：解决方案：检查是否删除了机器人，如果删除了7天内可以前往 QQ开放平台 进行恢复。
Q：为什么在群里面@机器人，遇到提示："该机器人当前服务状态异常，暂时无法回复消息"？创建的openclaw机器人是否支持加群？
A：因为openclaw机器人暂不支持加群，仅支持个人用户私聊使用。如果有下一步支持计划，会及时更新文档通知大家。
Q：快速创建的openclaw机器人是否支持在开放平台修改信息？
A：支持，方式如下：
Q：机器人为什么回复“401 not authorized”？
A：模型配置没有成功，请注意检查下模型 api key 配置，注意并不是 qqbot 的 secret 哦。
Q：机器人为什么回复“API rate limit reached. Please try again later.”
A：模型调用频率太快了，请检查模型使用情况或更换模型。
Q：如何联系官方人员？
A：可加入讨论群、讨论频道或添加机器人进行反馈，见文本最后的二维码。
Q：如何查询日志？
A：请登录openclaw运行的机器，使用终端输入“openclaw logs --follow”以显示实时日志。
Q：为什么openclaw机器人发不出图片？
A：可以发一张图片让机器人原样回给你，验证下是通道的问题，还是模型没有画图skills工具。如果是需要画图能力，需要自己配置画图skills，一般需要自己购买生图模型获得生图的api key。
Q：如果我从其他渠道的 qqbot 插件想升级到官方插件 @tencent-connect/openclaw-qqbot，应该怎么操作？
A：升级方式参考本文里的【原生 OpenClaw 安装插件 QQBot 插件】这部分内容。
交流与反馈
如果QQ 交流群已经满员，可前往 PC 管理端扫码添加最新群聊：
https://q.qq.com/qqbot/openclaw/login.html
最后，QQBot 官方接入指南仍在持续更新，欢迎访问在线文档 《QQ机器人接入 OpenClaw 的官方“养虾”指南》 查看最新内容。如果你在养虾过程中遇到问题，或有任何建议与反馈，也欢迎随时交流。我们会持续补充和完善文档内容，陪大家一起把虾养得更轻松、更顺手。
关注我们
