openclaw plugins install @kirigaya/openclaw-onebot
openclaw onebot setup
- ✅ 私聊：所有消息 AI 都会回复
- ✅ 触发：支持 @触发 和基于关键字的触发
- ✅ 自动获取上下文
- ✅ 自定义新成员入群欢迎触发器
- ✅ 自动合并转发长消息：超过阈值可渲染为图片发送或者合并发送
- ✅ 支持文件，图像读取/发送
- ✅ 支持黑白名单系统
你需要安装 onebot 服务端，QQ 目前比较常用的是 onebot 服务端是 NapCat，可以查看 官网 了解安装方法
| 类型 | 说明 |
|---|---|
forward-websocket |
插件主动连接 OneBot（go-cqhttp、Lagrange.Core 正向 WS/WSS） |
backward-websocket |
插件作为服务端，OneBot 连接过来 |
💡 提示：支持
ws://和wss://（WebSocket Secure）协议，可填写完整 URL 如wss://ws-napcatqq.example.com
可替代配置文件，适用于 Lagrange 等：
| 变量 | 说明 |
|---|---|
ONEBOT_WS_TYPE |
forward-websocket / backward-websocket |
ONEBOT_WS_HOST |
主机地址 |
ONEBOT_WS_PORT |
端口 |
ONEBOT_WS_ACCESS_TOKEN |
访问令牌 |
- 安装并配置
- 重启 Gateway：
openclaw gateway restart - 在 QQ 私聊或群聊中发消息（群聊需 @ 机器人，或配置关键字触发）
除了 @ 机器人外，还可以配置关键字检测，当群消息中包含指定关键字时自动触发回复（无需 @）。
{
"channels": {
"onebot": {
"keywordTriggers": {
"enabled": true,
"keywords": ["AI", "助手", "帮我问"],
"caseSensitive": false
}
}
}
}| 配置项 | 说明 |
|---|---|
enabled |
是否启用关键字触发 |
keywords |
关键字列表，包含任一关键字即触发 |
caseSensitive |
是否区分大小写 |
当单次回复超过长消息阈值（默认 300 字）时，可选用三种模式（openclaw onebot setup 中配置）：
| 模式 | 说明 |
|---|---|
normal |
准流式分段发送：边生成边聚合，按时间窗口或长度阈值增量发送 |
og_image |
将 Markdown 转为 HTML 再生成图片发送（需安装 satori 和 sharp） |
forward |
合并转发（发给自己后打包转发） |
normal 模式默认会开启块流式接收，并在插件侧做短时间聚合，默认规则：
normalModeFlushIntervalMs:1200normalModeFlushChars:160
也就是回复不会逐 token 刷屏，而是大约每 1.2 秒或累计到 160 字左右就发送一段。可在 openclaw.json 中手动调整：
{
"channels": {
"onebot": {
"longMessageMode": "normal",
"normalModeFlushIntervalMs": 1200,
"normalModeFlushChars": 160
}
}
}选择 生成图片发送（og_image） 时，会额外询问渲染主题：
| 选项 | 说明 |
|---|---|
| default | 无额外样式，默认白底黑字 |
| dust | 内置主题：暖色、旧纸质感 |
| custom | 自定义：在 ogImageRenderThemePath 中填写 CSS 文件绝对路径 |
配置项（枚举 + 可选路径）：
ogImageRenderTheme："default"|"dust"|"custom"ogImageRenderThemePath：当为custom时必填，CSS 文件绝对路径
示例（openclaw.json）：
{
"channels": {
"onebot": {
"longMessageMode": "og_image",
"longMessageThreshold": 300,
"ogImageRenderTheme": "dust"
}
}
}自定义主题示例：
{
"channels": {
"onebot": {
"longMessageMode": "og_image",
"ogImageRenderTheme": "custom",
"ogImageRenderThemePath": "C:/path/to/your-theme.css"
}
}
}通过 openclaw message send CLI（无需 Agent 工具）：
# 发送文本
openclaw message send --channel onebot --target user:123456789 --message "你好"
# 发送图片
openclaw message send --channel onebot --target group:987654321 --media "file:///path/to/image.png"--target 格式：user:QQ号 或 group:群号。回复场景由 deliver 自动投递，Agent 输出 text/mediaUrl 即会送达。
当有新成员加入群时，可根据其 ID 信息生成欢迎图片并发送。详见 receive.md。
- 在
openclaw.json中配置：
{
"channels": {
"onebot": {
"groupIncrease": {
"enabled": true,
"command": "npx tsx src/openclaw/trigger/welcome.ts",
"cwd": "C:/path/to/Tiphareth"
}
}
}
}-
command在cwd下用系统 shell 执行，环境变量传入GROUP_ID、GROUP_NAME、USER_ID、USER_NAME、AVATAR_URL。命令可调用openclaw message send自行发送，或向 stdout 输出 JSON 行供 handler 发送。 -
测试：
npm run test:group-increase-handler（DRY_RUN 模式，仅生成图片）
默认为空回复所有人的消息。如果设置的话，那么机器人就只会回复设置的数组里的用户的消息。
{
"channels": {
"onebot": {
"whitelistUserIds": [1193466151]
}
}
}在群里有时候有些人需要被屏蔽，不管他怎么 @ 还是怎么，都屏蔽他的消息不触发。
{
"channels": {
"onebot": {
"blacklistUserIds": [123456789]
}
}
}注意：白名单优先级高于黑名单。如果同时设置了白名单和黑名单，只有白名单内的用户才能触发，且黑名单内的白名单用户也会被屏蔽。
如果有人入群之后，可以通过这个来实现触发器。
{
"channels": {
"onebot": {
"groupIncrease": {
"enabled": true,
"command": "npx tsx welcome.ts",
"cwd": "/path/to/triggers"
}
}
}
}实现的脚本必须支持这三个参数：
--userId ${userId} --username ${username} --groupId ${groupId}
项目内提供测试脚本（需 .env 或环境变量）：
cd openclaw-onebot
npm run test:connect用于预览「Markdown 转图片」在不同主题下的渲染效果（需安装 satori 和 sharp）：
cd openclaw-onebot
# 无额外样式
npm run test:render-og-image -- default
# 内置 dust 主题
npm run test:render-og-image -- dust
# 自定义 CSS 文件（绝对路径）
npm run test:render-og-image -- "C:/path/to/your-theme.css"生成图片保存在 test/output-render-<主题>.png，可直接打开查看。
要是我不回你，可以选择进我的QQ群。782833642
MIT © LSTM-Kirigaya
