{"id":50017528,"url":"https://github.com/LSTM-Kirigaya/openclaw-onebot","last_synced_at":"2026-05-22T03:01:25.806Z","repository":{"id":343067219,"uuid":"1170852268","full_name":"LSTM-Kirigaya/openclaw-onebot","owner":"LSTM-Kirigaya","description":"小龙虾 openclaw 的 onebot 接入框架，可用于接入 QQ","archived":false,"fork":false,"pushed_at":"2026-05-07T16:03:58.000Z","size":3098,"stargazers_count":136,"open_issues_count":6,"forks_count":29,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-16T02:33:49.763Z","etag":null,"topics":["ai-agent","ai-agent-framework","ai-agents","openclaw","openclaw-china","openclaw-plugin","openclaw-skills","qq","qq-bot","qqbot","qqrobot"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LSTM-Kirigaya.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-02T15:41:54.000Z","updated_at":"2026-05-13T06:40:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/LSTM-Kirigaya/openclaw-onebot","commit_stats":null,"previous_names":["lstm-kirigaya/openclaw-onebot"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/LSTM-Kirigaya/openclaw-onebot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LSTM-Kirigaya%2Fopenclaw-onebot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LSTM-Kirigaya%2Fopenclaw-onebot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LSTM-Kirigaya%2Fopenclaw-onebot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LSTM-Kirigaya%2Fopenclaw-onebot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LSTM-Kirigaya","download_url":"https://codeload.github.com/LSTM-Kirigaya/openclaw-onebot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LSTM-Kirigaya%2Fopenclaw-onebot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33326656,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-21T12:23:38.849Z","status":"online","status_checked_at":"2026-05-22T02:00:06.671Z","response_time":265,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","ai-agent-framework","ai-agents","openclaw","openclaw-china","openclaw-plugin","openclaw-skills","qq","qq-bot","qqbot","qqrobot"],"created_at":"2026-05-20T05:01:16.865Z","updated_at":"2026-05-22T03:01:25.786Z","avatar_url":"https://github.com/LSTM-Kirigaya.png","language":"TypeScript","funding_links":[],"categories":["Skills \u0026 Plugins"],"sub_categories":["Third-Party Platforms"],"readme":"\u003cdiv align=\"center\"\u003e\n\n# openclaw-onebot\n\n[OpenClaw](https://openclaw.ai)  的 **OneBot v11 协议**（QQ/Lagrange.Core、go-cqhttp 等）渠道插件。\n\n[![npm version](https://img.shields.io/npm/v/@kirigaya/openclaw-onebot?style=flat-square)](https://www.npmjs.com/package/@kirigaya/openclaw-onebot)\n[![GitHub stars](https://img.shields.io/github/stars/LSTM-Kirigaya/openclaw-onebot?style=flat-square)](https://github.com/LSTM-Kirigaya/openclaw-onebot)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D22-brightgreen?style=flat-square)](https://nodejs.org)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.4-blue?style=flat-square)](https://www.typescriptlang.org/)\n[![OpenClaw](https://img.shields.io/badge/OpenClaw-Plugin-9cf?style=flat-square)](https://openclaw.ai)\n\n\u003c/div\u003e\n\n---\n\n## 安装\n\n```bash\nopenclaw plugins install @kirigaya/openclaw-onebot\nopenclaw onebot setup\n```\n\n## 教程\n\n[让 QQ 接入 openclaw！让你的助手掌管千人大群](https://kirigaya.cn/blog/article?seq=368)\n\n\u003cimg src=\"./figure/arch.png\" /\u003e\n\n\n## 功能\n\n- ✅ 私聊：所有消息 AI 都会回复\n- ✅ 触发：支持 @触发 和基于关键字的触发\n- ✅ 自动获取上下文\n- ✅ 自定义新成员入群欢迎触发器\n- ✅ 自动合并转发长消息：超过阈值可渲染为图片发送或者合并发送\n- ✅ 支持文件，图像读取/发送\n- ✅ 支持黑白名单系统\n\n## 安装 onebot 服务端\n\n你需要安装 onebot 服务端，QQ 目前比较常用的是 onebot 服务端是 NapCat，可以查看 [官网](https://napneko.github.io/) 了解安装方法\n\n\n### 连接类型\n\n| 类型 | 说明 |\n|------|------|\n| `forward-websocket` | 插件主动连接 OneBot（go-cqhttp、Lagrange.Core 正向 WS/WSS） |\n| `backward-websocket` | 插件作为服务端，OneBot 连接过来 |\n\n\u003e 💡 **提示**：支持 `ws://` 和 `wss://`（WebSocket Secure）协议，可填写完整 URL 如 `wss://ws-napcatqq.example.com`\n\n### 环境变量\n\n可替代配置文件，适用于 Lagrange 等：\n\n| 变量 | 说明 |\n|------|------|\n| `ONEBOT_WS_TYPE` | forward-websocket / backward-websocket |\n| `ONEBOT_WS_HOST` | 主机地址 |\n| `ONEBOT_WS_PORT` | 端口 |\n| `ONEBOT_WS_ACCESS_TOKEN` | 访问令牌 |\n\n## 使用\n\n1. 安装并配置\n2. 重启 Gateway：`openclaw gateway restart`\n3. 在 QQ 私聊或群聊中发消息（群聊需 @ 机器人，或配置关键字触发）\n\n## 关键字触发回复\n\n除了 @ 机器人外，还可以配置关键字检测，当群消息中包含指定关键字时自动触发回复（无需 @）。\n\n```json\n{\n  \"channels\": {\n    \"onebot\": {\n      \"keywordTriggers\": {\n        \"enabled\": true,\n        \"keywords\": [\"AI\", \"助手\", \"帮我问\"],\n        \"caseSensitive\": false\n      }\n    }\n  }\n}\n```\n\n| 配置项 | 说明 |\n|--------|------|\n| `enabled` | 是否启用关键字触发 |\n| `keywords` | 关键字列表，包含任一关键字即触发 |\n| `caseSensitive` | 是否区分大小写 |\n\n## 长消息处理与 OG 图片渲染\n\n当单次回复超过**长消息阈值**（默认 300 字）时，可选用三种模式（`openclaw onebot setup` 中配置）：\n\n| 模式 | 说明 |\n|------|------|\n| `normal` | 准流式分段发送：边生成边聚合，按时间窗口或长度阈值增量发送 |\n| `og_image` | 将 Markdown 转为 HTML 再生成图片发送（需安装 `satori` 和 `sharp`） |\n| `forward` | 合并转发（发给自己后打包转发） |\n\n`normal` 模式默认会开启块流式接收，并在插件侧做短时间聚合，默认规则：\n\n- `normalModeFlushIntervalMs`: `1200`\n- `normalModeFlushChars`: `160`\n\n也就是回复不会逐 token 刷屏，而是大约每 1.2 秒或累计到 160 字左右就发送一段。可在 `openclaw.json` 中手动调整：\n\n```json\n{\n  \"channels\": {\n    \"onebot\": {\n      \"longMessageMode\": \"normal\",\n      \"normalModeFlushIntervalMs\": 1200,\n      \"normalModeFlushChars\": 160\n    }\n  }\n}\n```\n\n选择 **生成图片发送（og_image）** 时，会额外询问**渲染主题**：\n\n| 选项 | 说明 |\n|------|------|\n| **default** | 无额外样式，默认白底黑字 |\n| **dust** | 内置主题：暖色、旧纸质感 |\n| **custom** | 自定义：在 `ogImageRenderThemePath` 中填写 CSS 文件绝对路径 |\n\n配置项（枚举 + 可选路径）：\n\n- `ogImageRenderTheme`：`\"default\"` | `\"dust\"` | `\"custom\"`\n- `ogImageRenderThemePath`：当为 `custom` 时必填，CSS 文件绝对路径\n\n示例（`openclaw.json`）：\n\n```json\n{\n  \"channels\": {\n    \"onebot\": {\n      \"longMessageMode\": \"og_image\",\n      \"longMessageThreshold\": 300,\n      \"ogImageRenderTheme\": \"dust\"\n    }\n  }\n}\n```\n\n自定义主题示例：\n\n```json\n{\n  \"channels\": {\n    \"onebot\": {\n      \"longMessageMode\": \"og_image\",\n      \"ogImageRenderTheme\": \"custom\",\n      \"ogImageRenderThemePath\": \"C:/path/to/your-theme.css\"\n    }\n  }\n}\n```\n\n## 主动发送消息\n\n通过 `openclaw message send` CLI（无需 Agent 工具）：\n\n```bash\n# 发送文本\nopenclaw message send --channel onebot --target user:123456789 --message \"你好\"\n\n# 发送图片\nopenclaw message send --channel onebot --target group:987654321 --media \"file:///path/to/image.png\"\n```\n\n`--target` 格式：`user:QQ号` 或 `group:群号`。回复场景由 deliver 自动投递，Agent 输出 text/mediaUrl 即会送达。\n\n## 新成员入群欢迎（自定义图片）\n\n当有新成员加入群时，可根据其 ID 信息生成欢迎图片并发送。详见 [receive.md](skills/onebot-ops/receive.md#新成员入群欢迎)。\n\n1. 在 `openclaw.json` 中配置：\n\n```json\n{\n  \"channels\": {\n    \"onebot\": {\n      \"groupIncrease\": {\n        \"enabled\": true,\n        \"command\": \"npx tsx src/openclaw/trigger/welcome.ts\",\n        \"cwd\": \"C:/path/to/Tiphareth\"\n      }\n    }\n  }\n}\n```\n\n2. `command` 在 `cwd` 下用系统 shell 执行，环境变量传入 `GROUP_ID`、`GROUP_NAME`、`USER_ID`、`USER_NAME`、`AVATAR_URL`。命令可调用 `openclaw message send` 自行发送，或向 stdout 输出 JSON 行供 handler 发送。\n\n3. 测试：`npm run test:group-increase-handler`（DRY_RUN 模式，仅生成图片）\n\n## 回复白名单\n\n默认为空回复所有人的消息。如果设置的话，那么机器人就只会回复设置的数组里的用户的消息。\n\n```json\n{\n  \"channels\": {\n    \"onebot\": {\n      \"whitelistUserIds\": [1193466151]\n    }\n  }\n}\n```\n\n## 黑名单\n\n在群里有时候有些人需要被屏蔽，不管他怎么 @ 还是怎么，都屏蔽他的消息不触发。\n\n```json\n{\n  \"channels\": {\n    \"onebot\": {\n      \"blacklistUserIds\": [123456789]\n    }\n  }\n}\n```\n\n**注意**：白名单优先级高于黑名单。如果同时设置了白名单和黑名单，只有白名单内的用户才能触发，且黑名单内的白名单用户也会被屏蔽。\n\n## 新人入群触发器\n\n如果有人入群之后，可以通过这个来实现触发器。\n\n```json\n{\n  \"channels\": {\n    \"onebot\": {\n      \"groupIncrease\": {\n        \"enabled\": true,\n        \"command\": \"npx tsx welcome.ts\",\n        \"cwd\": \"/path/to/triggers\"\n      }\n    }\n  }\n}\n```\n\n实现的脚本必须支持这三个参数：\n\n```\n--userId ${userId} --username ${username} --groupId ${groupId}\n```\n\n## 测试\n\n### 测试连接\n\n项目内提供测试脚本（需 `.env` 或环境变量）：\n\n```bash\ncd openclaw-onebot\nnpm run test:connect\n```\n\n### 测试 OG 图片渲染效果\n\n用于预览「Markdown 转图片」在不同主题下的渲染效果（需安装 `satori` 和 `sharp`）：\n\n```bash\ncd openclaw-onebot\n# 无额外样式\nnpm run test:render-og-image -- default\n# 内置 dust 主题\nnpm run test:render-og-image -- dust\n# 自定义 CSS 文件（绝对路径）\nnpm run test:render-og-image -- \"C:/path/to/your-theme.css\"\n```\n\n生成图片保存在 `test/output-render-\u003c主题\u003e.png`，可直接打开查看。\n\n## 参考\n\n- [OneBot 11](https://github.com/botuniverse/onebot-11)\n- [go-cqhttp](https://docs.go-cqhttp.org/)\n- [Lagrange.Core](https://github.com/LSTM-Kirigaya/Lagrange.Core)\n- [NapCat](https://github.com/NapNeko/NapCatQQ)\n\n## 联系\n\nzhelonghuang@qq.com\n\n要是我不回你，可以选择进我的QQ群。782833642\n\n## License\n\nMIT © [LSTM-Kirigaya](https://github.com/LSTM-Kirigaya)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FLSTM-Kirigaya%2Fopenclaw-onebot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FLSTM-Kirigaya%2Fopenclaw-onebot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FLSTM-Kirigaya%2Fopenclaw-onebot/lists"}