OpenClaw OneBot 11 Channel Plugin 🐧

中文 | English

中文

OpenClaw 的 OneBot 11 协议通道插件，让 QQ 成为 OpenClaw 一等消息通道。

支持 NapCat、go-cqhttp 等所有兼容 OneBot 11 协议的 QQ 机器人框架。

说明：

• 插件 id 是 openclaw-onebot
• 通道 id 仍然是 onebot
• 因此 plugins.allow / plugins.entries / plugins.installs 使用 openclaw-onebot
• channels.onebot 保持不变
• 当前版本对齐 OpenClaw 2026.4.9 / plugin-sdk 2026.4.9，并声明 setupEntry

功能

• 🔌 原生通道插件 — QQ 与 Discord / Telegram / WhatsApp 同级
• 📨 私聊和群聊收发消息
• 😀 Reaction 支持（群聊） — 通过 NapCat set_msg_emoji_like 给群消息加表情回应；QQ 私聊目前不稳定/通常不生效
• 👍 群聊自动 reaction — 对入站群消息自动点表情，可配置开关，默认开启
• 🌊 Block streaming — 支持 OpenClaw 分块回复，QQ 端会连续收到多条流式消息
• 🧭 OpenClaw 文本命令全支持 — /status、/help、/commands、/model、/new、/reset 等命令走统一文本命令链路
• 🎤 语音完整链路 — QQ 语音 (SILK/AMR) → MP3 → STT → TTS → 发送 QQ 语音
• 📦 消息聚合 — 连续多条消息 1.5s 内自动合并（类似 Telegram 风格）
• 🖼️ 图片、语音、文件附件发送
• 🔄 WebSocket 自动重连（指数退避）
• 🔒 可选 access token 鉴权
• 🎯 allowFrom 消息来源过滤（私聊/群聊/用户级别）
• ✅ 112 个测试用例全部通过
• 📈 覆盖率：Statements/Lines 91.97%，Branches 83.37%，Functions 95.00%；gateway.ts Statements/Lines 86.14%

与其他方案对比

核心区别：本项目是 OpenClaw 原生通道插件，安装后 QQ 就和 Discord / Telegram 一样使用，不需要额外的桥接脚本或消息队列。其他方案都是外挂式的独立进程，需要自己处理消息路由和会话管理。

架构

QQ 机器人框架 (NapCat / go-cqhttp)
  ├── WebSocket → 接收消息 (含语音 SILK/AMR 自动转 MP3)
  └── HTTP API  → 发送消息 (文字/图片/语音)
      ↕
OpenClaw OneBot Plugin (ChannelPlugin)
  ├── 消息聚合 (1.5s debounce)
  ├── 语音处理 (SILK → pilk → PCM → ffmpeg → MP3)
  └── allowFrom 过滤
      ↕
OpenClaw Gateway (统一消息管线)
  ├── STT (语音转文字)
  ├── Agent 对话
  ├── Block streaming (多段消息回复)
  ├── Reaction action
  └── TTS (文字转语音) → sendRecord → QQ 语音

快速开始

1. 安装插件

# 自动安装
bash scripts/install.sh

