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 完整配置示例
• 九、语音能力配置（可选）
• 9.1 STT（语音转文字）
• 9.2 TTS（文字转语音）
• 十、升级插件
• 10.1 使用 openclaw 命令升级
• 10.2 使用 npx 升级
• 10.3 从源码升级
• 十一、最佳实践
• 11.1 配置文件管理
• 11.2 安全建议
• 11.3 调试技巧
• 十二、常见问题 FAQ
• Q1: 机器人回复「去火星了」怎么办？
• Q2: 如何添加多个测试用户？
• Q3: 支持群聊吗？
• 十三、参考资源
• 十四、更新日志

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

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

QQ Bot 插件支持以下功能：

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

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

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

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

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

1. 进入「QQ 机器人」页面

用你的 QQ 扫码登录

1. 点击「创建机器人」

点击创建机器人。

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

# 方式一：通过 npm 安装（推荐）
openclaw plugins install @sliverp/qqbot@latest
# 方式二：从源码安装
git clone https://github.com/sliverp/qqbot.git && cd qqbot
openclaw plugins install .

执行插件安装命令：

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

# 查看插件目录
ls -la ~/.openclaw/extensions/qqbot/
# 确认以下文件存在：
# - openclaw.plugin.json
# - package.json
# - node_modules/

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

执行成功后会显示：

Added QQ Bot account "default".

编辑 ~/.openclaw/openclaw.json：

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

在 ~/.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"
      }
    }
  }
}

openclaw gateway restart

openclaw status

确认 Channels 部分：

│ QQ Bot │ ON      │ OK     │ configured            │

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

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

解决方案：

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

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

解决方案：

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

错误信息：

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 检查配置是否有效

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

解决方案：

cd ~/.openclaw/extensions/qqbot
npm install

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

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

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

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

openclaw plugins upgrade @sliverp/qqbot@latest

npx -y @sliverp/qqbot@latest upgrade

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

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

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

# 查看 gateway 日志
openclaw logs --follow
# 检查插件状态
openclaw doctor --fix
# 查看运行状态
openclaw status

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

1. AppID 和 AppSecret 是否正确
2. Gateway 是否正常运行
3. 插件是否正确安装

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

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

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

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

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

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