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