首页 > 人工智能 >OpenClaw 接入 QQ Bot 完整实践指南

OpenClaw 接入 QQ Bot 完整实践指南

来源：互联网 2026-03-20 13:24:10

一、概述本文档记录了在 OpenClaw 平台上接入 QQ Bot 的完整实践过程，包括： QQ 开放平台账号注册与机器人创建OpenClaw 插件安装与配置遇到的问题及解决方案最佳实践建议 1.1 功能特性 QQ Bot 插件支持以下功能： 🔒 多场景支持 - C2C 私聊、群聊 @消息、频道消息、频道私信🖼 富媒体消息 - 支持图片、语音、视频、文件收发定时推送 - 支持定时任务主动推送🔗 URL

一、概述

这份文档完整记录了在 OpenClaw 平台接入 QQ 机器人的实战经验，涵盖以下关键环节：

QQ 开放平台账号注册与机器人创建 OpenClaw 插件安装与配置实际遇到的问题及解决方案值得推荐的最佳实践

1.1 功能特性

QQ Bot 插件提供了相当丰富的功能支持：

多场景支持 - C2C 私聊、群聊 @消息、频道消息、频道私信富媒体消息 - 支持图片、语音、视频、文件收发定时推送 - 支持定时任务主动推送 URL 无限制 - 私聊可直接发送 URL 输入状态 - Bot 正在输入中状态提示热更新 - 支持 npm 方式安装和热更新 Markdown - 支持 Markdown 格式

二、前置条件

2.1 环境要求

OpenClaw 已安装并正常运行 Node.js 18+ 环境能够访问 QQ 开放平台（https://open.qq.com）手机 QQ 用于扫码认证

2.2 所需信息

QQ 开放平台账号（需要实名认证） QQ Bot 的 AppID 和 AppSecret

三、QQ 开放平台配置

3.1 注册 QQ 开放平台账号

访问 QQ 开放平台的龙虾专用入口

http://q.qq.com/qqbot/openclaw/login.html

3.2 创建 QQ Bot

进入「QQ 机器人」页面

OpenClaw 接入 QQ Bot 完整实践指南

用你的 QQ 扫码登录

点击「创建机器人」

OpenClaw 接入 QQ Bot 完整实践指南

点击创建机器人。

3.3 获取凭证

OpenClaw 接入 QQ Bot 完整实践指南

创建后会提供qq bot的AppID和AppSecret，用于在OpenClaw中配置。重要：AppSecret 首次查看后无法再次显示，请立即保存

四、OpenClaw 插件安装

4.1 安装 QQ Bot 插件

# 方式一：通过 npm 安装（推荐）
openclaw plugins install @sliverp/qqbot@latest

# 方式二：从源码安装
git clone https://github.com/sliverp/qqbot.git && cd qqbot
openclaw plugins install .

4.2 安装依赖

执行插件安装命令：

openclaw plugins install @sliverp/qqbot@latest

安装过程中可能会出现警告和依赖安装失败：

Downloading @sliverp/qqbot@latest…
Extracting /tmp/openclaw-npm-pack-4j5i0f/sliverp-qqbot-1.5.3.tgz…
WARNING: Plugin "qqbot" contains dangerous code patterns: Environment variable access combined with network send — possible credential harvesting (/tmp/openclaw-plugin-bRKZJH/extract/package/src/gateway.ts:140); Shell command execution detected (child_process) (/tmp/openclaw-plugin-bRKZJH/extract/package/src/utils/audio-convert.ts:565); Shell command execution detected (child_process) (/tmp/openclaw-plugin-bRKZJH/extract/package/src/utils/platform.ts:274); Shell command execution detected (child_process) (/tmp/openclaw-plugin-bRKZJH/extract/package/bin/qqbot-cli.js:109)
Installing to /root/.openclaw/extensions/qqbot…
Installing plugin dependencies…
npm install failed:

如果遇到 npm install failed，需要去插件目录手动安装依赖：

cd ~/.openclaw/extensions/qqbot
npm install

4.3 验证安装

# 查看插件目录
ls -la ~/.openclaw/extensions/qqbot/

# 确认以下文件存在：
# - openclaw.plugin.json
# - package.json
# - node_modules/

五、配置 QQ Bot Channel

5.1 方式一：使用命令行配置（推荐）

openclaw channels add --channel qqbot --token "你的AppID:你的AppSecret"

