OpenClaw QQ（非机器人）插件 v0.5.0 发布：支持全媒体消息与精细化权限控制

OpenClaw QQ（非机器人）插件 v0.5.0 发布：支持全媒体消息与精细化权限控制

1. 简介

OpenClaw QQ 频道插件 (@izhimu/qq) 是一个基于 OpenClaw 框架的高性能插件。它通过 NapCat WebSocket API 与 QQ 机器人建立连接，完美支持私聊、群聊，并具备强大的消息处理与分发能力。

在最新的 v0.5.0 版本中，我们引入了多项重量级特性，包括视频文件消息支持、精细化的黑白名单控制以及更灵活的群组响应配置，让你的机器人更加智能且安全。

---

2. v0.5.0 新特性概览

• 📺 全媒体支持增强：新增对 视频 (video) 消息类型的接收支持，现在你可以更全面地感知聊天动态。
• 🛡️ 精细化访问控制：
  • 引入 messageDirect (私聊) 和 messageGroup (群聊) 独立配置项。
  • 支持三种策略模式：allow (全部允许), deny (全部拒绝), allowlist (白名单模式)。
  • 支持基于 QQ 号/群号 的黑白名单精准过滤。
• 🎯 群组触发器升级：
  • 唤醒词 (wakeWord)：自定义机器人在群聊中的唤醒词，不再仅仅依赖 @。
  • 戳一戳 (requirePoke)：支持开启/关闭“戳一戳”响应，增加互动趣味性。
  • 独立群配置 (messageGroupsCustom)：支持针对不同群组设置完全不同的响应逻辑。
• 📝 Markdown 优化：新增 markdownFormat 开关，可自由选择是否将 Markdown 转换为纯文本，提升移动端适配体验。
• 🏗️ 架构重构：配置解析逻辑更健壮，适应更复杂的生产部署环境。

---

3. 安装步骤

前提条件

1. 已安装 OpenClaw (版本 >= 2026.2.1)。
2. 已部署 NapCat QQ 并开启 WebSocket 服务。

通过 OpenClaw CLI 一键安装

这是最推荐的安装方式，简单高效：

# 安装插件
openclaw plugins install @izhimu/qq

# 如果已有旧版本，执行更新
openclaw plugins update qq

---

4. 配置指南

在 0.5.0 版本中，你可以通过交互式向导或手动编辑 config.json 进行配置。

4.1 交互式配置

运行以下命令，按照提示输入 WebSocket 地址 and Token 即可完成基础设置：

openclaw onboard

4.2 进阶配置示例

以下是一个典型的配置片段，展示了新版本的权限控制与群组特性：

{
  "channels": {
    "qq": {
      "wsUrl": "ws://127.0.0.1:3001",
      "accessToken": "your_token",
      "enabled": true,
      "markdownFormat": true,
      "messageDirect": {
        "policy": "allow",
        "denyFrom": ["12345678"] // 屏蔽特定用户
      },
      "messageGroup": {
        "policy": "allowlist",
        "allowFrom": ["88888888"], // 仅允许在特定群运行
        "requireMention": true,     // 必须 @ 机器人才响应
        "requirePoke": true,        // 开启戳一戳响应
        "wakeWord": "小艺"           // 自定义唤醒词
      }
    }
  }
}

4.3 配置界面参考

---

5. 功能演示

新版本在处理富媒体消息和交互体验上做了深度优化，以下是实际运行效果：

5.1 基础对话与响应

5.2 群聊 @ 与 唤醒

精准识别 @ 消息，配合自定义唤醒词，让机器人更具个性化。

---

6. 常用命令速查

操作	命令示例
发送私聊	openclaw message send "你好" --to qq:private:12345
发送群聊	openclaw message send "开会了" --to qq:group:67890
查看状态	openclaw channels
查看日志	openclaw logs --channel qq

---

7. 故障排查

1. 连接失败：请检查 NapCat 的 WebSocket 服务是否正常运行，并确保防火墙已放行对应端口（默认 3001）。
2. 不响应消息：
   • 检查配置中的 enabled 是否为 true。
   • 检查 messageGroup 或 messageDirect 中的 policy 是否拦截了当前用户/群组。
   • 如果开启了 requireMention，请确保消息中确实 @ 了机器人或使用了 wakeWord。

---

资源链接

• 项目地址：GitHub - openclaw-channel-qq

欢迎在 GitHub 提交 Issue 或 Pull Request，一起完善 OpenClaw 生态！如果觉得好用，记得点个 ⭐️ Star 哦！