openclaw-onebot

OpenClaw 的 OneBot v11 协议（QQ/Lagrange.Core、go-cqhttp 等）渠道插件。

教程

📖 完整安装与配置教程：让 QQ 接入 openclaw！让你的助手掌管千人大群

功能

• ✅ 私聊：所有消息 AI 都会回复
• ✅ 群聊：仅当用户 @ 机器人时回复（可配置）
• ✅ 自动获取上下文
• ✅ 新成员入群欢迎
• ✅ 自动合并转发长消息
• ✅ normal 模式准流式回复：按短时间窗口聚合后增量发送，避免等到最后一次性吐出
• ✅ 长消息生成图片：超过阈值可将 Markdown 渲染为图片发送（可选主题：default / dust / custom 自定义 CSS）
• ✅ 支持文件，图像读取/上传
• ✅ 支持白名单系统
• ✅ 通过 openclaw message send CLI 发送（无 Agent 工具，降低 token 消耗）

安装

openclaw plugins install @kirigaya/openclaw-onebot
openclaw onebot setup

安装 onebot 服务端

你需要安装 onebot 服务端，QQ 目前比较常用的是 onebot 服务端是 NapCat，可以查看 官网 了解安装方法

连接类型

| 类型 | 说明 | |------|------| | forward-websocket | 插件主动连接 OneBot（go-cqhttp、Lagrange.Core 正向 WS） | | backward-websocket | 插件作为服务端，OneBot 连接过来 |

环境变量

可替代配置文件，适用于 Lagrange 等：

| 变量 | 说明 | |------|------| | ONEBOT_WS_TYPE | forward-websocket / backward-websocket | | ONEBOT_WS_HOST | 主机地址 | | ONEBOT_WS_PORT | 端口 | | ONEBOT_WS_ACCESS_TOKEN | 访问令牌 |

使用

1. 安装并配置
2. 重启 Gateway：openclaw gateway restart
3. 在 QQ 私聊或群聊中发消息（群聊需 @ 机器人）

长消息处理与 OG 图片渲染

当单次回复超过长消息阈值（默认 300 字）时，可选用三种模式（openclaw onebot setup 中配置）：

| 模式 | 说明 | |------|------| | normal | 准流式分段发送：边生成边聚合，按时间窗口或长度阈值增量发送 | | og_image | 将 Markdown 转为 HTML 再生成图片发送（需安装 node-html-to-image） | | forward | 合并转发（发给自己后打包转发） |

normal 模式默认会开启块流式接收，并在插件侧做短时间聚合，默认规则：

• normalModeFlushIntervalMs: 1200
• normalModeFlushChars: 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。

1. 在 openclaw.json 中配置：

{
  "channels": {
    "onebot": {
      "groupIncrease": {
        "enabled": true,
        "command": "npx tsx src/openclaw/trigger/welcome.ts",
        "cwd": "C:/path/to/Tiphareth"
      }
    }
  }
}

2. command 在 cwd 下用系统 shell 执行，环境变量传入 GROUP_ID、GROUP_NAME、USER_ID、USER_NAME、AVATAR_URL。命令可调用 openclaw message send 自行发送，或向 stdout 输出 JSON 行供 handler 发送。

3. 测试：npm run test:group-increase-handler（DRY_RUN 模式，仅生成图片）

回复白名单

默认为空回复所有人的消息。如果设置的话，那么机器人就只会回复设置的数组里的用户的消息。

{
  "channels": {
    "onebot": {
      "whitelistUserIds": [1193466151],
    }
  }
}

新人入群触发器

如果有人入群之后，可以通过这个来实现触发器。

{
  "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

测试 OG 图片渲染效果

用于预览「Markdown 转图片」在不同主题下的渲染效果（需安装 node-html-to-image）：

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，可直接打开查看。

参考

• OneBot 11
• go-cqhttp
• Lagrange.Core
• NapCat

License

MIT © LSTM-Kirigaya