🌊 OpenClaw 接入 QQ 聊天 — 完整实战教程

环境：Windows 10 / PowerShell，OpenClaw 2026.7.1-2（本地模式）
通道：QQ 机器人（官方 OpenAPI + WebSocket 长连接）
插件：@openclaw/qqbot（官方插件）
状态：2026-08-23 实战验证通过 ✅

一、前置条件

• OpenClaw ≥ 2026.5.29（本机 2026.7.1-2，符合）

• 一个 QQ 号（扫码登录开放平台即可）

• OpenClaw gateway 在运行（QQ 是 gateway 通道）

检查 gateway 是否运行：

openclaw gateway status
# 看到 "Runtime: running" 即正常

PowerShell 执行策略需已放开（配飞书时已做）：

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

二、QQ 开放平台创建机器人（需手动操作）

1. 打开 QQ 开放平台：https://q.qq.com

2. 用手机 QQ 扫码登录（个人开发者可注册）

3. 点击 创建机器人，按提示创建

4. 复制凭证：AppID（数字）和 AppSecret

⚠️ AppSecret 只在页面显示一次，离开后看不到，务必当场复制保存。

三、安装插件 ⚠️（关键坑）

必须用官方插件命令，不要用 npm install -g：

openclaw plugins install @openclaw/qqbot

⚠️ 踩坑：用 npm install @openclaw/qqbot -g 后 gateway 报 "no channel plugin installed / no-channel-owner"。改用官方命令装进 OpenClaw 自己的插件目录才加载成功。

四、写入配置（openclaw.json）

在 plugins.entries 添加：

"qqbot": { "enabled": true }

在 channels 添加：

"qqbot": {
  "enabled": true,
  "appId": "1905479713",
  "clientSecret": "***"
}

AppSecret 也可用文件/环境变量方式（更安全）：

"qqbot": {
  "enabled": true,
  "appId": "YOUR_APP_ID",
  "clientSecretFile": "C:/path/qqbot-secret.txt"
  // 或
  // "clientSecret": { "source": "env", "provider": "default", "id": "QQBOT_CLIENT_SECRET" }
}

五、重启 gateway 生效

openclaw gateway restart

六、验证（测试）

1. 手机 QQ 找到机器人，私聊发消息

2. 看日志：openclaw logs --follow

# 正常输出示例：
# [qqbot:default] Gateway ready
# Processing message from XXX: 你好
# [qqbot:api] <<< Status: 200 OK
# Sent markdown chunk (...)(c2c)

私聊发 /bot-me 获取你的 QQ openid（配白名单用）。

七、常用命令（私聊内运行）

八、支持的消息能力

• 私聊(C2C) + 群聊(@提及)：文字、图片、语音、视频、文件 ✅

• 频道消息：仅文字 + 远程 URL 图片（语音/视频/文件/本地图不支持）

• 不支持：表情回应、话题串（threads）

目标格式：

• qqbot:c2c:OPENID — 私聊

• qqbot:group:GROUP_OPENID — 群聊

• qqbot:channel:CHANNEL_ID — 频道

九、常见问题排查