@kirigaya/openclaw-onebot 1.0.9 → 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 图片渲染
 
@@ -190,7 +216,7 @@ openclaw message send --channel onebot --target group:987654321 --media "file://
 }
 ```
 
-### 黑名单
+## 黑名单
 
 在群里有时候有些人需要被屏蔽，不管他怎么 @ 还是怎么，都屏蔽他的消息不触发。
 
@@ -204,7 +230,7 @@ openclaw message send --channel onebot --target group:987654321 --media "file://
 }
 ```
 
-注意：白名单优先级高于黑名单。如果同时设置了白名单和黑名单，只有白名单内的用户才能触发，且黑名单内的白名单用户也会被屏蔽。
+**注意**：白名单优先级高于黑名单。如果同时设置了白名单和黑名单，只有白名单内的用户才能触发，且黑名单内的白名单用户也会被屏蔽。
 
 ## 新人入群触发器
 
@@ -264,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

@@ -32,3 +32,5 @@ export declare function getTriggerKeywords(cfg: any): string[];
  * - "contains": 消息包含关键词即可
  */
 export declare function getTriggerMode(cfg: any): "prefix" | "contains";
+/** 是否在用户不在白名单时回复“权限不足”，默认 true */
+export declare function getReplyWhenWhitelistDenied(cfg: any): boolean;

package/dist/config.js

@@ -131,3 +131,8 @@ export function getTriggerMode(cfg) {
         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);
             }
         });

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, getBlacklistUserIds, getOgImageRenderTheme, getNormalModeFlushIntervalMs, getNormalModeFlushChars, getTriggerKeywords, getTriggerMode, } 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";
@@ -150,15 +150,17 @@ export async function processInboundMessage(api, msg) {
     // 白名单检查
     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;
     }
@@ -185,7 +187,11 @@ export async function processInboundMessage(api, msg) {
     }) ?? "";
     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?.({
@@ -289,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}`;
@@ -307,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;
         }
@@ -321,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;
     };
@@ -340,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);
@@ -357,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);
     };
@@ -394,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 || {};
@@ -460,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 再补发一次。
@@ -544,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 {
@@ -645,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)
@@ -669,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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kirigaya/openclaw-onebot",
-  "version": "1.0.9",
+  "version": "1.1.0",
   "description": "OneBot v11 protocol channel plugin for OpenClaw (QQ/Lagrange.Core/go-cqhttp)",
   "license": "MIT",
   "publishConfig": {