部署OpenClaw整合QQ机器人

小坏说Java

890人浏览 · 2026-03-23 09:52:09

小坏说Java · 2026-03-23 09:52:09 发布

一、前期准备

部署OpenClaw服务
确保OpenClaw已在服务器或本地环境正常运行
验证服务状态：执行 openclaw gateway status显示 running
确保18789端口已开放（云服务器需在安全组中配置）
准备QQ账号
需要一个正常使用的QQ号，已绑定手机号并完成实名认证
一个QQ账号最多可创建5个独立的QQ机器人
获取公网IP（服务器部署需要）
本地部署用户注意：QQ开放平台采用主动拉取模式，OpenClaw会主动连接QQ服务器获取消息，本地部署也可以稳定运行
二、QQ开放平台配置
注册QQ开放平台
访问QQ开放平台官网：https://q.qq.com/qqbot/openclaw/login.html
使用手机QQ扫码登录（扫码的QQ号必须绑定输入的那个手机号）
首次使用需要完成开发者认证，通过人脸识别后即可入驻
创建QQ机器人
登录成功后，点击页面上的"创建机器人"按钮
填写机器人信息：
名称：4-30个字符（1个中文字=2个字符），需先检测名称可用性
头像：上传png/bmp/jpeg/jpg格式图片，240×240px以上，无政治敏感与色情内容
描述：限120个字
点击"确认"完成创建
获取核心凭证
创建完成后，进入机器人"开发管理"页面
复制保存以下信息：
AppID：机器人的唯一标识
AppSecret：机器人密钥（仅显示一次，必须立即复制保存！）
Token：格式为"AppID:AppSecret"
⚠️ 重要提醒：AppSecret不支持明文保存，如果忘记需要重新生成，原来的密钥会立即失效
配置IP白名单
在"开发管理"页面找到"IP白名单"选项
输入你的服务器公网IP地址
点击"保存"（提示"提审及上线前IP白名单不可为空"直接确认即可）
注意：未配置IP白名单会导致机器人提示"该机器人去火星了，稍后再试吧"
沙箱配置（测试环境）
进入"沙箱配置"页面
选择配置类型（2026年1月31日后仅支持单独聊天配置）：
选择"在消息列表配置"（单独聊天场景）
点击"添加成员"，设置成员角色（管理员/普通成员）
添加后使用该成员的QQ扫码确认添加机器人
扫码成功后，该成员的QQ消息列表中将出现该机器人节点
三、OpenClaw端配置
安装QQBot插件（三种方式）
方式一：远程一键安装（推荐）

首次安装，需提供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服务

方式二：源码安装

拉取仓库

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

方式三：npm方式手动安装

（首次安装可跳过）卸载旧插件

openclaw plugins uninstall qqbot
openclaw plugins uninstall openclaw-qqbot

安装openclaw-qqbot最新版本

openclaw plugins install @tencent-connect/openclaw-qqbot@latest

如果安装失败，可能是镜像问题，可以用国内源重试

npm config set registry https://registry.npmmirror.com
openclaw plugins install @sliverp/qqbot@latest --registry=https://registry.npmmirror.com
2. 验证插件安装

查看已安装插件列表

openclaw plugins list | grep openclaw-qqbot

正常应显示 “qqbot | loaded” 或 “openclaw-qqbot | loaded”

绑定QQ机器人

将 AppID:AppSecret 替换成你刚刚保存的凭证

openclaw channels add --channel qqbot --token “1234567890:ABCDefGHIjklMNOPqrsTUVwxyz”
命令格式说明：–token的值是AppID:AppSecret的拼接，中间用英文冒号隔开

配置凭证（可选配置文件方式）
如果需要在配置文件中直接配置，可以在 ~/.openclaw/openclaw.json中添加：

{
“channels”: {
“qqbot”: {
“enabled”: true,
“appId”: “你的AppID”,
“clientSecret”: “你的AppSecret”
}
}
}
安全提示：建议通过命令行参数配置，避免在配置文件中明文存储凭证

重启网关使配置生效

重启网关

openclaw gateway restart

确认网关状态正常

openclaw gateway status
6. 验证通道状态

查看通道状态

openclaw channels status

正常应显示 “QQ Bot 通道显示为 enabled, configured, running”

且机器人实际可以正常收发消息或 in/out 时间持续更新

四、测试验证

在QQ中找到机器人
打开手机QQ，在搜索框输入你创建的机器人名称（或QQ号）
点击进入对话界面
发送测试消息
向机器人发送一条消息进行测试
如果机器人能正常回复，说明QQ渠道接入成功
注意：首次对话可能需要等待几秒钟进行初始化
五、常见问题排查
机器人没有响应？
检查以下项目：

IP白名单是否正确配置
AppID和AppSecret是否正确
是否在沙箱配置中添加了测试账号
Gateway服务是否正常运行
2. 提示"该机器人去火星了"？
通常为IP白名单配置错误
检查服务器公网IP是否正确添加到QQ开放平台的IP白名单中
3. 如何更新机器人凭证？

先移除旧频道

openclaw channels remove --channel qqbot

重新添加新凭证

openclaw channels add --channel qqbot --token “新AppID:新AppSecret”

重启服务

openclaw gateway restart
4. 如何完整卸载QQ机器人功能？

停止并移除频道

openclaw channels remove --channel qqbot

卸载插件

openclaw plugins uninstall openclaw-qqbot

如果卸载中显示qqbot通道没有被删除，就在配置文件中把qqbot配置进行手动删除

vim ~/.openclaw/openclaw.json

重启服务

openclaw gateway restart
六、功能特性
支持的消息类型
QQBot插件提供了富媒体收发支持，覆盖图片、语音、视频、文件的双向交互。除了接收日常的文本消息以外，QQBot通道还支持接收多种媒体消息。

注意事项
群聊限制：目前QQ机器人主要支持单聊场景，群聊功能可能受限。2026年1月31日后QQ开放平台暂不支持QQ群配置，仅支持单独聊天配置。
插件角色：QQ Bot插件仅作为消息通道使用——负责在QQ与OpenClaw之间中转消息。诸如图像理解、语音转录、绘图等功能，取决于用户所配置的AI模型以及OpenClaw内部已安装的技能。
上线正式环境：沙箱测试通过后，需要提交审核。审核通过后即可正式上线使用。
七、简化方案：Qclaw
如果觉得OpenClaw配置复杂，腾讯推出了Qclaw，提供一键部署和深度整合微信/QQ，更适合普通用户。