OpenClaw QQ Bot接入精选指南

一、概述

在 OpenClaw 上接入 QQ Bot 这个问题，实操中其实容易踩坑。这里把关键步骤和踩过的坑都记下来了，涵盖从账号注册、插件安装到问题排查的完整流程。

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

1.1 功能特性

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

• 多场景支持 - C2C 私聊、群聊 @消息、频道消息、频道私信，覆盖了主要的交互场景
• 富媒体消息 - 图片、语音、视频、文件都能收发
• 定时推送 - 可以设置定时任务主动发消息
• 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 获取凭证

创建完成后，系统会提供 AppID 和 AppSecret。这两个信息是后续配置的关键。

重要：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 安装依赖

执行安装命令后，插件会从 npm 下载并安装依赖：

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: [...]
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 启用插件

同样在配置文件中添加插件相关的条目：

{
  "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），虽然文件复制了，但插件并未被正确注册。

解决方案：

1. 先安装插件：openclaw plugins install @sliverp/qqbot@latest
2. 如果依赖安装失败，手动安装：cd ~/.openclaw/extensions/qqbot && npm install
3. 然后配置 channel：openclaw channels add --channel qqbot --token "你的AppID:你的AppSecret"
4. 最后重启 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 完整配置示例

一个完整的配置文件长这样，包含了飞书和 QQ Bot 两个 channel 的配置：

{
  "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（语音转文字）

如果需要让 Bot 能听懂语音，可以配置语音识别：

{
  "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 群配置」，只支持私聊模式。这点需要留意。

十三、参考资源

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

十四、更新日志

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