执行成功后会显示：

Added QQ Bot account "default".

5.2 方式二：手动编辑配置文件

编辑 ~/.openclaw/openclaw.json：

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

5.3 启用插件

在 ~/.openclaw/openclaw.json 中添加：

{
  "plugins": {
    "allow": ["qqbot"],
    "entries": {
      "qqbot": {
        "enabled": true
      }
    },
    "installs": {
      "qqbot": {
        "source": "npm",
        "spec": "@sliverp/qqbot@latest",
        "installPath": "/root/.openclaw/extensions/qqbot",
        "version": "1.5.3"
      }
    }
  }
}

六、启动与验证

6.1 重启 Gateway

openclaw gateway restart

6.2 检查状态

openclaw status

确认 Channels 部分：

│ QQ Bot │ ON│ OK │ configured│

6.3 测试对话

打开手机 QQ 找到添加的机器人发送消息测试

OpenClaw 接入 QQ Bot 完整实践指南

七、遇到的问题及解决方案

7.1 问题一：`openclaw: command not found`

原因：openclaw 命令的软链接不在 PATH 中

解决方案：

ln -sf /usr/lib/node_modules/openclaw/openclaw.mjs /usr/local/bin/openclaw
chmod +x /usr/local/bin/openclaw

7.2 问题二：`Unknown channel: qqbot`

原因：QQ Bot 不是 OpenClaw 内置 channel，需要先安装插件。如果插件安装时依赖失败（npm install failed），虽然插件文件已复制，但未被正确注册，导致 OpenClaw 无法识别 qqbot channel。

解决方案：

先安装插件：openclaw plugins install @sliverp/qqbot@latest 如果依赖安装失败，手动安装：cd ~/.openclaw/extensions/qqbot && npm install 使用命令配置：openclaw channels add --channel qqbot --token "你的AppID:你的AppSecret" 重启 gateway：openclaw gateway restart

7.3 问题三：JSON 配置文件语法错误

错误信息：

JSON5: invalid character '\"' at 198:7

原因：手动编辑 JSON 时，在添加 qqbot 插件安装记录时漏掉了逗号

问题代码：

