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

作者：腾讯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.gitcd 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 qqbotopenclaw 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 clinpm i -g clawhub# 2. 装完确定下是否可用：clawhub --help# 3. 进入 OpenClaw workspacecd ~/.openclaw/workspace# 4. 搜索 skillclawhub search "你想要的功能关键词"# 5. 安装 skillclawhub install <skill-slug># 6. 检查是否识别到openclaw skills listopenclaw skills check# 7. 如需配置 API Key，则编辑配置文件vi ~/.openclaw/openclaw.json# 8. 重启 gatewayopenclaw gateway restart# 9. 看日志openclaw logs --follow# 10. 检查目前已经安装了哪些 skillsopenclaw skills list --eligibleopenclaw skills info <这里填 list 里显示的某个 skills 的名字>

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

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

手动安装自己写的 Skills

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

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

# 1. 创建 skills 目录，假设这里的 skills 叫 my-demo-skillmkdir -p ~/.openclaw/workspace/skills/my-demo-skill# 2. 写入 skills，或者把已经写好的 skills 放在对应目录下cat > ~/.openclaw/workspace/skills/my-demo-skill/SKILL.md <<'SKILL_EOF'---name: my_demo_skilldescription: A simple custom skill for testing.---# My Demo Skill当用户要求测试自定义 skill 时，优先遵循这里的说明。触发示例：- “调用 my demo skill”行为：- 回复：“已命中 my_demo_skill”SKILL_EOF# 3. 让 OpenClaw 重新发现这个 skill，可以通过对话让 agent “refresh skills”，或者直接重启 gatewayopenclaw gateway restartopenclaw skills listopenclaw 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 的官方“养虾”指南》查看最新内容。如果你在养虾过程中遇到问题，或有任何建议与反馈，也欢迎随时交流。我们会持续补充和完善文档内容，陪大家一起把虾养得更轻松、更顺手。