# 或手动（先在仓库根目录准备发布包）
npm install && npm run prepare:clawhub:plugin
mkdir -p ~/.openclaw/plugins/onebot
cp -r .clawhub-plugin/openclaw-onebot-plugin/* ~/.openclaw/plugins/onebot/
cd ~/.openclaw/plugins/onebot && npm install --omit=dev --omit=peer --no-package-lock --no-audit --no-fund

scripts/install.sh 会先在源码仓库生成 .clawhub-plugin/openclaw-onebot-plugin 精简发布包，再把这份运行时 payload 安装到 OpenClaw 目录，并自动尝试执行 scripts/sync-openclaw-cli.mjs，把 --shared-dir / --container-shared-dir 接到本机 OpenClaw CLI。

2. 配置

在 openclaw.json 中添加：

{
  "plugins": {
    "allow": ["openclaw-onebot"],
    "entries": {
      "openclaw-onebot": {
        "enabled": true
      }
    }
  },
  "channels": {
    "onebot": {
      "enabled": true,
      "wsUrl": "ws://your-host:3001",
      "httpUrl": "http://your-host:3001",
      "accessToken": "your_token",
      "sharedDir": "/Users/you/napcat/shared",
      "containerSharedDir": "/shared",
      "groupAutoReact": true,
      "groupAutoReactEmojiId": 1
    }
  }
}

说明：

• 插件配置键使用 openclaw-onebot
• 通道配置键使用 channels.onebot
• 如果你是通过本地路径/扩展目录安装插件，通常还需要在 plugins.installs.openclaw-onebot 中指向实际安装目录；如果用 OpenClaw 自己的插件安装流程，这一项会自动生成

也支持环境变量：

ONEBOT_WS_URL=ws://your-host:3001
ONEBOT_HTTP_URL=http://your-host:3001
ONEBOT_ACCESS_TOKEN=your_token  # 可选

OneBot setup 也支持：

• --token wsUrl,httpUrl[,accessToken[,sharedDir[,containerSharedDir]]]
• 或 openclaw channels add --channel onebot --shared-dir <hostPath> --container-shared-dir /shared
• 如果 OpenClaw 升级后覆盖了 CLI dist，可在插件目录执行 npm run sync:openclaw-cli 重新同步参数接线

3. 重启 Gateway

openclaw gateway restart

高级配置

{
  "channels": {
    "onebot": {
      "enabled": true,
      "wsUrl": "ws://your-host:3001",
      "httpUrl": "http://your-host:3001",
      "accessToken": "your_token",
      "sharedDir": "/Users/you/napcat/shared",
      "containerSharedDir": "/shared",
      "allowFrom": ["private:12345", "group:67890"],
      "groupAutoReact": true,
      "groupAutoReactEmojiId": 1
    }
  }
}

Reaction 与流式回复

• Reaction
• 流式回复

{
  "agents": {
    "defaults": {
      "blockStreamingDefault": "on"
    }
  }
}

• 可选调优：

{
  "channels": {
    "onebot": {
      "blockStreamingCoalesce": {
        "minChars": 80,
        "idleMs": 600
      }
    }
  }
}

验证

• Reaction

npm run build
npm run react-test -- --message-id <message_id> --emoji 76

• 当前建议只把这项验证用于群聊消息；私聊 reaction 在 QQ/NapCat 上通常不生效

• Streaming

语音支持（可选）

支持 QQ 语音消息的完整自动处理链路：

• 入站：QQ 语音 (SILK/AMR) → 下载 → 转 MP3 → OpenClaw STT 转文字 → Agent 生成回复
• 出站：Agent 回复 → TTS 生成音频 → sendRecord 发送 QQ 语音

依赖：

• ffmpeg — 音频格式转换
• uv — 运行 pilk 解码 SILK 格式（AMR 仅需 ffmpeg）

不需要语音功能时可以跳过这些依赖。

消息目标格式

• private:<QQ号> — 私聊消息
• group:<群号> — 群聊消息
• <QQ号> — 自动识别为私聊

NapCat 部署参考

推荐使用 Docker 部署 NapCat：

# docker-compose.yml
services:
  napcat:
    image: mlikiowa/napcat-docker:latest
    restart: always
    ports:
      - "3001:3001"   # OneBot 11 WS + HTTP
      - "6099:6099"   # WebUI
    volumes:
      - ./napcat-data:/app/.config/QQ
      - ./shared:/shared   # 文件共享目录

开发

npm install
npm test          # 112 tests
npm run build     # 编译 TypeScript
npm run coverage  # 覆盖率报告（`gateway.ts` lines/statements 86.14%）
npm run sync:openclaw-cli  # 重新同步 OpenClaw CLI 的 shared-dir 参数

English

An OpenClaw native channel plugin that connects to NapCat, go-cqhttp, or any OneBot 11 compatible QQ bot framework.

Note:

• Plugin id: openclaw-onebot
• Channel id: onebot
• Use openclaw-onebot in plugins.allow / plugins.entries / plugins.installs
• Keep channels.onebot unchanged
• This release targets OpenClaw 2026.4.9 / plugin-sdk 2026.4.9 and declares setupEntry

Features

• 🔌 Native channel plugin — QQ on par with Discord / Telegram / WhatsApp
• 📨 Private & group chat (inbound + outbound)
• 😀 Reaction support (groups) — react to a QQ group message via NapCat set_msg_emoji_like; QQ private-chat reactions are currently unreliable
• 👍 Automatic group reactions — auto-react to inbound group messages with a configurable switch, enabled by default
• 🌊 Block streaming — OpenClaw partial replies arrive as multiple QQ messages
• 🎤 Full voice pipeline — QQ voice (SILK/AMR) → MP3 → STT → TTS → send QQ voice
• 📦 Message batching — auto-merge rapid messages within 1.5s (Telegram-style)
• 🖼️ Image, audio, and file attachments
• 🔄 WebSocket auto-reconnect with exponential backoff
• 🔒 Optional access token authentication
• 🎯 allowFrom filtering (private/group/user-level)
• 🧭 Full OpenClaw text-command passthrough (/status, /help, /commands, /model, /new, /reset, etc.)
• ✅ 112 tests passing
• 📈 Coverage: Statements/Lines 91.97%, Branches 83.37%, Functions 95.00%; gateway.ts Statements/Lines 86.14%

Comparison with Alternatives

Key difference: This is a native OpenClaw channel plugin — once installed, QQ works just like Discord or Telegram. No bridge scripts, no message queues, no extra processes.

Quick Start

1. Install

# Auto install
bash scripts/install.sh

# Or manual (prepare the release payload from the repo root first)
npm install && npm run prepare:clawhub:plugin
mkdir -p ~/.openclaw/plugins/onebot
cp -r .clawhub-plugin/openclaw-onebot-plugin/* ~/.openclaw/plugins/onebot/
cd ~/.openclaw/plugins/onebot && npm install --omit=dev --omit=peer --no-package-lock --no-audit --no-fund

scripts/install.sh prepares .clawhub-plugin/openclaw-onebot-plugin in the source repo first, installs that trimmed runtime payload, and then runs scripts/sync-openclaw-cli.mjs so the local OpenClaw CLI keeps the OneBot --shared-dir / --container-shared-dir flags wired in after install.

2. Configure

Add to openclaw.json:

{
  "plugins": {
    "allow": ["openclaw-onebot"],
    "entries": {
      "openclaw-onebot": {
        "enabled": true
      }
    }
  },
  "channels": {
    "onebot": {
      "enabled": true,
      "wsUrl": "ws://your-host:3001",
      "httpUrl": "http://your-host:3001",
      "groupAutoReact": true,
      "groupAutoReactEmojiId": 1
    }
  }
}

Notes:

• Use openclaw-onebot for plugin config keys
• Keep runtime channel config under channels.onebot
• If you install from a local path / extension directory, you may also need plugins.installs.openclaw-onebot pointing at the actual install directory; OpenClaw usually writes this automatically during plugin install

Or via environment variables:

ONEBOT_WS_URL=ws://your-host:3001
ONEBOT_HTTP_URL=http://your-host:3001
ONEBOT_ACCESS_TOKEN=your_token  # optional

OneBot setup also supports:

• --token wsUrl,httpUrl[,accessToken[,sharedDir[,containerSharedDir]]]
• or openclaw channels add --channel onebot --shared-dir <hostPath> --container-shared-dir /shared
• if an OpenClaw upgrade overwrites the installed CLI dist, run npm run sync:openclaw-cli from the plugin directory to re-apply the flags

3. Restart Gateway

openclaw gateway restart

Voice Support (Optional)

End-to-end voice flow:

• Inbound: QQ voice (SILK/AMR) → download → MP3 → OpenClaw STT → Agent reply
• Outbound: Agent reply → TTS audio → sendRecord → QQ voice

Dependencies: ffmpeg + uv (for SILK decoding via pilk). Skip if text/image only.

Reactions and Streaming Replies

• Reactions
• Streaming replies

{
  "agents": {
    "defaults": {
      "blockStreamingDefault": "on"
    }
  }
}

• Optional coalescing hint for OneBot:

{
  "channels": {
    "onebot": {
      "blockStreamingCoalesce": {
        "minChars": 80,
        "idleMs": 600
      }
    }
  }
}

Verification

• Reaction

npm run build
npm run react-test -- --message-id <message_id> --emoji 76

• For now, treat this as a group-chat verification flow; private-chat reactions are not a reliable capability

• Streaming

Configuration

Target Format

• private:<qq_number> — Private message
• group:<group_id> — Group message
• <qq_number> — Auto-detected as private

Development

npm install
npm test          # Run 112 tests
npm run build     # Compile TypeScript
npm run coverage  # Coverage report (`gateway.ts` lines/statements 86.14%)
npm run sync:openclaw-cli  # Re-apply shared-dir CLI wiring after OpenClaw upgrades

License

MIT