openclaw-channel-qq

QQ 开放平台 Bot 通道插件（OpenClaw Channel Plugin）。

本项目在设计思路和工程结构上参考了 Copaw 相关实践，并结合 OpenClaw 插件机制做了适配与实现。

---

项目简介

openclaw-channel-qq 用于把 QQ 开放平台机器人接入 OpenClaw，实现：

• QQ 侧消息发送（私聊 / 群 / 频道）
• Access Token 获取与缓存
• QQ 网关（WS）连接、心跳、消息事件处理
• 将入站消息路由到 OpenClaw 会话管线

当前实现以稳定可用为目标，适合二次开发与生产前测试。

---

功能特性

• ✅ sendText 出站发送
• ✅ Access Token 自动缓存/续期
• ✅ 网关事件接收（*_MESSAGE_CREATE）
• ✅ 私聊/群聊消息入站路由
• ✅ 引用消息补全（按 message_id 拉取）
• ✅ 富文本/附件抽取与结构化转发
• ✅ 入站去重（短 TTL）
• ✅ 可选原始入站日志落盘（debug）

---

目录结构

openclaw-channel-qq/
├─ src/
│  ├─ auth.ts        # token 获取与缓存
│  ├─ channel.ts     # 核心插件逻辑（出入站、网关）
│  ├─ config.ts      # 配置读取
│  ├─ runtime.ts     # runtime 注入
│  └─ types.ts       # 配置 schema
├─ index.ts
├─ openclaw.plugin.json
├─ package.json
└─ README.md

---

安装与本地开发

npm install
npm run type-check
openclaw plugins install .

---

配置示例

在 OpenClaw 配置中添加：

{
  "channels": {
    "qq": {
      "enabled": true,
      "appId": "YOUR_QQ_APP_ID",
      "clientSecret": "YOUR_QQ_CLIENT_SECRET",
      "apiBase": "https://api.sgroup.qq.com",
      "botPrefix": "[BOT]",
      "debugRawInbound": false,
      "debugRawInboundPath": "./logs/qq-raw-inbound.jsonl"
    }
  }
}

⚠️ 请不要把真实 appId/clientSecret 提交到仓库。

---

目标地址格式

• qq:u_<openid>：C2C 私聊消息
• qq:g_<group_openid>：群消息
• qq:c_<channel_id>：频道消息

---

安全与脱敏说明

为便于公开仓库维护，建议：

• 使用 .env / 外部配置注入密钥
• 禁止提交真实账号、密钥、测试凭据
• 原始消息日志目录加入 .gitignore

---

兼容性

• peerDependencies: openclaw >= 2026.2.13
• Node.js: 建议使用 LTS 版本

---

致谢

• OpenClaw 插件体系
• Copaw（思路参考）

---

License

建议按你的发布策略补充（MIT / Apache-2.0 等）。