OpenClaw部署整合QQ机器人实操

根据最新的官方文档和社区教程，以下是OpenClaw配置QQ机器人的详细步骤，涵盖从前期准备到最终测试的完整流程。

一、前期准备

1. 部署OpenClaw服务

确保OpenClaw已在服务器或本地环境正常运行
验证服务状态：执行 openclaw gateway status显示 running
确保18789端口已开放（云服务器需在安全组中配置）

2. 准备QQ账号

需要一个正常使用的QQ号，已绑定手机号并完成实名认证
一个QQ账号最多可创建5个独立的QQ机器人

3. 获取公网IP（服务器部署需要）

本地部署用户注意：QQ开放平台采用主动拉取模式，OpenClaw会主动连接QQ服务器获取消息，本地部署也可以稳定运行

二、QQ开放平台配置

1. 注册QQ开放平台

访问QQ开放平台官网：https://q.qq.com/qqbot/openclaw/login.html
使用手机QQ扫码登录（扫码的QQ号必须绑定输入的那个手机号）
首次使用需要完成开发者认证，通过人脸识别后即可入驻

2. 创建QQ机器人

登录成功后，点击页面上的"创建机器人"按钮
填写机器人信息：

名称：4-30个字符（1个中文字=2个字符），需先检测名称可用性
头像：上传png/bmp/jpeg/jpg格式图片，240×240px以上，无政治敏感与色情内容
描述：限120个字

点击"确认"完成创建

3. 获取核心凭证

创建完成后，进入机器人"开发管理"页面
复制保存以下信息：

AppID：机器人的唯一标识
AppSecret：机器人密钥（仅显示一次，必须立即复制保存！）
Token：格式为"AppID:AppSecret"

⚠️ 重要提醒：AppSecret不支持明文保存，如果忘记需要重新生成，原来的密钥会立即失效

4. 配置IP白名单

在"开发管理"页面找到"IP白名单"选项
输入你的服务器公网IP地址
点击"保存"（提示"提审及上线前IP白名单不可为空"直接确认即可）
注意：未配置IP白名单会导致机器人提示"该机器人去火星了，稍后再试吧"

5. 沙箱配置（测试环境）

进入"沙箱配置"页面
选择配置类型（2026年1月31日后仅支持单独聊天配置）：

选择"在消息列表配置"（单独聊天场景）

点击"添加成员"，设置成员角色（管理员/普通成员）
添加后使用该成员的QQ扫码确认添加机器人
扫码成功后，该成员的QQ消息列表中将出现该机器人节点

三、OpenClaw端配置

1. 安装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.gitcd openclaw-qqbot# 通过本地脚本进行源码安装bash ./scripts/upgrade-via-source.sh --appid YOUR_APPID --secret YOUR_SECRET

脚本执行到后面会让选择是否后台重启openclaw网关服务？[Y/n]，一般选择Y

方式三：npm方式手动安装

# （首次安装可跳过）卸载旧插件openclaw plugins uninstall qqbotopenclaw plugins uninstall openclaw-qqbot# 安装openclaw-qqbot最新版本openclaw plugins install @tencent-connect/openclaw-qqbot@latest# 如果安装失败，可能是镜像问题，可以用国内源重试npm config set registry https://registry.npmmirror.comopenclaw plugins install @sliverp/qqbot@latest --registry=https://registry.npmmirror.com

2. 验证插件安装

# 查看已安装插件列表openclaw plugins list | grep openclaw-qqbot# 正常应显示 "qqbot | loaded" 或 "openclaw-qqbot | loaded"

3. 绑定QQ机器人

# 将 AppID:AppSecret 替换成你刚刚保存的凭证openclaw channels add --channel qqbot --token "1234567890:ABCDefGHIjklMNOPqrsTUVwxyz"

命令格式说明：--token的值是AppID:AppSecret的拼接，中间用英文冒号隔开

4. 配置凭证（可选配置文件方式）

如果需要在配置文件中直接配置，可以在 ~/.openclaw/openclaw.json中添加：

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

安全提示：建议通过命令行参数配置，避免在配置文件中明文存储凭证

5. 重启网关使配置生效

# 重启网关openclaw gateway restart# 确认网关状态正常openclaw gateway status

6. 验证通道状态

# 查看通道状态openclaw channels status# 正常应显示 "QQ Bot 通道显示为 enabled, configured, running"# 且机器人实际可以正常收发消息或 in/out 时间持续更新

四、测试验证

1. 在QQ中找到机器人

打开手机QQ，在搜索框输入你创建的机器人名称（或QQ号）
点击进入对话界面

2. 发送测试消息

向机器人发送一条消息进行测试
如果机器人能正常回复，说明QQ渠道接入成功
注意：首次对话可能需要等待几秒钟进行初始化

五、常见问题排查

1. 机器人没有响应？

检查以下项目：

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，更适合普通用户。

按照以上步骤操作，通常可以在5-10分钟内完成OpenClaw QQ机器人的配置。如果遇到问题，可以参考官方文档或社区教程进行排查。