"installedAt": "2026-03-06T13:49:46.622Z"}← 缺少逗号
"qqbot": {

解决方案：

# 修复语法错误
sed -i '197s/}/},/' /root/.openclaw/openclaw.json

# 验证 JSON 语法
node -e "JSON.parse(require('fs').readFileSync('/root/.openclaw/openclaw.json', 'utf8')); console.log('JSON OK')"

教训：

编辑 JSON 时要确保相邻属性之间有逗号大文件编辑后应该用 node -e "JSON.parse(...)" 验证语法或者编辑后立即执行 openclaw status 检查配置是否有效

7.4 问题四：npm 依赖安装失败

原因：插件安装过程中 npm install 可能失败

解决方案：

cd ~/.openclaw/extensions/qqbot
npm install

八、配置文件参考

8.1 完整配置示例

{
  "channels": {
    "feishu": {
      "appId": "cli_xxx",
      "appSecret": "xxx",
      "enabled": true
    },
    "qqbot": {
      "enabled": true,
      "appId": "你的AppID",
      "clientSecret": "你的AppSecret"
    }
  },
  "plugins": {
    "allow": ["feishu-openclaw-plugin", "qqbot"],
    "entries": {
      "feishu-openclaw-plugin": {
        "enabled": true
      },
      "qqbot": {
        "enabled": true
      }
    },
    "installs": {
      "feishu-openclaw-plugin": {
        "source": "npm",
        "spec": "@larksuiteoapi/feishu-openclaw-plugin",
        "installPath": "/root/.openclaw/extensions/feishu-openclaw-plugin",
        "version": "2026.3.7-beta.1"
      },
      "qqbot": {
        "source": "npm",
        "spec": "@sliverp/qqbot@latest",
        "installPath": "/root/.openclaw/extensions/qqbot",
        "version": "1.5.3"
      }
    }
  }
}

十、升级插件

10.1 使用 openclaw 命令升级

openclaw plugins upgrade @sliverp/qqbot@latest

10.2 使用 npx 升级

npx -y @sliverp/qqbot@latest upgrade

10.3 从源码升级

cd ~/.openclaw/extensions/qqbot
git pull
npm install
openclaw gateway restart

十一、最佳实践

11.1 配置文件管理

修改配置前先备份：cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak 修改后验证语法：node -e "JSON.parse(...)" 使用版本控制管理配置文件

11.2 安全建议

不要将 AppSecret 提交到公开仓库定期轮换 AppSecret 限制测试成员范围

11.3 调试技巧

# 查看 gateway 日志
openclaw logs --follow

# 检查插件状态
openclaw doctor --fix

# 查看运行状态
openclaw status

十二、常见问题 FAQ

Q1: 机器人回复「去火星了」怎么办？

A: 这是因为 OpenClaw 还没有成功连接到 QQ Bot。请检查：

AppID 和 AppSecret 是否正确 Gateway 是否正常运行插件是否正确安装

Q2: 如何添加多个测试用户？

A: 在 QQ 开放平台的「沙箱配置」中添加更多成员。

Q3: 支持群聊吗？

A: QQ 开放平台目前不支持机器人的「在 QQ 群配置」，仅支持私聊模式。

十三、参考资源

OpenClaw 官方文档 QQ Bot 插件 GitHub QQ 开放平台 QQ Bot 开发文档

日期

版本

更新内容

2026-03-08

v1.0

初始版本

文档说明本文档基于 OpenClaw 2026.3.2 和 QQ Bot 插件 1.5.3 版本编写。

侠游戏发布此文仅为了传递信息，不代表侠游戏网站认同其观点或证实其描述

热游推荐

口袋妖怪燃烧绿宝石

Android/ | 角色扮演

2026-03-26

下载
召唤师纷争 0.1折版

Android/ | 战争策略

2026-03-26

下载
寒境庇护所

Android/ | 冒险解谜

2026-03-26

下载
大学助教生活桃子移植

Android/ | 模拟养成

2026-03-26

下载
国潮沙威玛传奇 2026

Android/ | 模拟养成

2026-03-26

下载
全能斗士猫三国

Android/ | 战争策略

2026-03-26

下载
幽幽奇遇

Android/ | 休闲益智

2026-03-26

下载
海蛇传奇

Android/ | 角色扮演

2026-03-26

下载

精彩专题

手游专题攻略 App下载 web3

本站为非盈利网站，不接受任何广告。本站所有软件，都由网友: 上传，如有侵犯你的版权，请发邮件给xiayx666@163.com

抵制不良色情、反动、暴力游戏。注意自我保护，谨防受骗上当。: 适度游戏益脑，沉迷游戏伤身。合理安排时间，享受健康生活。

OpenClaw 接入 QQ Bot 完整实践指南

一、概述

1.1 功能特性

二、前置条件

2.1 环境要求

2.2 所需信息

三、QQ 开放平台配置

3.1 注册 QQ 开放平台账号

3.2 创建 QQ Bot

3.3 获取凭证

四、OpenClaw 插件安装

4.1 安装 QQ Bot 插件

4.2 安装依赖

4.3 验证安装

五、配置 QQ Bot Channel

5.1 方式一：使用命令行配置（推荐）

5.2 方式二：手动编辑配置文件

5.3 启用插件

六、启动与验证

6.1 重启 Gateway

6.2 检查状态

6.3 测试对话

七、遇到的问题及解决方案

7.1 问题一：openclaw: command not found

7.2 问题二：Unknown channel: qqbot

7.3 问题三：JSON 配置文件语法错误

7.4 问题四：npm 依赖安装失败

八、配置文件参考

8.1 完整配置示例

十、升级插件

10.1 使用 openclaw 命令升级

10.2 使用 npx 升级

10.3 从源码升级

十一、最佳实践

11.1 配置文件管理

11.2 安全建议

11.3 调试技巧

十二、常见问题 FAQ

Q1: 机器人回复「去火星了」怎么办？

Q2: 如何添加多个测试用户？

Q3: 支持群聊吗？

十三、参考资源

日期 版本 更新内容 2026-03-08 v1.0 初始版本 文档说明 本文档基于 OpenClaw 2026.3.2 和 QQ Bot 插件 1.5.3 版本编写。

相关攻略

同类更新

热游推荐

精彩专题

7.1 问题一：`openclaw: command not found`

7.2 问题二：`Unknown channel: qqbot`

日期

版本

更新内容

2026-03-08

v1.0

初始版本

文档说明本文档基于 OpenClaw 2026.3.2 和 QQ Bot 插件 1.5.3 版本编写。