@ssfxx44533/onebot-qq

OpenClaw 原生 ChannelPlugin，直接把 NapCat / OneBot QQ 接到 OpenClaw。

设计目标：

• 不再做独立 bridge + main + cron 的拼装服务
• 不在接入层持有模型 API token
• QQ 入站消息直接进入 OpenClaw 原生 session / reply pipeline
• 出站统一走 OpenClaw channel 能力，支持文本、图片、音频、视频、文件

当前范围

已实现：

• NapCat WebSocket 长连接与自动重连（指数退避重连）
• QQ 私聊入站
• QQ 群聊入站，默认要求 @机器人
• OpenClaw 原生 session 路由与自动回复分发
• DM pairing 审批流
• 入站图片 / 音频 / 视频自动缓存到本地媒体目录
• 入站文件附件元数据提取（file / onlinefile）
• 文本回复（超长自动分块，默认 1200 字）
• 图片 / 音频 / 视频消息发送
• 普通文件上传
• 基础 allowFrom / groupAllowFrom / dmPolicy / groupPolicy
• per-group requireMention / systemPrompt / allowFrom

暂未实现：

• OneBot 反向 HTTP webhook 模式
• 多账号复杂编排

安装

本地开发链接：

openclaw plugins install -l /root/openclaw-onebot-qq
openclaw plugins enable onebot-qq
openclaw gateway restart

后续发布到 npm 后：

openclaw plugins install @ssfxx44533/onebot-qq
openclaw plugins enable onebot-qq
openclaw gateway restart

配置

最小配置：

{
  channels: {
    "onebot-qq": {
      enabled: true,
      wsUrl: "ws://localhost:3001/?access_token=napcat_ws"
    }
  },
  plugins: {
    entries: {
      "onebot-qq": {
        enabled: true
      }
    }
  }
}

常用配置：

{
  channels: {
    "onebot-qq": {
      enabled: true,
      wsUrl: "ws://localhost:3001/?access_token=napcat_ws",
      selfId: "3546821676",
      requireMention: true,
      dmPolicy: "pairing",
      mediaMaxMb: 20,
      groupPolicy: "open",
      allowFrom: ["123456789"],
      groupAllowFrom: ["123456789"],
      groups: {
        "987654321": {
          requireMention: true,
          systemPrompt: "这是内部群，优先简洁回复。"
        }
      }
    }
  }
}

出站目标格式

• 私聊：直接填 QQ 号，例如 123456789
• 私聊：也可以用 qq:123456789 或 private:123456789
• 群聊：用 group:987654321

开发检查

cd /root/openclaw-onebot-qq
npm test
npm run check

兼容性说明

当前 OpenClaw 插件安装器只会对插件 package.json 里的 dependencies 执行隔离目录内的 npm install。因此本插件显式声明了 openclaw 运行时依赖，避免首次安装后出现 Cannot find module 'openclaw/plugin-sdk/... 这类宿主 SDK 解析失败。