@kirigaya/openclaw-onebot 1.0.5 → 1.1.0

package/README.md

@@ -15,29 +15,29 @@
 
 ---
 
+## 安装
+
+```bash
+openclaw plugins install @kirigaya/openclaw-onebot
+openclaw onebot setup
+```
+
 ## 教程
 
-📖 **完整安装与配置教程**：[让 QQ 接入 openclaw！让你的助手掌管千人大群](https://kirigaya.cn/blog/article?seq=368)
+[让 QQ 接入 openclaw！让你的助手掌管千人大群](https://kirigaya.cn/blog/article?seq=368)
+
+<img src="./figure/arch.png" />
+
 
 ## 功能
 
 - ✅ 私聊：所有消息 AI 都会回复
-- ✅ 群聊：仅当用户 @ 机器人时回复（可配置）
+- ✅ 触发：支持 @触发 和基于关键字的触发
 - ✅ 自动获取上下文
-- ✅ 新成员入群欢迎
-- ✅ 自动合并转发长消息
-- ✅ normal 模式准流式回复：按短时间窗口聚合后增量发送，避免等到最后一次性吐出
-- ✅ **长消息生成图片**：超过阈值可将 Markdown 渲染为图片发送（可选主题：default / dust / custom 自定义 CSS）
-- ✅ 支持文件，图像读取/上传
-- ✅ 支持白名单系统
-- ✅ 通过 `openclaw message send` CLI 发送（无 Agent 工具，降低 token 消耗）
-
-## 安装
-
-```bash
-openclaw plugins install @kirigaya/openclaw-onebot
-openclaw onebot setup
-```
+- ✅ 自定义新成员入群欢迎触发器
+- ✅ 自动合并转发长消息：超过阈值可渲染为图片发送或者合并发送
+- ✅ 支持文件，图像读取/发送
+- ✅ 支持黑白名单系统
 
 ## 安装 onebot 服务端
 
@@ -48,9 +48,11 @@ openclaw onebot setup
 
 | 类型 | 说明 |
 |------|------|
-| `forward-websocket` | 插件主动连接 OneBot（go-cqhttp、Lagrange.Core 正向 WS） |
+| `forward-websocket` | 插件主动连接 OneBot（go-cqhttp、Lagrange.Core 正向 WS/WSS） |
 | `backward-websocket` | 插件作为服务端，OneBot 连接过来 |
 
+> 💡 **提示**：支持 `ws://` 和 `wss://`（WebSocket Secure）协议，可填写完整 URL 如 `wss://ws-napcatqq.example.com`
+
 ### 环境变量
 
 可替代配置文件，适用于 Lagrange 等：
@@ -66,7 +68,31 @@ openclaw onebot setup
 
 1. 安装并配置
 2. 重启 Gateway：`openclaw gateway restart`
-3. 在 QQ 私聊或群聊中发消息（群聊需 @ 机器人）
+3. 在 QQ 私聊或群聊中发消息（群聊需 @ 机器人，或配置关键字触发）
+
+## 关键字触发回复
+
+除了 @ 机器人外，还可以配置关键字检测，当群消息中包含指定关键字时自动触发回复（无需 @）。
+
+```json
+{
+  "channels": {
+    "onebot": {
+      "keywordTriggers": {
+        "enabled": true,
+        "keywords": ["AI", "助手", "帮我问"],
+        "caseSensitive": false
+      }
+    }
+  }
+}
+```
+
+| 配置项 | 说明 |
+|--------|------|
+| `enabled` | 是否启用关键字触发 |
+| `keywords` | 关键字列表，包含任一关键字即触发 |
+| `caseSensitive` | 是否区分大小写 |
 
 ## 长消息处理与 OG 图片渲染
 
@@ -75,7 +101,7 @@ openclaw onebot setup
 | 模式 | 说明 |
 |------|------|
 | `normal` | 准流式分段发送：边生成边聚合，按时间窗口或长度阈值增量发送 |
-| `og_image` | 将 Markdown 转为 HTML 再生成图片发送（需安装 `node-html-to-image`） |
+| `og_image` | 将 Markdown 转为 HTML 再生成图片发送（需安装 `satori` 和 `sharp`） |
 | `forward` | 合并转发（发给自己后打包转发） |
 
 `normal` 模式默认会开启块流式接收，并在插件侧做短时间聚合，默认规则：
@@ -184,12 +210,28 @@ openclaw message send --channel onebot --target group:987654321 --media "file://
 {
   "channels": {
     "onebot": {
-      "whitelistUserIds": [1193466151],
+      "whitelistUserIds": [1193466151]
     }
   }
 }
 ```
 
+## 黑名单
+
+在群里有时候有些人需要被屏蔽，不管他怎么 @ 还是怎么，都屏蔽他的消息不触发。
+
+```json
+{
+  "channels": {
+    "onebot": {
+      "blacklistUserIds": [123456789]
+    }
+  }
+}
+```
+
+**注意**：白名单优先级高于黑名单。如果同时设置了白名单和黑名单，只有白名单内的用户才能触发，且黑名单内的白名单用户也会被屏蔽。
+
 ## 新人入群触发器
 
 如果有人入群之后，可以通过这个来实现触发器。
@@ -227,7 +269,7 @@ npm run test:connect
 
 ### 测试 OG 图片渲染效果
 
-用于预览「Markdown 转图片」在不同主题下的渲染效果（需安装 `node-html-to-image`）：
+用于预览「Markdown 转图片」在不同主题下的渲染效果（需安装 `satori` 和 `sharp`）：
 
 ```bash
 cd openclaw-onebot
@@ -248,6 +290,12 @@ npm run test:render-og-image -- "C:/path/to/your-theme.css"
 - [Lagrange.Core](https://github.com/LSTM-Kirigaya/Lagrange.Core)
 - [NapCat](https://github.com/NapNeko/NapCatQQ)
 
+## 联系
+
+zhelonghuang@qq.com
+
+要是我不回你，可以选择进我的QQ群。782833642
+
 ## License
 
 MIT © [LSTM-Kirigaya](https://github.com/LSTM-Kirigaya)

package/dist/config.d.ts

@@ -13,9 +13,24 @@ export declare function getNormalModeFlushIntervalMs(cfg: any): number;
 export declare function getNormalModeFlushChars(cfg: any): number;
 /** 白名单 QQ 号列表，为空则所有人可回复；非空则仅白名单内用户可触发 AI */
 export declare function getWhitelistUserIds(cfg: any): number[];
+/** 黑名单 QQ 号列表，在黑名单内的用户无法触发 AI */
+export declare function getBlacklistUserIds(cfg: any): number[];
 /**
  * OG 图片渲染主题：枚举 default（无额外样式）、dust（内置）、custom（使用 ogImageRenderThemePath）
  * 返回用于 getMarkdownStyles 的值：default | dust | 自定义 CSS 绝对路径
  */
 export declare function getOgImageRenderTheme(cfg: any): "default" | "dust" | string;
 export declare function listAccountIds(apiOrCfg: any): string[];
+/**
+ * 触发关键词列表，当 requireMention 为 false 时生效
+ * 消息包含这些关键词时触发机器人响应
+ */
+export declare function getTriggerKeywords(cfg: any): string[];
+/**
+ * 关键词匹配模式
+ * - "prefix": 消息以关键词开头（默认）
+ * - "contains": 消息包含关键词即可
+ */
+export declare function getTriggerMode(cfg: any): "prefix" | "contains";
+/** 是否在用户不在白名单时回复“权限不足”，默认 true */
+export declare function getReplyWhenWhitelistDenied(cfg: any): boolean;

package/dist/config.js

@@ -80,6 +80,13 @@ export function getWhitelistUserIds(cfg) {
         return [];
     return v.filter((x) => typeof x === "number" || (typeof x === "string" && /^\d+$/.test(x))).map((x) => Number(x));
 }
+/** 黑名单 QQ 号列表，在黑名单内的用户无法触发 AI */
+export function getBlacklistUserIds(cfg) {
+    const v = cfg?.channels?.onebot?.blacklistUserIds;
+    if (!Array.isArray(v))
+        return [];
+    return v.filter((x) => typeof x === "number" || (typeof x === "string" && /^\d+$/.test(x))).map((x) => Number(x));
+}
 /**
  * OG 图片渲染主题：枚举 default（无额外样式）、dust（内置）、custom（使用 ogImageRenderThemePath）
  * 返回用于 getMarkdownStyles 的值：default | dust | 自定义 CSS 绝对路径
@@ -103,3 +110,29 @@ export function listAccountIds(apiOrCfg) {
         return ["default"];
     return [];
 }
+/**
+ * 触发关键词列表，当 requireMention 为 false 时生效
+ * 消息包含这些关键词时触发机器人响应
+ */
+export function getTriggerKeywords(cfg) {
+    const v = cfg?.channels?.onebot?.triggerKeywords;
+    if (!Array.isArray(v))
+        return [];
+    return v.filter((x) => typeof x === "string" && x.trim().length > 0).map((x) => x.trim());
+}
+/**
+ * 关键词匹配模式
+ * - "prefix": 消息以关键词开头（默认）
+ * - "contains": 消息包含关键词即可
+ */
+export function getTriggerMode(cfg) {
+    const v = cfg?.channels?.onebot?.triggerMode;
+    if (v === "contains")
+        return "contains";
+    return "prefix"; // 默认为前缀匹配
+}
+/** 是否在用户不在白名单时回复“权限不足”，默认 true */
+export function getReplyWhenWhitelistDenied(cfg) {
+    const v = cfg?.channels?.onebot?.replyWhenWhitelistDenied;
+    return v === undefined ? true : Boolean(v);
+}

package/dist/connection.js

@@ -177,18 +177,22 @@ function getLogger() {
 function sendOneBotAction(wsocket, action, params, log = getLogger()) {
     const echo = nextEcho();
     const payload = { action, params, echo };
+    // Log the initiation of the action with basic target info
+    const targetInfo = params.group_id ? `group=${params.group_id}` : (params.user_id ? `user=${params.user_id}` : "");
+    log.info?.(`[onebot-trace] sendOneBotAction action=${action} echo=${echo} ${targetInfo}`);
     return new Promise((resolve, reject) => {
         const timeout = setTimeout(() => {
             pendingEcho.delete(echo);
-            log.warn?.(`[onebot] sendOneBotAction ${action} timeout`);
-            reject(new Error(`OneBot action ${action} timeout`));
+            log.warn?.(`[onebot-trace] sendOneBotAction ${action} timeout for echo=${echo}, ws.readyState=${wsocket.readyState}`);
+            reject(new Error(`OneBot action ${action} timeout (echo=${echo}, ws.readyState=${wsocket.readyState})`));
         }, 15000);
         pendingEcho.set(echo, {
             resolve: (v) => {
                 clearTimeout(timeout);
                 pendingEcho.delete(echo);
+                log.info?.(`[onebot-trace] echo ${echo} resolved with retcode=${v?.retcode} message_id=${v?.data?.message_id ?? "unknown"}`);
                 if (v?.retcode !== 0)
-                    log.warn?.(`[onebot] sendOneBotAction ${action} retcode=${v?.retcode} msg=${v?.msg ?? ""}`);
+                    log.warn?.(`[onebot-trace] sendOneBotAction ${action} retcode=${v?.retcode} msg=${v?.msg ?? ""}`);
                 resolve(v);
             },
         });
@@ -196,6 +200,7 @@ function sendOneBotAction(wsocket, action, params, log = getLogger()) {
             if (err) {
                 pendingEcho.delete(echo);
                 clearTimeout(timeout);
+                log.warn?.(`[onebot-trace] sendOneBotAction ${action} wsocket.send error for echo=${echo}: ${err.message}`);
                 reject(err);
             }
         });
@@ -612,7 +617,9 @@ export async function getGroupMsgHistoryInRange(groupId, opts = {}) {
 export async function connectForward(config) {
     const path = config.path ?? "/onebot/v11/ws";
     const pathNorm = path.startsWith("/") ? path : `/${path}`;
-    const addr = `ws://${config.host}:${config.port}${pathNorm}`;
+    // 端口为 443 时使用 wss，其余端口使用 ws
+    const scheme = config.port === 443 ? "wss" : "ws";
+    const addr = `${scheme}://${config.host}:${config.port}${pathNorm}`;
     const headers = {};
     if (config.accessToken) {
         headers["Authorization"] = `Bearer ${config.accessToken}`;

package/dist/handlers/process-inbound.js

@@ -3,7 +3,7 @@
  */
 import { getOneBotConfig } from "../config.js";
 import { getRawText, getTextFromSegments, getReplyMessageId, getTextFromMessageContent, isMentioned, } from "../message.js";
-import { getRenderMarkdownToPlain, getCollapseDoubleNewlines, getWhitelistUserIds, getOgImageRenderTheme, getNormalModeFlushIntervalMs, getNormalModeFlushChars, } from "../config.js";
+import { getRenderMarkdownToPlain, getCollapseDoubleNewlines, getWhitelistUserIds, getBlacklistUserIds, getOgImageRenderTheme, getNormalModeFlushIntervalMs, getNormalModeFlushChars, getTriggerKeywords, getTriggerMode, getReplyWhenWhitelistDenied, } from "../config.js";
 import { markdownToPlain, collapseDoubleNewlines } from "../markdown.js";
 import { markdownToImage } from "../og-image.js";
 import { sendPrivateMsg, sendGroupMsg, sendPrivateImage, sendGroupImage, sendGroupForwardMsg, sendPrivateForwardMsg, setMsgEmojiLike, getMsg, } from "../connection.js";
@@ -12,6 +12,34 @@ import { loadPluginSdk, getSdk } from "../sdk.js";
 import { handleGroupIncrease } from "./group-increase.js";
 const DEFAULT_HISTORY_LIMIT = 20;
 export const sessionHistories = new Map();
+/**
+ * 检查消息是否匹配触发关键词
+ * @param text 消息文本
+ * @param keywords 关键词列表
+ * @param mode 匹配模式：prefix-前缀匹配，contains-包含匹配
+ */
+function checkTriggerKeyword(text, keywords, mode) {
+    if (!text || keywords.length === 0)
+        return false;
+    for (const keyword of keywords) {
+        if (!keyword)
+            continue;
+        if (mode === "prefix") {
+            // 前缀匹配：消息以关键词开头（忽略前导空格）
+            const trimmedText = text.trimStart();
+            if (trimmedText.toLowerCase().startsWith(keyword.toLowerCase())) {
+                return true;
+            }
+        }
+        else {
+            // 包含匹配：消息中包含关键词即可
+            if (text.toLowerCase().includes(keyword.toLowerCase())) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
 /** forward 模式下待处理的会话，用于定期清理未完成的缓冲 */
 const forwardPendingSessions = new Map();
 /** 每个 replySessionId 已发送的 chunk 数量，用于支持多次 final（如工具调用后追加内容） */
@@ -77,9 +105,31 @@ export async function processInboundMessage(api, msg) {
     const isGroup = msg.message_type === "group";
     const cfg = api.config;
     const requireMention = cfg?.channels?.onebot?.requireMention ?? true;
-    if (isGroup && requireMention && !isMentioned(msg, selfId)) {
-        api.logger?.info?.(`[onebot] ignoring group message without @mention`);
-        return;
+    // 触发检查逻辑
+    if (isGroup) {
+        const isAtMentioned = isMentioned(msg, selfId);
+        if (requireMention) {
+            // 传统模式：必须 @ 才响应
+            if (!isAtMentioned) {
+                api.logger?.info?.(`[onebot] ignoring group message without @mention`);
+                return;
+            }
+        }
+        else {
+            // 关键词模式：配置 triggerKeywords 时，需匹配关键词才响应
+            const triggerKeywords = getTriggerKeywords(cfg);
+            if (triggerKeywords.length > 0) {
+                const triggerMode = getTriggerMode(cfg);
+                const textFromMsg = getTextFromSegments(msg).trim() || messageText.trim();
+                const matched = checkTriggerKeyword(textFromMsg, triggerKeywords, triggerMode);
+                if (!matched) {
+                    api.logger?.info?.(`[onebot] ignoring group message, no trigger keyword matched`);
+                    return;
+                }
+                api.logger?.info?.(`[onebot] trigger keyword matched, processing message`);
+            }
+            // 如果没有配置关键词，则所有消息都响应（降级到原逻辑）
+        }
     }
     const gi = cfg?.channels?.onebot?.groupIncrease;
     // 测试欢迎：@ 机器人并发送 /group-increase，模拟当前发送者入群，触发欢迎（使用该人的 id、nickname 等）
@@ -97,36 +147,53 @@ export async function processInboundMessage(api, msg) {
         return;
     }
     const userId = msg.user_id;
+    // 白名单检查
     const whitelist = getWhitelistUserIds(cfg);
     if (whitelist.length > 0 && !whitelist.includes(Number(userId))) {
-        const denyMsg = "权限不足，请向管理员申请权限";
-        const getConfig = () => getOneBotConfig(api);
-        try {
-            if (msg.message_type === "group" && msg.group_id)
-                await sendGroupMsg(msg.group_id, denyMsg, getConfig);
-            else
-                await sendPrivateMsg(userId, denyMsg, getConfig);
+        if (getReplyWhenWhitelistDenied(cfg)) {
+            const denyMsg = "权限不足，请向管理员申请权限";
+            const getConfig = () => getOneBotConfig(api);
+            try {
+                if (msg.message_type === "group" && msg.group_id)
+                    await sendGroupMsg(msg.group_id, denyMsg, getConfig);
+                else
+                    await sendPrivateMsg(userId, denyMsg, getConfig);
+            }
+            catch (_) { }
         }
-        catch (_) { }
         api.logger?.info?.(`[onebot] user ${userId} not in whitelist, denied`);
         return;
     }
+    // 黑名单检查
+    const blacklist = getBlacklistUserIds(cfg);
+    if (blacklist.length > 0 && blacklist.includes(Number(userId))) {
+        api.logger?.info?.(`[onebot] user ${userId} is in blacklist, ignored`);
+        return;
+    }
     const groupId = msg.group_id;
-    const sessionId = isGroup
+    const tempSessionId = isGroup
         ? `onebot:group:${groupId}`.toLowerCase()
         : `onebot:${userId}`.toLowerCase();
     const route = runtime.channel.routing?.resolveAgentRoute?.({
         cfg,
-        sessionKey: sessionId,
+        sessionKey: tempSessionId,
         channel: "onebot",
         accountId: config.accountId ?? "default",
     }) ?? { agentId: "main" };
+    // 修复构造符合 OpenClaw 规范的全局 SessionKey格式必须为 agent:{agentId}:{channel}:{type}:{id}，否则下方的dispatchReplyWithBufferedBlockDispatcher会触发自动兜底机制，直接在 main 代理下“克隆”出一个一模一样的会话，导致多agent配置达不到效果
+    const sessionId = `agent:${route.agentId}:${tempSessionId}`;
     const storePath = runtime.channel.session?.resolveStorePath?.(cfg?.session?.store, {
         agentId: route.agentId,
     }) ?? "";
     const envelopeOptions = runtime.channel.reply?.resolveEnvelopeFormatOptions?.(cfg) ?? {};
     const chatType = isGroup ? "group" : "direct";
-    const fromLabel = String(userId);
+    // 优先使用群名片(card)，其次是昵称(nickname)，都没有则为空串
+    const senderNickname = (isGroup ? msg.sender?.card?.trim() : undefined)
+        || msg.sender?.nickname?.trim()
+        || "";
+    const fromLabel = senderNickname || String(userId);
+    // 添加日志：打印插件接收到的原始消息内容
+    api.logger?.info?.(`[onebot] received message from user ${userId}: "${messageText}"`);
     const formattedBody = runtime.channel.reply?.formatInboundEnvelope?.({
         channel: "OneBot",
         from: fromLabel,
@@ -228,10 +295,16 @@ export async function processInboundMessage(api, msg) {
             api.logger?.warn?.("[onebot] setMsgEmojiLike failed (maybe OneBot doesn't support it)");
         }
     }
-    api.logger?.info?.(`[onebot] dispatching message for session ${sessionId}`);
+    const traceId = `trace-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+    const traceLog = {
+        info: (m) => api.logger?.info?.(`[${traceId}] ${m}`),
+        warn: (m) => api.logger?.warn?.(`[${traceId}] ${m}`),
+        error: (m) => api.logger?.error?.(`[${traceId}] ${m}`)
+    };
+    traceLog.info(`dispatching message for session ${sessionId}`);
     const longMessageMode = onebotCfg.longMessageMode ?? "normal";
     const longMessageThreshold = onebotCfg.longMessageThreshold ?? 300;
-    api.logger?.info?.(`[onebot] longMessageMode=${longMessageMode}, threshold=${longMessageThreshold}`);
+    traceLog.info(`longMessageMode=${longMessageMode}, threshold=${longMessageThreshold}`);
     const normalModeFlushIntervalMs = getNormalModeFlushIntervalMs(cfg);
     const normalModeFlushChars = getNormalModeFlushChars(cfg);
     const replySessionId = `onebot-reply-${Date.now()}-${sessionId}`;
@@ -246,11 +319,13 @@ export async function processInboundMessage(api, msg) {
     let normalModeBufferedRawText = "";
     let normalModeFlushTimer = null;
     let normalModeFlushChain = Promise.resolve();
+    let receivedFinal = false;
     const getConfig = () => getOneBotConfig(api);
     const onReplySessionEnd = onebotCfg.onReplySessionEnd;
     const normalModePunctuationFlushMinChars = 24;
-    const clearNormalModeFlushTimer = () => {
+    const clearNormalModeFlushTimer = (reason = "unknown") => {
         if (normalModeFlushTimer) {
+            traceLog.info(`clearNormalModeFlushTimer: clearing timer, reason=${reason}`);
             clearTimeout(normalModeFlushTimer);
             normalModeFlushTimer = null;
         }
@@ -260,7 +335,7 @@ export async function processInboundMessage(api, msg) {
         normalModeFlushChain = normalModeFlushChain
             .then(action)
             .catch((e) => {
-            api.logger?.error?.(`[onebot] normal-mode flush failed: ${e?.message ?? e}`);
+            traceLog.error(`normal-mode flush failed: ${e?.message ?? e}`);
         });
         return normalModeFlushChain;
     };
@@ -279,11 +354,12 @@ export async function processInboundMessage(api, msg) {
         }
     };
     const flushBufferedNormalModeText = async (effectiveIsGroup, effectiveGroupId, uid) => {
-        clearNormalModeFlushTimer();
+        clearNormalModeFlushTimer("flushBufferedNormalModeText");
         if (!hasBufferedNormalModeText())
             return;
         const text = normalModeBufferedText;
         const rawText = normalModeBufferedRawText;
+        traceLog.info(`flushBufferedNormalModeText: textLen=${text.length}, textPreview="${text.slice(0, 30).replace(/\n/g, '\\n')}"`);
         normalModeBufferedText = "";
         normalModeBufferedRawText = "";
         await doSendChunk(effectiveIsGroup, effectiveGroupId, uid, text, undefined);
@@ -296,7 +372,9 @@ export async function processInboundMessage(api, msg) {
     const scheduleNormalModeFlush = (effectiveIsGroup, effectiveGroupId, uid) => {
         if (normalModeFlushTimer)
             return;
+        traceLog.info(`scheduleNormalModeFlush: scheduled (interval=${normalModeFlushIntervalMs}ms)`);
         normalModeFlushTimer = setTimeout(() => {
+            traceLog.info(`scheduleNormalModeFlush: timer triggered`);
             void queueNormalModeFlush(() => flushBufferedNormalModeText(effectiveIsGroup, effectiveGroupId, uid));
         }, normalModeFlushIntervalMs);
     };
@@ -333,6 +411,10 @@ export async function processInboundMessage(api, msg) {
                     const replyText = typeof p === "string" ? p : (p?.text ?? p?.body ?? "");
                     const mediaUrl = typeof p === "string" ? undefined : (p?.mediaUrl ?? p?.mediaUrls?.[0]);
                     const trimmed = (replyText || "").trim();
+                    traceLog.info(`deliver entry: kind=${info.kind}, textLen=${replyText.length}, mediaUrl=${!!mediaUrl}, deliveredChunks=${deliveredChunks.length}`);
+                    if (info.kind === "final") {
+                        receivedFinal = true;
+                    }
                     if ((!trimmed || trimmed === "NO_REPLY" || trimmed.endsWith("NO_REPLY")) && !mediaUrl)
                         return;
                     const { userId: uid, groupId: gid, isGroup: ig } = ctxPayload._onebot || {};
@@ -399,7 +481,7 @@ export async function processInboundMessage(api, msg) {
                             const isLong = totalLen > longMessageThreshold;
                             const isIncrementalLong = incrementalLen > longMessageThreshold;
                             const isIncremental = lastSentCount > 0;
-                            api.logger?.info?.(`[onebot] final check: totalLen=${totalLen}, threshold=${longMessageThreshold}, isLong=${isLong}, isIncremental=${isIncremental}, deliveredChunks=${deliveredChunks.length}`);
+                            traceLog.info(`final check: totalLen=${totalLen}, threshold=${longMessageThreshold}, isLong=${isLong}, isIncremental=${isIncremental}, deliveredChunks=${deliveredChunks.length}`);
                             if (isIncremental) {
                                 setForwardSuppressDelivery(false);
                                 // normal 模式下增量 chunk 已在 deliver 中实时发出；这里不能在 final 再补发一次。
@@ -416,7 +498,7 @@ export async function processInboundMessage(api, msg) {
                                                         await sendPrivateImage(uid, imgUrl, api.logger, getConfig);
                                                 }
                                                 else {
-                                                    api.logger?.warn?.("[onebot] og_image (incremental): node-html-to-image not installed, falling back to normal send");
+                                                    api.logger?.warn?.("[onebot] og_image (incremental): satori or sharp not installed, falling back to normal send");
                                                     for (const c of chunksToSend) {
                                                         if (c.text || c.mediaUrl)
                                                             await doSendChunk(effectiveIsGroup, effectiveGroupId, uid, c.text ?? "", c.mediaUrl);
@@ -483,9 +565,9 @@ export async function processInboundMessage(api, msg) {
                                 }
                             }
                             else if (!shouldSendNow && (longMessageMode === "og_image" || longMessageMode === "forward")) {
-                                api.logger?.info?.(`[onebot] checking og_image: isLong=${isLong}, mode=${longMessageMode}`);
+                                traceLog.info(`checking og_image: isLong=${isLong}, mode=${longMessageMode}`);
                                 if (isLong && longMessageMode === "og_image") {
-                                    api.logger?.info?.(`[onebot] triggering og_image for ${totalLen} chars`);
+                                    traceLog.info(`triggering og_image for ${totalLen} chars`);
                                     const fullRaw = deliveredChunks.map((c) => c.rawText ?? c.text ?? "").join("\n\n");
                                     if (fullRaw.trim()) {
                                         try {
@@ -497,7 +579,7 @@ export async function processInboundMessage(api, msg) {
                                                     await sendPrivateImage(uid, imgUrl, api.logger, getConfig);
                                             }
                                             else {
-                                                api.logger?.warn?.("[onebot] og_image: node-html-to-image not installed, falling back to normal send");
+                                                api.logger?.warn?.("[onebot] og_image: satori or sharp not installed, falling back to normal send");
                                                 setForwardSuppressDelivery(false);
                                                 for (const c of deliveredChunks) {
                                                     if (c.text || c.mediaUrl)
@@ -584,20 +666,24 @@ export async function processInboundMessage(api, msg) {
                         }
                     }
                     catch (e) {
-                        api.logger?.error?.(`[onebot] deliver failed: ${e?.message}`);
+                        traceLog.error(`deliver failed: ${e?.message}`);
                     }
                 },
                 onError: async (err, info) => {
-                    api.logger?.error?.(`[onebot] ${info?.kind} reply failed: ${err}`);
+                    traceLog.error(`${info?.kind} reply failed: ${err}`);
                     await clearEmojiReaction();
                 },
             },
             replyOptions: { disableBlockStreaming: longMessageMode !== "normal" },
         });
+        traceLog.info(`dispatchReplyWithBufferedBlockDispatcher returned successfully.`);
     }
     catch (err) {
         await clearEmojiReaction();
-        api.logger?.error?.(`[onebot] dispatch failed: ${err?.message}`);
+        // 异常时清空缓冲，避免 finally 补发半截正文后再发错误消息
+        traceLog.error(`dispatch catch block: err=${err?.message}, receivedFinal=${receivedFinal}, chunkIndex=${chunkIndex}`);
+        normalModeBufferedText = "";
+        normalModeBufferedRawText = "";
         try {
             const { userId: uid, groupId: gid, isGroup: ig } = ctxPayload._onebot || {};
             if (ig && gid)
@@ -608,7 +694,23 @@ export async function processInboundMessage(api, msg) {
         catch (_) { }
     }
     finally {
-        clearNormalModeFlushTimer();
+        traceLog.info(`dispatch finally block: receivedFinal=${receivedFinal}, hasBuffered=${hasBufferedNormalModeText()}, bufferLen=${normalModeBufferedText.length}, hasTimer=${!!normalModeFlushTimer}, chunks=${deliveredChunks.length}`);
+        // 补发缓冲池中残留的文本（引擎未发送 final 帧时会走到这里）
+        if (hasBufferedNormalModeText()) {
+            try {
+                const { userId: uid, groupId: gid, isGroup: ig } = ctxPayload._onebot || {};
+                const sessionKey = String(ctxPayload.SessionKey ?? sessionId);
+                const groupMatch = sessionKey.match(/^onebot:group:(\d+)$/i);
+                const effectiveIsGroup = groupMatch != null || Boolean(ig);
+                const effectiveGroupId = (groupMatch ? parseInt(groupMatch[1], 10) : undefined) ?? gid;
+                queueNormalModeFlush(() => flushBufferedNormalModeText(effectiveIsGroup, effectiveGroupId, uid));
+                await normalModeFlushChain;
+            }
+            catch (e) {
+                traceLog.error(`finally flush failed: ${e?.message ?? e}`);
+            }
+        }
+        clearNormalModeFlushTimer("finally");
         setForwardSuppressDelivery(false);
         setActiveReplySelfId(null);
         lastSentChunkCountBySession.delete(replySessionId);

package/dist/index.js

@@ -13,9 +13,24 @@ import { registerService } from "./service.js";
 import { startImageTempCleanup } from "./connection.js";
 import { startForwardCleanupTimer } from "./handlers/process-inbound.js";
 import { registerOneBotCli } from "./cli-commands.js";
+import { createRequire } from "module";
+const require = createRequire(import.meta.url);
+const pkg = require("../package.json");
 export default function register(api) {
     globalThis.__onebotApi = api;
     globalThis.__onebotGatewayConfig = api.config;
+    // 打印插件加载信息
+    const pluginName = pkg.name;
+    const pluginVersion = pkg.version;
+    const logger = api.logger;
+    if (logger?.info) {
+        logger.info(`[${pluginName}] v${pluginVersion} 加载中...`);
+        logger.info(`[${pluginName}] OneBot v11 协议渠道插件`);
+    }
+    else {
+        console.log(`[${pluginName}] v${pluginVersion} 加载中...`);
+        console.log(`[${pluginName}] OneBot v11 协议渠道插件`);
+    }
     startImageTempCleanup();
     startForwardCleanupTimer();
     api.registerChannel({ plugin: OneBotChannelPlugin });
@@ -33,5 +48,10 @@ export default function register(api) {
         }, { commands: ["onebot"] });
     }
     registerService(api);
-    api.logger?.info?.("[onebot] plugin loaded");
+    if (logger?.info) {
+        logger.info(`[${pluginName}] v${pluginVersion} 加载完成`);
+    }
+    else {
+        console.log(`[${pluginName}] v${pluginVersion} 加载完成`);
+    }
 }

package/dist/markdown-to-html.js

@@ -13,7 +13,7 @@ function getDustThemePath() {
     return join(__dirname, "..", "themes", "dust.css");
 }
 const HIGHLIGHT_CSS = `
-.hljs{display:block;overflow-x:auto;padding:1em;background:#1e1e1e;color:#d4d4d4;border-radius:6px;font-family:Consolas,Monaco,monospace;font-size:13px;line-height:1.5}
+.hljs{display:block;overflow-x:auto;padding:1em;background:#1e1e1e;color:#d4d4d4;border-radius:6px;font-family:Consolas,Monaco,monospace;font-size:15px;line-height:1.5}
 .hljs-keyword{color:#569cd6}
 .hljs-string{color:#ce9178}
 .hljs-number{color:#b5cea8}
@@ -53,7 +53,7 @@ marked.use({
 const WRAPPER_STYLE = `
 <style>
 *{margin:0;padding:0;box-sizing:border-box}
-body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;font-size:15px;line-height:1.6;color:#24292e;background:#fff;padding:24px;max-width:800px}
+body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;font-size:18px;line-height:1.6;color:#24292e;background:#fff;padding:24px;max-width:450px}
 h1,h2,h3,h4,h5,h6{margin:16px 0 8px;font-weight:600;line-height:1.25}
 h1{font-size:1.5em}
 h2{font-size:1.3em}
@@ -90,7 +90,7 @@ export function getMarkdownStyles(theme) {
         try {
             if (existsSync(dustPath)) {
                 const dustCss = readFileSync(dustPath, "utf-8");
-                extra = `<style>body{background:var(--background) !important;padding:24px;max-width:800px;}${dustCss}</style>`;
+                extra = `<style>body{background:var(--background) !important;padding:24px;max-width:450px;}${dustCss}</style>`;
             }
         }
         catch {

package/dist/og-image.d.ts

@@ -1,7 +1,24 @@
 /**
  * Markdown 转 OG 图片
- * 依赖可选的 node-html-to-image（需安装：npm install node-html-to-image）
+ * 依赖可选的 puppeteer-core（需安装：npm install puppeteer-core）
+ *
+ * 兼容性说明：
+ * - 支持 Ubuntu 24+、macOS、Windows
+ * - 自动检测系统 Chromium/Chrome 路径
+ * - 无需下载 Chromium，使用系统已安装的浏览器
+ *
+ * 安装系统 Chromium（Ubuntu/Debian）：
+ *   sudo apt update
+ *   sudo apt install -y chromium-browser
+ *
+ * 安装系统 Chromium（macOS）：
+ *   brew install --cask chromium
+ *   # 或直接使用系统 Chrome
  */
-export declare function markdownToImage(md: string, opts?: {
+export interface MarkdownToImageOptions {
     theme?: string;
-}): Promise<string | null>;
+    width?: number;
+    height?: number;
+    fullPage?: boolean;
+}
+export declare function markdownToImage(md: string, opts?: MarkdownToImageOptions): Promise<string | null>;

package/dist/og-image.js

@@ -1,25 +1,98 @@
 /**
  * Markdown 转 OG 图片
- * 依赖可选的 node-html-to-image（需安装：npm install node-html-to-image）
+ * 依赖可选的 puppeteer-core（需安装：npm install puppeteer-core）
+ *
+ * 兼容性说明：
+ * - 支持 Ubuntu 24+、macOS、Windows
+ * - 自动检测系统 Chromium/Chrome 路径
+ * - 无需下载 Chromium，使用系统已安装的浏览器
+ *
+ * 安装系统 Chromium（Ubuntu/Debian）：
+ *   sudo apt update
+ *   sudo apt install -y chromium-browser
+ *
+ * 安装系统 Chromium（macOS）：
+ *   brew install --cask chromium
+ *   # 或直接使用系统 Chrome
  */
 import { unlinkSync, mkdirSync } from "fs";
 import { join } from "path";
 import { tmpdir } from "os";
 import { markdownToHtml, getMarkdownStyles } from "./markdown-to-html.js";
 const OG_TEMP_DIR = join(tmpdir(), "openclaw-onebot-og");
-export async function markdownToImage(md, opts) {
-    if (!md?.trim())
-        return null;
-    let nodeHtmlToImage;
+/**
+ * 自动检测系统 Chromium/Chrome 可执行文件路径
+ */
+function detectChromiumPath() {
+    const platform = process.platform;
+    const envPath = process.env.PUPPETEER_EXECUTABLE_PATH || process.env.CHROME_PATH;
+    if (envPath) {
+        return envPath;
+    }
+    // 各平台常见路径
+    const paths = {
+        linux: [
+            "/usr/bin/chromium",
+            "/usr/bin/chromium-browser",
+            "/usr/bin/google-chrome",
+            "/usr/bin/google-chrome-stable",
+            "/snap/bin/chromium",
+            "/usr/lib/chromium/chromium",
+        ],
+        darwin: [
+            "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+            "/Applications/Chromium.app/Contents/MacOS/Chromium",
+            "/usr/bin/google-chrome",
+            "/opt/homebrew/bin/chromium",
+            "/usr/local/bin/chromium",
+        ],
+        win32: [
+            "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
+            "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe",
+            "C:\\Program Files\\Chromium\\Application\\chromium.exe",
+        ],
+    };
+    const candidates = paths[platform] || [];
+    // 简单检查文件是否存在（同步检查）
+    for (const p of candidates) {
+        try {
+            // 使用 fs.accessSync 检查文件是否可读
+            const { accessSync, constants } = require("fs");
+            accessSync(p, constants.X_OK);
+            return p;
+        }
+        catch {
+            continue;
+        }
+    }
+    return undefined;
+}
+/**
+ * 动态导入 puppeteer-core
+ */
+async function loadPuppeteer() {
     try {
-        const mod = await import("node-html-to-image");
-        nodeHtmlToImage = mod.default;
+        const mod = await import("puppeteer-core");
+        return mod;
     }
     catch {
         return null;
     }
-    if (!nodeHtmlToImage)
+}
+export async function markdownToImage(md, opts) {
+    if (!md?.trim())
+        return null;
+    const puppeteer = await loadPuppeteer();
+    if (!puppeteer) {
+        return null;
+    }
+    const chromiumPath = detectChromiumPath();
+    if (!chromiumPath) {
+        console.warn("[onebot] 未找到系统 Chromium/Chrome，请安装或设置 PUPPETEER_EXECUTABLE_PATH 环境变量");
+        console.warn("[onebot] Ubuntu/Debian: sudo apt install chromium-browser");
+        console.warn("[onebot] macOS: brew install --cask chromium");
         return null;
+    }
     const bodyHtml = markdownToHtml(md);
     const styles = getMarkdownStyles(opts?.theme);
     const theme = (opts?.theme || "").trim();
@@ -27,21 +100,58 @@ export async function markdownToImage(md, opts) {
     const fullHtml = `<!DOCTYPE html><html><head><meta charset="utf-8">${styles}</head><body>${wrappedBody}</body></html>`;
     mkdirSync(OG_TEMP_DIR, { recursive: true });
     const outPath = join(OG_TEMP_DIR, `og-${Date.now()}-${Math.random().toString(36).slice(2)}.png`);
+    let browser;
     try {
-        await nodeHtmlToImage({
-            output: outPath,
-            html: fullHtml,
+        browser = await puppeteer.launch({
+            executablePath: chromiumPath,
+            headless: true,
+            args: [
+                "--no-sandbox",
+                "--disable-setuid-sandbox",
+                "--disable-dev-shm-usage",
+                "--disable-gpu",
+                "--disable-software-rasterizer",
+                "--disable-extensions",
+                "--disable-background-networking",
+                "--disable-background-timer-throttling",
+                "--disable-backgrounding-occluded-windows",
+                "--disable-renderer-backgrounding",
+            ],
+        });
+        const page = await browser.newPage();
+        // 设置视口
+        await page.setViewport({
+            width: opts?.width || 800,
+            height: opts?.height || 600,
+            deviceScaleFactor: 2, // 高清截图
+        });
+        // 设置内容并等待渲染完成
+        await page.setContent(fullHtml, {
+            waitUntil: ["networkidle0", "domcontentloaded"],
+        });
+        // 等待字体和样式加载
+        await page.evaluate(() => document.fonts.ready);
+        // 截图
+        await page.screenshot({
+            path: outPath,
             type: "png",
-            quality: 90,
-            puppeteerArgs: {
-                headless: true,
-                args: ["--no-sandbox", "--disable-setuid-sandbox"],
-                executablePath: process.env.PUPPETEER_EXECUTABLE_PATH || "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
-            },
+            fullPage: opts?.fullPage !== false, // 默认全页截图
         });
+        await browser.close();
+        browser = undefined;
         return `file://${outPath.replace(/\\/g, "/")}`;
     }
     catch (e) {
+        // 清理浏览器资源
+        if (browser) {
+            try {
+                await browser.close();
+            }
+            catch {
+                // 忽略关闭错误
+            }
+        }
+        // 清理临时文件
         try {
             unlinkSync(outPath);
         }

package/dist/setup.js

@@ -44,7 +44,7 @@ export async function runOneBotSetup() {
         message: "长消息处理模式（单次回复超过阈值时）：",
         options: [
             { value: "normal", label: "正常发送（分段发送）" },
-            { value: "og_image", label: "生成图片发送（需安装 node-html-to-image）" },
+            { value: "og_image", label: "生成图片发送（需安装 satori 和 sharp）" },
             { value: "forward", label: "合并转发发送（发给自己后打包转发）" },
         ],
         initialValue: "normal",
@@ -89,6 +89,13 @@ export async function runOneBotSetup() {
         message: "白名单 QQ 号（逗号分隔，留空则所有人可回复）",
         initialValue: whitelistInitial,
     }));
+    const blacklistInitial = Array.isArray(prevOnebot?.blacklistUserIds)
+        ? prevOnebot.blacklistUserIds.join(", ")
+        : "";
+    const blacklistInput = guardCancel(await clackText({
+        message: "黑名单 QQ 号（逗号分隔，留空则不禁用任何人）",
+        initialValue: blacklistInitial,
+    }));
     const port = parseInt(String(portStr).trim(), 10);
     if (!Number.isFinite(port)) {
         console.error("端口必须为数字");
@@ -97,6 +104,7 @@ export async function runOneBotSetup() {
     const channels = existing.channels || {};
     const thresholdNum = parseInt(String(longMessageThreshold).trim(), 10);
     const whitelistIds = (String(whitelistInput).trim().split(/[,\s]+/).map((s) => s.trim()).filter(Boolean).map((s) => (/^\d+$/.test(s) ? Number(s) : null)).filter((n) => n != null));
+    const blacklistIds = (String(blacklistInput).trim().split(/[,\s]+/).map((s) => s.trim()).filter(Boolean).map((s) => (/^\d+$/.test(s) ? Number(s) : null)).filter((n) => n != null));
     channels.onebot = {
         ...(channels.onebot || {}),
         type,
@@ -110,6 +118,7 @@ export async function runOneBotSetup() {
         ...(longMessageMode === "og_image" ? { ogImageRenderTheme, ...(ogImageRenderThemePath != null ? { ogImageRenderThemePath } : {}) } : {}),
         longMessageThreshold: Number.isFinite(thresholdNum) ? thresholdNum : 300,
         ...(whitelistIds.length > 0 ? { whitelistUserIds: whitelistIds } : {}),
+        ...(blacklistIds.length > 0 ? { blacklistUserIds: blacklistIds } : {}),
     };
     const next = { ...existing, channels };
     writeFileSync(CONFIG_PATH, JSON.stringify(next, null, 2), "utf-8");

package/dist/types.d.ts

@@ -14,7 +14,11 @@ export interface OneBotMessage {
     raw_message?: string;
     self_id?: number;
     time?: number;
-    notice_type?: string;
+    sender?: {
+        user_id?: number;
+        nickname?: string;
+        card?: string;
+    };
     [key: string]: unknown;
 }
 export interface OneBotAccountConfig {

package/openclaw.plugin.json

@@ -29,6 +29,11 @@
         "items": { "type": "number" },
         "description": "白名单 QQ 号，非空时仅白名单内用户可触发 AI；为空则所有人可回复"
       },
+      "blacklistUserIds": {
+        "type": "array",
+        "items": { "type": "number" },
+        "description": "黑名单 QQ 号，在黑名单内的用户无法触发 AI（优先级低于白名单）"
+      },
       "renderMarkdownToPlain": {
         "type": "boolean",
         "default": true,
@@ -75,7 +80,7 @@
         "type": "string",
         "enum": ["normal", "og_image", "forward"],
         "default": "normal",
-        "description": "长消息处理模式：normal 正常发送；og_image 生成图片（需 node-html-to-image）；forward 合并转发"
+        "description": "长消息处理模式：normal 正常发送；og_image 生成图片（需 satori 和 sharp）；forward 合并转发"
       },
       "longMessageThreshold": {
         "type": "number",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kirigaya/openclaw-onebot",
-  "version": "1.0.5",
+  "version": "1.1.0",
   "description": "OneBot v11 protocol channel plugin for OpenClaw (QQ/Lagrange.Core/go-cqhttp)",
   "license": "MIT",
   "publishConfig": {
@@ -71,11 +71,13 @@
     "fuse.js": "^7.1.0",
     "highlight.js": "^11.10.0",
     "marked": "^15.0.0",
+    "puppeteer-core": "^24.39.1",
     "tsx": "^4.0.0",
     "ws": "^8.17.0"
   },
   "optionalDependencies": {
-    "node-html-to-image": "^3.0.0"
+    "satori": "^0.12.0",
+    "sharp": "^0.33.0"
   },
   "peerDependencies": {
     "clawdbot": "*"

package/skills/onebot-ops/config.md

@@ -11,6 +11,7 @@
 | path | 反向 WS 路径，默认 `/onebot/v11/ws` |
 | requireMention | 群聊是否需 @ 才回复，默认 `true` |
 | whitelistUserIds | 白名单 QQ 号数组，非空时仅白名单内用户可触发 AI；为空则所有人可回复 |
+| blacklistUserIds | 黑名单 QQ 号数组，在黑名单内的用户无法触发 AI（优先级低于白名单） |
 | renderMarkdownToPlain | 是否将 Markdown 转为纯文本再发送，默认 `true` |
 | collapseDoubleNewlines | 是否将连续多个换行压缩为单个，默认 `true`（减少 AI 输出的双空行） |
 | longMessageMode | 长消息模式：`normal` 正常发送、`og_image` 生成图片、`forward` 合并转发 |
@@ -67,5 +68,5 @@
 | 模式 | 说明 |
 |------|------|
 | normal | 正常分段发送（默认） |
-| og_image | 将 Markdown 渲染为 HTML 并生成图片发送。需安装 `node-html-to-image`：`npm install node-html-to-image`。此模式下保留 Markdown 格式与代码高亮 |
+| og_image | 将 Markdown 渲染为图片发送。需安装 `satori` 和 `sharp`：`npm install satori sharp`。此模式下保留 Markdown 格式与代码高亮，无需浏览器内核 |
 | forward | 将各块消息先发给自己，再打包为合并转发发送。需 OneBot 实现支持 `send_group_forward_msg` / `send_private_forward_msg` |

package/themes/dust.css

@@ -104,7 +104,7 @@ body {
     font-family: var(--base-font);
     color: var(--font-main-color);
     line-height: 1.8;
-    font-size: 16px;
+    font-size: 18px;
 }
 
 .markdown p {
@@ -360,7 +360,8 @@ body {
     white-space: normal;
 }
 
-/* 代码块阴影效果 */
+/* 代码块阴影效果 - OG图片模式下禁用，避免截图显示不完整 */
+/*
 .markdown pre:after,
 .markdown pre:before {
     content: '';
@@ -381,6 +382,7 @@ body {
     left: auto;
     transform: rotate(2deg);
 }
+*/
 
 /* ==================== 代码工具箱样式 ==================== */
 .code-toolbox {