OpenClaw OneBot 11 Channel Plugin 🐧

中文 | English

中文

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

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

说明：

npm 包名是 openclaw-onebot
ClawHub package payload 包名是 openclaw-onebot-plugin
插件 id 是 openclaw-onebot
通道 id 仍然是 onebot
因此 plugins.allow / plugins.entries 使用 openclaw-onebot；安装记录由 openclaw plugins install 管理
channels.onebot 保持不变
当前版本对齐 OpenClaw 2026.4.26 / plugin-sdk 2026.4.26，并声明 setupEntry 与 channelConfigs manifest metadata

功能

🔌 原生通道插件 — 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 风格）
🖼️ 图片、语音、文件附件发送
🛠️ 通用 sendMedia 出站适配，delivery recovery / mirror / message tool 等通路都能发送图片、语音、文件
🔄 WebSocket 自动重连（指数退避）
🔒 可选 access token 鉴权
🎯 allowFrom 消息来源过滤（私聊/群聊/用户级别）
✅ 120 个测试用例全部通过
📈 覆盖率可通过 npm run coverage 复核

架构

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
openclaw plugins install .clawhub-plugin/openclaw-onebot-plugin --force

scripts/install.sh 会先在源码仓库生成 .clawhub-plugin/openclaw-onebot-plugin 精简发布包，并优先通过 openclaw plugins install 写入新版插件安装索引；旧版 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 会把插件安装记录保存在托管安装索引中，请使用 openclaw plugins install <path-or-package>

也支持环境变量：

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
    }
  }
}

参数	说明
`allowFrom`	消息来源白名单 — `private:<QQ号>`、`group:<群号>`、或 `*`（允许所有）
`accessToken`	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
- 开启方式：

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

可选调优：

{
  "channels": {
    "onebot": {
      "streaming": {
        "block": {
          "coalesce": {
            "minChars": 80,
            "idleMs": 600
          }
        }
      }
    }
  }
}

旧版 channels.onebot.blockStreamingCoalesce 仍兼容；新版 openclaw doctor --fix 会把它迁移到 channels.onebot.streaming.block.coalesce。

验证

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

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

当前建议只把这项验证用于群聊消息；私聊 reaction 在 QQ/NapCat 上通常不生效
Streaming
- 在 OpenClaw 配置里开启 agents.defaults.blockStreamingDefault = "on"
- 然后在 QQ 里发一条明确要求“分段回复”的消息
- 成功时，QQ 会连续收到多条消息，日志里会出现 deliver(block)，最后再有 deliver(final)

语音支持（可选）

支持 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          # 120 tests
npm run build     # 编译 TypeScript
npm run coverage  # 覆盖率报告
npm run sync:openclaw-cli  # 重新同步 OpenClaw CLI 的 shared-dir 参数

发布准备

npm ci --ignore-scripts
npm run release:check
npm publish --access public

说明：

npm run release:check 会串行执行 build、全量 vitest、npm pack --dry-run、npm publish --dry-run、ClawHub package/skill 产物准备
npm 包名保持 openclaw-onebot，用于兼容已经安装 openclaw-onebot@1.2.x 的用户
ClawHub package payload 包名是 openclaw-onebot-plugin
OpenClaw runtime manifest id 仍是 openclaw-onebot，用于现有 plugins.allow / plugins.entries 配置兼容
ClawHub package 产物输出到 .clawhub-plugin/openclaw-onebot-plugin/
ClawHub skill 产物输出到 .clawhub-skill/openclaw-onebot/
npm 发布后，再创建同版本 GitHub tag/release，并用同一个 tag 发布 ClawHub package 和 skill；完整命令见 docs/release-runbook.md

English

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

Note:

npm package name: openclaw-onebot
ClawHub package payload name: openclaw-onebot-plugin
Plugin id: openclaw-onebot
Channel id: onebot
Use openclaw-onebot in plugins.allow / plugins.entries; install records are managed by openclaw plugins install
Keep channels.onebot unchanged
This release targets OpenClaw 2026.4.26 / plugin-sdk 2026.4.26 and declares setupEntry plus channelConfigs manifest metadata

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
🛠️ Generic sendMedia outbound adapter so delivery recovery, mirror, and message-tool paths can all send images, audio, and files
🔄 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.)
✅ 120 tests passing
📈 Coverage can be re-generated with npm run coverage

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
openclaw plugins install .clawhub-plugin/openclaw-onebot-plugin --force

scripts/install.sh prepares .clawhub-plugin/openclaw-onebot-plugin in the source repo first and prefers openclaw plugins install so current OpenClaw builds update the managed plugin install index. Older OpenClaw builds fall back to the legacy manual copy path. The script also 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
Do not edit plugins.installs by hand; current OpenClaw stores install records in a managed plugin index, so use openclaw plugins install <path-or-package>

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
- 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:

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

Optional coalescing hint for OneBot:

{
  "channels": {
    "onebot": {
      "streaming": {
        "block": {
          "coalesce": {
            "minChars": 80,
            "idleMs": 600
          }
        }
      }
    }
  }
}

Legacy channels.onebot.blockStreamingCoalesce remains accepted; current openclaw doctor --fix migrates it to channels.onebot.streaming.block.coalesce.

Verification

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

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
- Enable agents.defaults.blockStreamingDefault = "on" in OpenClaw config
- Send a QQ prompt that explicitly asks for chunked / stepwise output
- Success looks like multiple QQ messages plus deliver(block) entries in the gateway log, followed by deliver(final)

Configuration

Option	Description
`allowFrom`	Whitelist — `private:<qq>`, `group:<id>`, or `*` (allow all)
`accessToken`	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`

Target Format

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

Development

npm install
npm test          # Run 120 tests
npm run build     # Compile TypeScript
npm run coverage  # Coverage report
npm run sync:openclaw-cli  # Re-apply shared-dir CLI wiring after OpenClaw upgrades

Release Prep

npm ci --ignore-scripts
npm run release:check
npm publish --access public

Notes:

npm run release:check runs build, the full vitest suite, npm pack --dry-run, npm publish --dry-run, and ClawHub package/skill staging
npm package name stays openclaw-onebot for users already installed from openclaw-onebot@1.2.x
ClawHub package payload name: openclaw-onebot-plugin
OpenClaw runtime manifest id stays openclaw-onebot for existing plugins.allow / plugins.entries compatibility
The ClawHub package payload is written to .clawhub-plugin/openclaw-onebot-plugin/
The ClawHub skill payload is written to .clawhub-skill/openclaw-onebot/
After npm is published, create the same-version GitHub tag/release and publish the ClawHub package plus skill from that tag; see docs/release-runbook.md

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 34 Commits
.github/workflows		.github/workflows
docs		docs
scripts		scripts
src		src
test		test
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
SKILL.md		SKILL.md
index.ts		index.ts
openclaw.plugin.json		openclaw.plugin.json
package-lock.json		package-lock.json
package.json		package.json
setup-entry.ts		setup-entry.ts
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

OpenClaw OneBot 11 Channel Plugin 🐧

中文

功能

架构

快速开始

1. 安装插件

2. 配置

3. 重启 Gateway

高级配置

Reaction 与流式回复

验证

语音支持（可选）

消息目标格式

NapCat 部署参考

开发

发布准备

English

Features

Quick Start

1. Install

2. Configure

3. Restart Gateway

Voice Support (Optional)

Reactions and Streaming Replies

Verification

Configuration

Target Format

Development

Release Prep

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages