OpenClaw OneBot 11 Channel Plugin

中文 | English

---

中文

源码仓库可在 GitHub 查看。

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

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

说明：

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

功能

• - 🔌 原生通道插件 — 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 消息来源过滤（私聊/群聊/用户级别）
• ✅ 116 个测试用例全部通过
• 📈 覆盖率可通过 npm run coverage 复核

快速开始

1. 安装

CODEBLOCK0

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

2. 配置

在 openclaw.json 中添加：

CODEBLOCK1

说明：

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

也支持环境变量：

CODEBLOCK2

OneBot setup 也支持：

• - INLINECODE31
• 或 INLINECODE32
• 如果 OpenClaw 升级后覆盖了 CLI dist，可在插件目录执行 npm run sync:openclaw-cli 重新同步参数接线

3. 重启 Gateway

CODEBLOCK3

高级配置

CODEBLOCK4

参数	说明
INLINECODE34	消息来源白名单 — private:<QQ号>、group:<群号>、或 *（允许所有）
INLINECODE38

HTTP API 用 Bearer token，WebSocket 用 query 参数 |
| sharedDir | 宿主机共享目录；默认 ~/napcat/shared，用于把语音/图片 stage 给 NapCat |
| containerSharedDir | 容器内共享目录；默认 /shared，与 sharedDir 对应 |
| groupAutoReact | 是否对入站群消息自动添加 reaction，默认 true |
| groupAutoReactEmojiId | 群聊自动 reaction 使用的 QQ emoji id，默认 1 |

Reaction 与流式回复

• - Reaction

- 插件实现了 OpenClaw channel action react - 通过 NapCat set_msg_emoji_like 对群消息或指定群消息 message_id 添加表情 - QQ 私聊 reaction 目前不可靠，接口可能返回成功，但不会真正落到消息上 - 入站群消息还支持自动 reaction，受 groupAutoReact / groupAutoReactEmojiId 控制，默认开启

• - 流式回复

- 这里支持的是 OpenClaw block streaming - QQ 端表现为连续多条分块消息，不是“编辑同一条消息”的 draft stream - 开启方式：

CODEBLOCK5

• - 可选调优：

CODEBLOCK6

验证

• - Reaction

- 先让群里出现一条新消息 - 从 gateway 日志里拿到 msg=<message_id> - 再执行：

CODEBLOCK7

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

• - Streaming

- 在 OpenClaw 配置里开启 agents.defaults.blockStreamingDefault = "on" - 然后在 QQ 里发一条明确要求“分段回复”的消息 - 成功时，QQ 会连续收到多条消息，日志里会出现 deliver(block)，最后再有 INLINECODE56

语音支持（可选）

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

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

依赖：

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

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

消息目标格式

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

开发

CODEBLOCK8

---

English

Source code is available on GitHub.

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

Note:

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

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 OpenClaw text-command passthrough — /status, /help, /commands, /model, /new, /reset, etc.
• 🎤 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)
• ✅ 116 tests passing
• 📈 Coverage can be re-generated with INLINECODE84

Quick Start

1. Install

CODEBLOCK9

INLINECODE85 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.

2. Configure

Add to openclaw.json:

CODEBLOCK10

Notes:

• - Use openclaw-onebot for plugin config keys
• Keep runtime channel config under INLINECODE92
• If you install from a local path or 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:

CODEBLOCK11

OneBot setup also supports:

• - INLINECODE94
• or INLINECODE95
• 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

CODEBLOCK12

Advanced Configuration

CODEBLOCK13

Option	Description
INLINECODE97	Whitelist — private:<qq>, group:<id>, or * (allow all)
INLINECODE101

Bearer token for HTTP, query param for WebSocket |
| sharedDir | Host-side shared directory; defaults to ~/napcat/shared for staging outbound media |
| containerSharedDir | Container-side mount path; defaults to /shared and should map to sharedDir |
| groupAutoReact | Whether to auto-react to inbound group messages; defaults to true |
| groupAutoReactEmojiId | QQ emoji id used for automatic group reactions; defaults to 1 |

Reactions and Streaming Replies

• - Reactions

- The plugin implements the OpenClaw react channel action - It maps to NapCat set_msg_emoji_like - Group-message reactions are supported - QQ private-chat reactions are currently unreliable: the API may return success while no visible reaction is persisted - Inbound group messages can also be auto-reacted, controlled by groupAutoReact / groupAutoReactEmojiId, enabled by default

• - Streaming replies

- This plugin supports OpenClaw block streaming - QQ receives multiple incremental messages instead of a single edited draft message - Enable it with:

CODEBLOCK14

• - Optional coalescing hint for OneBot:

CODEBLOCK15

Verification

• - Reaction

- Send a fresh QQ group message first - Read the inbound msg=<message_id> from the gateway log - Then run:

CODEBLOCK16

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

• - Streaming

- Enable agents.defaults.blockStreamingDefault = "on" in OpenClaw config - Send a QQ prompt that explicitly asks for chunked or stepwise output - Success looks like multiple QQ messages plus deliver(block) entries in the gateway log, followed by INLINECODE118

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:

• - INLINECODE120
• INLINECODE121 (for SILK decoding via pilk; AMR only needs ffmpeg)

Skip these if you only need text and image delivery.

Target Format

• - private:<qq_number> — Private message
• INLINECODE124 — Group message
• INLINECODE125 — Auto-detected as private

Development

CODEBLOCK17

License

MIT