{"_id":"@asce66/openclaw-onebot","name":"@asce66/openclaw-onebot","dist-tags":{"latest":"1.0.3-fork"},"versions":{"1.0.3-fork":{"name":"@asce66/openclaw-onebot","version":"1.0.3-fork","description":"OneBot v11 protocol channel plugin for OpenClaw (QQ/Lagrange.Core/go-cqhttp)","license":"MIT","publishConfig":{"access":"public"},"author":{"name":"LSTM-Kirigaya"},"repository":{"type":"git","url":"git+https://github.com/LSTM-Kirigaya/openclaw-onebot.git"},"bugs":{"url":"https://github.com/LSTM-Kirigaya/openclaw-onebot/issues"},"homepage":"https://github.com/LSTM-Kirigaya/openclaw-onebot#readme","keywords":["openclaw","onebot","qq","lagrange","cqhttp","chatbot"],"type":"module","main":"./dist/index.js","exports":"./dist/index.js","openclaw":{"extensions":["./dist/index.js"],"skills":["skills/onebot-ops","skills/onebot-scripts"],"channel":{"id":"onebot","label":"OneBot","selectionLabel":"OneBot (QQ/Lagrange)","docsPath":"/channels/onebot","blurb":"OneBot v11 protocol via WebSocket (go-cqhttp, Lagrange.Core, etc.)","order":85,"aliases":["qq","lagrange","cqhttp"]}},"scripts":{"build":"tsc","test:connect":"npx tsx scripts/test-connect.ts","test:group-welcome":"npx tsx scripts/test-group-welcome.ts","test:group-increase-handler":"npx tsx scripts/test-group-increase-handler.ts","test:render-og-image":"npx tsx test/render-og-image.ts","prepublishOnly":"npm run build","pub":"npm run build && npm publish"},"dependencies":{"fuse.js":"^7.1.0","ws":"^8.17.0","@clack/prompts":"^1.0.0","tsx":"^4.0.0","cron":"^4.4.0","marked":"^15.0.0","highlight.js":"^11.10.0"},"optionalDependencies":{"node-html-to-image":"^3.0.0"},"peerDependencies":{"openclaw":"*","clawdbot":"*"},"peerDependenciesMeta":{"clawdbot":{"optional":true},"openclaw":{"optional":true}},"devDependencies":{"typescript":"^5.4.0","@types/node":"^22.0.0","@types/ws":"^8.5.10"},"engines":{"node":">=22"},"_id":"@asce66/openclaw-onebot@1.0.3-fork","gitHead":"183c4efc05578b7e50fc00ea275dfe949c3f35b5","types":"./dist/index.d.ts","_nodeVersion":"22.17.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-fgoI0QoR3GjYj0qqqjaBP/posv4aJz+hgVF/BpWk5D960EVMRG4Nc0qfKc9dh6NJHxe+J9LG6VNK+zkcxTsLgw==","shasum":"93ca22c28e898e2a8cc25db39e8e68e345d779ae","tarball":"https://registry.npmjs.org/@asce66/openclaw-onebot/-/openclaw-onebot-1.0.3-fork.tgz","fileCount":54,"unpackedSize":209922,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCDrfzG8TQDfiWJbN2O8t7IGJO3vv2HxmiaVIuIDWS4OQIhAOoXT12rjL+ev/88yPSpqoeRnK/gY/dtkoZej3LNIgJL"}]},"_npmUser":{"name":"asce66","email":"2571263394@qq.com"},"directories":{},"maintainers":[{"name":"asce66","email":"2571263394@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/openclaw-onebot_1.0.3-fork_1773337586650_0.7409518849817023"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-12T17:46:26.548Z","1.0.3-fork":"2026-03-12T17:46:26.836Z","modified":"2026-03-12T17:46:27.024Z"},"maintainers":[{"name":"asce66","email":"2571263394@qq.com"}],"description":"OneBot v11 protocol channel plugin for OpenClaw (QQ/Lagrange.Core/go-cqhttp)","homepage":"https://github.com/LSTM-Kirigaya/openclaw-onebot#readme","keywords":["openclaw","onebot","qq","lagrange","cqhttp","chatbot"],"repository":{"type":"git","url":"git+https://github.com/LSTM-Kirigaya/openclaw-onebot.git"},"author":{"name":"LSTM-Kirigaya"},"bugs":{"url":"https://github.com/LSTM-Kirigaya/openclaw-onebot/issues"},"license":"MIT","readme":"<div align=\"center\">\r\n\r\n# openclaw-onebot\r\n\r\n[OpenClaw](https://openclaw.ai)  的 **OneBot v11 协议**（QQ/Lagrange.Core、go-cqhttp 等）渠道插件。\r\n\r\n[![npm version](https://img.shields.io/npm/v/@kirigaya/openclaw-onebot?style=flat-square)](https://www.npmjs.com/package/@kirigaya/openclaw-onebot)\r\n[![GitHub stars](https://img.shields.io/github/stars/LSTM-Kirigaya/openclaw-onebot?style=flat-square)](https://github.com/LSTM-Kirigaya/openclaw-onebot)\r\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)\r\n[![Node.js](https://img.shields.io/badge/node-%3E%3D22-brightgreen?style=flat-square)](https://nodejs.org)\r\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.4-blue?style=flat-square)](https://www.typescriptlang.org/)\r\n[![OpenClaw](https://img.shields.io/badge/OpenClaw-Plugin-9cf?style=flat-square)](https://openclaw.ai)\r\n\r\n</div>\r\n\r\n---\r\n\r\n## 教程\r\n\r\n📖 **完整安装与配置教程**：[让 QQ 接入 openclaw！让你的助手掌管千人大群](https://kirigaya.cn/blog/article?seq=368)\r\n\r\n## 功能\r\n\r\n- ✅ 私聊：所有消息 AI 都会回复\r\n- ✅ 群聊：仅当用户 @ 机器人时回复（可配置）\r\n- ✅ 自动获取上下文\r\n- ✅ 新成员入群欢迎\r\n- ✅ 自动合并转发长消息\r\n- ✅ normal 模式准流式回复：按短时间窗口聚合后增量发送，避免等到最后一次性吐出\r\n- ✅ **长消息生成图片**：超过阈值可将 Markdown 渲染为图片发送（可选主题：default / dust / custom 自定义 CSS）\r\n- ✅ 支持文件，图像读取/上传\r\n- ✅ 支持白名单系统\r\n- ✅ 通过 `openclaw message send` CLI 发送（无 Agent 工具，降低 token 消耗）\r\n\r\n## 安装\r\n\r\n```bash\r\nopenclaw plugins install @kirigaya/openclaw-onebot\r\nopenclaw onebot setup\r\n```\r\n\r\n## 安装 onebot 服务端\r\n\r\n你需要安装 onebot 服务端，QQ 目前比较常用的是 onebot 服务端是 NapCat，可以查看 [官网](https://napneko.github.io/) 了解安装方法\r\n\r\n\r\n### 连接类型\r\n\r\n| 类型 | 说明 |\r\n|------|------|\r\n| `forward-websocket` | 插件主动连接 OneBot（go-cqhttp、Lagrange.Core 正向 WS） |\r\n| `backward-websocket` | 插件作为服务端，OneBot 连接过来 |\r\n\r\n### 环境变量\r\n\r\n可替代配置文件，适用于 Lagrange 等：\r\n\r\n| 变量 | 说明 |\r\n|------|------|\r\n| `ONEBOT_WS_TYPE` | forward-websocket / backward-websocket |\r\n| `ONEBOT_WS_HOST` | 主机地址 |\r\n| `ONEBOT_WS_PORT` | 端口 |\r\n| `ONEBOT_WS_ACCESS_TOKEN` | 访问令牌 |\r\n\r\n## 使用\r\n\r\n1. 安装并配置\r\n2. 重启 Gateway：`openclaw gateway restart`\r\n3. 在 QQ 私聊或群聊中发消息（群聊需 @ 机器人）\r\n\r\n## 长消息处理与 OG 图片渲染\r\n\r\n当单次回复超过**长消息阈值**（默认 300 字）时，可选用三种模式（`openclaw onebot setup` 中配置）：\r\n\r\n| 模式 | 说明 |\r\n|------|------|\r\n| `normal` | 准流式分段发送：边生成边聚合，按时间窗口或长度阈值增量发送 |\r\n| `og_image` | 将 Markdown 转为 HTML 再生成图片发送（需安装 `node-html-to-image`） |\r\n| `forward` | 合并转发（发给自己后打包转发） |\r\n\r\n`normal` 模式默认会开启块流式接收，并在插件侧做短时间聚合，默认规则：\r\n\r\n- `normalModeFlushIntervalMs`: `1200`\r\n- `normalModeFlushChars`: `160`\r\n\r\n也就是回复不会逐 token 刷屏，而是大约每 1.2 秒或累计到 160 字左右就发送一段。可在 `openclaw.json` 中手动调整：\r\n\r\n```json\r\n{\r\n  \"channels\": {\r\n    \"onebot\": {\r\n      \"longMessageMode\": \"normal\",\r\n      \"normalModeFlushIntervalMs\": 1200,\r\n      \"normalModeFlushChars\": 160\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n选择 **生成图片发送（og_image）** 时，会额外询问**渲染主题**：\r\n\r\n| 选项 | 说明 |\r\n|------|------|\r\n| **default** | 无额外样式，默认白底黑字 |\r\n| **dust** | 内置主题：暖色、旧纸质感 |\r\n| **custom** | 自定义：在 `ogImageRenderThemePath` 中填写 CSS 文件绝对路径 |\r\n\r\n配置项（枚举 + 可选路径）：\r\n\r\n- `ogImageRenderTheme`：`\"default\"` | `\"dust\"` | `\"custom\"`\r\n- `ogImageRenderThemePath`：当为 `custom` 时必填，CSS 文件绝对路径\r\n\r\n示例（`openclaw.json`）：\r\n\r\n```json\r\n{\r\n  \"channels\": {\r\n    \"onebot\": {\r\n      \"longMessageMode\": \"og_image\",\r\n      \"longMessageThreshold\": 300,\r\n      \"ogImageRenderTheme\": \"dust\"\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n自定义主题示例：\r\n\r\n```json\r\n{\r\n  \"channels\": {\r\n    \"onebot\": {\r\n      \"longMessageMode\": \"og_image\",\r\n      \"ogImageRenderTheme\": \"custom\",\r\n      \"ogImageRenderThemePath\": \"C:/path/to/your-theme.css\"\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n## 主动发送消息\r\n\r\n通过 `openclaw message send` CLI（无需 Agent 工具）：\r\n\r\n```bash\r\n# 发送文本\r\nopenclaw message send --channel onebot --target user:123456789 --message \"你好\"\r\n\r\n# 发送图片\r\nopenclaw message send --channel onebot --target group:987654321 --media \"file:///path/to/image.png\"\r\n```\r\n\r\n`--target` 格式：`user:QQ号` 或 `group:群号`。回复场景由 deliver 自动投递，Agent 输出 text/mediaUrl 即会送达。\r\n\r\n## 新成员入群欢迎（自定义图片）\r\n\r\n当有新成员加入群时，可根据其 ID 信息生成欢迎图片并发送。详见 [receive.md](skills/onebot-ops/receive.md#新成员入群欢迎)。\r\n\r\n1. 在 `openclaw.json` 中配置：\r\n\r\n```json\r\n{\r\n  \"channels\": {\r\n    \"onebot\": {\r\n      \"groupIncrease\": {\r\n        \"enabled\": true,\r\n        \"command\": \"npx tsx src/openclaw/trigger/welcome.ts\",\r\n        \"cwd\": \"C:/path/to/Tiphareth\"\r\n      }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n2. `command` 在 `cwd` 下用系统 shell 执行，环境变量传入 `GROUP_ID`、`GROUP_NAME`、`USER_ID`、`USER_NAME`、`AVATAR_URL`。命令可调用 `openclaw message send` 自行发送，或向 stdout 输出 JSON 行供 handler 发送。\r\n\r\n3. 测试：`npm run test:group-increase-handler`（DRY_RUN 模式，仅生成图片）\r\n\r\n## 回复白名单\r\n\r\n默认为空回复所有人的消息。如果设置的话，那么机器人就只会回复设置的数组里的用户的消息。\r\n\r\n```json\r\n{\r\n  \"channels\": {\r\n    \"onebot\": {\r\n      \"whitelistUserIds\": [1193466151],\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n## 新人入群触发器\r\n\r\n如果有人入群之后，可以通过这个来实现触发器。\r\n\r\n```json\r\n{\r\n  \"channels\": {\r\n    \"onebot\": {\r\n      \"groupIncrease\": {\r\n        \"enabled\": true,\r\n        \"command\": \"npx tsx welcome.ts\",\r\n        \"cwd\": \"/path/to/triggers\"\r\n      }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n实现的脚本必须支持这三个参数：\r\n\r\n```\r\n--userId ${userId} --username ${username} --groupId ${groupId}\r\n```\r\n\r\n## 测试\r\n\r\n### 测试连接\r\n\r\n项目内提供测试脚本（需 `.env` 或环境变量）：\r\n\r\n```bash\r\ncd openclaw-onebot\r\nnpm run test:connect\r\n```\r\n\r\n### 测试 OG 图片渲染效果\r\n\r\n用于预览「Markdown 转图片」在不同主题下的渲染效果（需安装 `node-html-to-image`）：\r\n\r\n```bash\r\ncd openclaw-onebot\r\n# 无额外样式\r\nnpm run test:render-og-image -- default\r\n# 内置 dust 主题\r\nnpm run test:render-og-image -- dust\r\n# 自定义 CSS 文件（绝对路径）\r\nnpm run test:render-og-image -- \"C:/path/to/your-theme.css\"\r\n```\r\n\r\n生成图片保存在 `test/output-render-<主题>.png`，可直接打开查看。\r\n\r\n## 参考\r\n\r\n- [OneBot 11](https://github.com/botuniverse/onebot-11)\r\n- [go-cqhttp](https://docs.go-cqhttp.org/)\r\n- [Lagrange.Core](https://github.com/LSTM-Kirigaya/Lagrange.Core)\r\n- [NapCat](https://github.com/NapNeko/NapCatQQ)\r\n\r\n## License\r\n\r\nMIT © [LSTM-Kirigaya](https://github.com/LSTM-Kirigaya)\r\n","readmeFilename":"README.md","_rev":"1-84f91e0c365fcf522828a76e93b25c5b"}