AI > openclaw >

OpenClaw 接入 QQ Bot实践指南

2026-03-09 09:49:00 16Miku

一、概述

本文档记录了在 OpenClaw 平台上接入 QQ Bot 的完整实践过程，包括：

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 机器人」页面

用你的 QQ 扫码登录

点击「创建机器人」

点击创建机器人。

3.3 获取凭证

创建后会提供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
找到添加的机器人
发送消息测试

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

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"
      }
    }
  }
}

九、语音能力配置（可选）

9.1 STT（语音转文字）

在 ~/.openclaw/openclaw.json 中配置：

{
  "channels": {
    "qqbot": {
      "stt": {
        "provider": "your-provider",
        "model": "your-stt-model"
      }
    }
  }
}

9.2 TTS（文字转语音）

{
  "channels": {
    "qqbot": {
      "tts": {
        "provider": "your-provider",
        "model": "your-tts-model",
        "voice": "your-voice"
      }
    }
  }
}

十、升级插件

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 群配置」，仅支持私聊模式。

十三、参考资源

十四、更新日志

日期	版本	更新内容
2026-03-08	v1.0	初始版本

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

到此这篇关于OpenClaw 接入 QQ Bot实践指南的文章就介绍到这了,更多相关OpenClaw 接入 QQ Bot 内容请搜索脚本之家以前的文章或继续浏览下面的相关文章，希望大家以后多多支持脚本之家！