@kirigaya/openclaw-onebot 1.0.2 → 1.0.4

package/dist/setup.js

@@ -2,7 +2,7 @@
  * OneBot TUI 配置向导
  * openclaw onebot setup
  */
-import { cancel as clackCancel, isCancel, note as clackNote, outro as clackOutro, select as clackSelect, text as clackText, } from "@clack/prompts";
+import { cancel as clackCancel, confirm as clackConfirm, isCancel, note as clackNote, outro as clackOutro, select as clackSelect, text as clackText, } from "@clack/prompts";
 import { existsSync, readFileSync, writeFileSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
@@ -36,11 +36,44 @@ export async function runOneBotSetup() {
         message: "Access Token（可选，留空回车跳过）",
         initialValue: process.env.ONEBOT_WS_ACCESS_TOKEN || "",
     }));
-    const port = parseInt(String(portStr).trim(), 10);
-    if (!Number.isFinite(port)) {
-        console.error("端口必须为数字");
-        process.exit(1);
+    const renderMarkdownToPlain = guardCancel(await clackConfirm({
+        message: "是否将机器人回复中的 Markdown 渲染为纯文本再发送？（去除 **、# 等标记，推荐开启）",
+        initialValue: true,
+    }));
+    const longMessageMode = guardCancel(await clackSelect({
+        message: "长消息处理模式（单次回复超过阈值时）：",
+        options: [
+            { value: "normal", label: "正常发送（分段发送）" },
+            { value: "og_image", label: "生成图片发送（需安装 node-html-to-image）" },
+            { value: "forward", label: "合并转发发送（发给自己后打包转发）" },
+        ],
+        initialValue: "normal",
+    }));
+    let ogImageRenderTheme = "default";
+    let ogImageRenderThemePath;
+    if (longMessageMode === "og_image") {
+        const themeChoice = guardCancel(await clackSelect({
+            message: "长消息生成图片时的渲染样式：",
+            options: [
+                { value: "default", label: "default（无额外样式，默认白底黑字）" },
+                { value: "dust", label: "dust（内置暖色旧纸质感）" },
+                { value: "custom", label: "custom（自定义 CSS 文件路径）" },
+            ],
+            initialValue: "default",
+        }));
+        ogImageRenderTheme = themeChoice;
+        if (themeChoice === "custom") {
+            const customPath = guardCancel(await clackText({
+                message: "CSS 文件绝对路径",
+                initialValue: "",
+            }));
+            ogImageRenderThemePath = (customPath || "").trim() || undefined;
+        }
     }
+    const longMessageThreshold = guardCancel(await clackText({
+        message: "长消息阈值（字符数，超过则启用上述模式）",
+        initialValue: "300",
+    }));
     let existing = {};
     if (existsSync(CONFIG_PATH)) {
         try {
@@ -48,7 +81,22 @@ export async function runOneBotSetup() {
         }
         catch { }
     }
+    const prevOnebot = (existing.channels || {}).onebot;
+    const whitelistInitial = Array.isArray(prevOnebot?.whitelistUserIds)
+        ? prevOnebot.whitelistUserIds.join(", ")
+        : "";
+    const whitelistInput = guardCancel(await clackText({
+        message: "白名单 QQ 号（逗号分隔，留空则所有人可回复）",
+        initialValue: whitelistInitial,
+    }));
+    const port = parseInt(String(portStr).trim(), 10);
+    if (!Number.isFinite(port)) {
+        console.error("端口必须为数字");
+        process.exit(1);
+    }
     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));
     channels.onebot = {
         ...(channels.onebot || {}),
         type,
@@ -57,6 +105,11 @@ export async function runOneBotSetup() {
         ...(accessToken?.trim() ? { accessToken: String(accessToken).trim() } : {}),
         enabled: true,
         requireMention: true,
+        renderMarkdownToPlain,
+        longMessageMode,
+        ...(longMessageMode === "og_image" ? { ogImageRenderTheme, ...(ogImageRenderThemePath != null ? { ogImageRenderThemePath } : {}) } : {}),
+        longMessageThreshold: Number.isFinite(thresholdNum) ? thresholdNum : 300,
+        ...(whitelistIds.length > 0 ? { whitelistUserIds: whitelistIds } : {}),
     };
     const next = { ...existing, channels };
     writeFileSync(CONFIG_PATH, JSON.stringify(next, null, 2), "utf-8");

package/dist/tools.d.ts

@@ -2,16 +2,18 @@
  * Agent 工具注册
  * 供 OpenClaw cron 等场景下，AI 调用 OneBot 能力
  */
-import { sendPrivateMsg, sendGroupMsg, sendGroupImage, sendPrivateImage, getGroupMsgHistory, getGroupInfo, getStrangerInfo, getGroupMemberInfo, getAvatarUrl } from "./connection.js";
+import { sendPrivateMsg, sendGroupMsg, sendGroupImage, sendPrivateImage, getGroupMsgHistory, getGroupMsgHistoryInRange, getGroupInfo, getStrangerInfo, getGroupMemberInfo, searchGroupMemberByName, getAvatarUrl } from "./connection.js";
 export interface OneBotClient {
     sendGroupMsg: typeof sendGroupMsg;
     sendGroupImage: typeof sendGroupImage;
     sendPrivateMsg: typeof sendPrivateMsg;
     sendPrivateImage: typeof sendPrivateImage;
     getGroupMsgHistory: typeof getGroupMsgHistory;
+    getGroupMsgHistoryInRange: typeof getGroupMsgHistoryInRange;
     getGroupInfo: typeof getGroupInfo;
     getStrangerInfo: typeof getStrangerInfo;
     getGroupMemberInfo: typeof getGroupMemberInfo;
+    searchGroupMemberByName: typeof searchGroupMemberByName;
     getAvatarUrl: typeof getAvatarUrl;
 }
 export declare const onebotClient: OneBotClient;

package/dist/tools.js

@@ -4,16 +4,20 @@
  */
 import WebSocket from "ws";
 import { loadScript } from "./load-script.js";
-import { getWs, sendPrivateMsg, sendGroupMsg, sendGroupImage, sendPrivateImage, uploadGroupFile, uploadPrivateFile, getGroupMsgHistory, getGroupInfo, getStrangerInfo, getGroupMemberInfo, getAvatarUrl, } from "./connection.js";
+import { getWs, sendPrivateMsg, sendGroupMsg, sendGroupImage, sendPrivateImage, uploadGroupFile, uploadPrivateFile, getGroupMsgHistory, getGroupMsgHistoryInRange, getGroupInfo, getStrangerInfo, getGroupMemberInfo, searchGroupMemberByName, getAvatarUrl, } from "./connection.js";
+import { getRenderMarkdownToPlain } from "./config.js";
+import { markdownToPlain } from "./markdown.js";
 export const onebotClient = {
     sendGroupMsg,
     sendGroupImage,
     sendPrivateMsg,
     sendPrivateImage,
     getGroupMsgHistory,
+    getGroupMsgHistoryInRange,
     getGroupInfo,
     getStrangerInfo,
     getGroupMemberInfo,
+    searchGroupMemberByName,
     getAvatarUrl,
 };
 export function registerTools(api) {
@@ -35,14 +39,16 @@ export function registerTools(api) {
             if (!w || w.readyState !== WebSocket.OPEN) {
                 return { content: [{ type: "text", text: "OneBot 未连接" }] };
             }
+            const cfg = api?.config;
+            const textToSend = getRenderMarkdownToPlain(cfg) ? markdownToPlain(params.text) : params.text;
             const t = params.target.replace(/^onebot:/i, "");
             try {
                 if (t.startsWith("group:")) {
-                    await sendGroupMsg(parseInt(t.slice(6), 10), params.text);
+                    await sendGroupMsg(parseInt(t.slice(6), 10), textToSend);
                 }
                 else {
                     const id = parseInt(t.replace(/^user:/, ""), 10);
-                    await sendPrivateMsg(id, params.text);
+                    await sendPrivateMsg(id, textToSend);
                 }
                 return { content: [{ type: "text", text: "发送成功" }] };
             }
@@ -116,14 +122,16 @@ export function registerTools(api) {
     });
     api.registerTool({
         name: "onebot_get_group_msg_history",
-        description: "获取群聊历史消息（需 Lagrange.Core，go-cqhttp 可能不支持）。用于定时总结、日报等场景",
+        description: "获取群聊历史消息。可指定 hours 获取最近 N 小时内消息（分页拉取），不指定则返回单页（始终从旧到新）。需 Lagrange.Core",
         parameters: {
             type: "object",
             properties: {
                 group_id: { type: "number", description: "群号" },
-                count: { type: "number", description: "获取条数，默认 50" },
-                message_seq: { type: "number", description: "可选，起始消息序号" },
-                message_id: { type: "number", description: "可选，起始消息 ID" },
+                hours: { type: "number", description: "可选。指定则获取从现在到过去 N 小时内的消息（如 24 即过去 24 小时）" },
+                count: { type: "number", description: "单页条数（未指定 hours 时生效），默认 50" },
+                message_seq: { type: "number", description: "可选，起始消息序号（分页用，未指定 hours 时生效）" },
+                message_id: { type: "number", description: "可选，起始消息 ID（未指定 hours 时生效）" },
+                limit: { type: "number", description: "指定 hours 时最多返回条数，默认 3000" },
             },
             required: ["group_id"],
         },
@@ -133,10 +141,26 @@ export function registerTools(api) {
                 return { content: [{ type: "text", text: "OneBot 未连接" }] };
             }
             try {
+                const hoursNum = params.hours != null ? Number(params.hours) : undefined;
+                if (typeof hoursNum === "number" && Number.isFinite(hoursNum) && hoursNum > 0) {
+                    const startTime = Math.floor(Date.now() / 1000) - hoursNum * 3600;
+                    const msgs = await getGroupMsgHistoryInRange(params.group_id, {
+                        startTime,
+                        limit: params.limit ?? 3000,
+                        chunkSize: 100,
+                    });
+                    const summary = msgs.map((m) => {
+                        const text = typeof m.message === "string" ? m.message : JSON.stringify(m.message);
+                        const nick = m.sender?.nickname ?? m.sender?.user_id ?? "?";
+                        return `[${new Date(m.time * 1000).toISOString()}] ${nick}: ${text.slice(0, 200)}`;
+                    });
+                    return { content: [{ type: "text", text: summary.join("\n") || "无历史消息", metadata: { count: msgs.length } }] };
+                }
                 const msgs = await getGroupMsgHistory(params.group_id, {
                     count: params.count ?? 50,
                     message_seq: params.message_seq,
                     message_id: params.message_id,
+                    reverse_order: true,
                 });
                 const summary = msgs.map((m) => {
                     const text = typeof m.message === "string" ? m.message : JSON.stringify(m.message);
@@ -150,6 +174,35 @@ export function registerTools(api) {
             }
         },
     });
+    api.registerTool({
+        name: "onebot_search_group_member",
+        description: "按名字模糊匹配群成员，返回匹配到的 QQ 号与展示名（群名片优先）。用于根据昵称/群名片查 QQ 号",
+        parameters: {
+            type: "object",
+            properties: {
+                group_id: { type: "number", description: "群号" },
+                name: { type: "string", description: "要搜索的名字（群名片或昵称，支持模糊匹配）" },
+            },
+            required: ["group_id", "name"],
+        },
+        async execute(_id, params) {
+            const w = getWs();
+            if (!w || w.readyState !== WebSocket.OPEN) {
+                return { content: [{ type: "text", text: "OneBot 未连接" }] };
+            }
+            try {
+                const list = await searchGroupMemberByName(params.group_id, params.name);
+                if (!list.length) {
+                    return { content: [{ type: "text", text: `未找到匹配「${params.name}」的群成员` }] };
+                }
+                const lines = list.map((m) => `QQ: ${m.user_id}  展示名: ${m.displayName}`);
+                return { content: [{ type: "text", text: lines.join("\n"), metadata: { count: list.length, matches: list } }] };
+            }
+            catch (e) {
+                return { content: [{ type: "text", text: `搜索失败: ${e?.message}` }] };
+            }
+        },
+    });
     api.registerTool({
         name: "onebot_run_script",
         description: "执行用户配置的 JS/TS 脚本（.mjs/.ts/.mts），脚本可调用 OneBot API（获取群历史、发图等）。用于定时任务中实现自定义逻辑（如 OG 图片生成、日报汇总）",

package/openclaw.plugin.json

@@ -1,10 +1,11 @@
 {
   "id": "openclaw-onebot",
   "name": "OneBot Channel",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "OneBot v11 protocol channel (QQ/Lagrange.Core via WebSocket)",
   "author": "Lagrange.Onebot",
   "channels": ["onebot"],
+  "commands": ["onebot"],
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
@@ -23,6 +24,26 @@
         "default": true,
         "description": "群聊是否必须 @ 机器人才回复"
       },
+      "whitelistUserIds": {
+        "type": "array",
+        "items": { "type": "number" },
+        "description": "白名单 QQ 号，非空时仅白名单内用户可触发 AI；为空则所有人可回复"
+      },
+      "renderMarkdownToPlain": {
+        "type": "boolean",
+        "default": true,
+        "description": "是否将机器人回复中的 Markdown 渲染为纯文本再发送（去除 **、# 等标记）"
+      },
+      "normalModeFlushIntervalMs": {
+        "type": "number",
+        "default": 1200,
+        "description": "normal 模式下聚合发送的等待窗口（毫秒）。块流式开启后，插件会在该时间窗口内合并回复再发送。"
+      },
+      "normalModeFlushChars": {
+        "type": "number",
+        "default": 160,
+        "description": "normal 模式下聚合发送的字符阈值。达到该长度会提前 flush，而不是继续等待时间窗口结束。"
+      },
       "groupIncrease": {
         "type": "object",
         "properties": {
@@ -31,9 +52,13 @@
             "type": "string",
             "description": "欢迎语模板。占位符：{name} 新成员昵称，{userId} QQ号，{groupName} 群名，{groupId} 群号，{avatarUrl} 头像链接"
           },
-          "handler": {
+          "command": {
+            "type": "string",
+            "description": "在 cwd 下用系统 shell 执行的命令。调用方自动追加 --userId、--username、--groupId 参数。命令可自行发送（如调用 openclaw message send），或向 stdout 输出 JSON 行供 handler 发送"
+          },
+          "cwd": {
             "type": "string",
-            "description": "自定义脚本路径（.mjs/.ts/.mts），接收 ctx，返回 { text?, imagePath?, imageUrl? }。TS 需安装 tsx。优先级高于 message"
+            "description": "命令执行的工作目录（绝对路径）"
           }
         }
       },
@@ -42,6 +67,31 @@
         "default": 60,
         "description": "表情 ID（Lagrange/QQ NT set_msg_emoji_like），收到消息时添加，回复完成后取消"
       },
+      "onReplySessionEnd": {
+        "type": "string",
+        "description": "回复会话结束时的钩子脚本路径（.mjs/.ts/.mts）。脚本接收 ctx: { replySessionId, sessionId, to, chunks, userMessage }，可对同一问题下的多次发送做统一处理（如日志、合并、上报等）"
+      },
+      "longMessageMode": {
+        "type": "string",
+        "enum": ["normal", "og_image", "forward"],
+        "default": "normal",
+        "description": "长消息处理模式：normal 正常发送；og_image 生成图片（需 node-html-to-image）；forward 合并转发"
+      },
+      "longMessageThreshold": {
+        "type": "number",
+        "default": 300,
+        "description": "长消息阈值（字符数），超过则启用 longMessageMode"
+      },
+      "ogImageRenderTheme": {
+        "type": "string",
+        "enum": ["default", "dust", "custom"],
+        "default": "default",
+        "description": "长消息 og_image 时的渲染主题：default 无额外样式，dust 内置 dust 样式，custom 时需填写 ogImageRenderThemePath"
+      },
+      "ogImageRenderThemePath": {
+        "type": "string",
+        "description": "当 ogImageRenderTheme 为 custom 时，填写 CSS 文件绝对路径"
+      },
       "cronJobs": {
         "type": "array",
         "description": "内置定时任务（无 AI 介入，直接执行脚本并推送到群聊）",
@@ -67,6 +117,11 @@
     "accessToken": { "label": "Access Token", "sensitive": true },
     "host": { "label": "主机地址", "placeholder": "127.0.0.1" },
     "port": { "label": "端口", "placeholder": "8080" },
-    "requireMention": { "label": "群聊需 @ 回复" }
+    "requireMention": { "label": "群聊需 @ 回复" },
+    "renderMarkdownToPlain": { "label": "Markdown 转纯文本" },
+    "normalModeFlushIntervalMs": { "label": "normal 聚合窗口(ms)" },
+    "normalModeFlushChars": { "label": "normal 提前发送阈值" },
+    "ogImageRenderTheme": { "label": "OG 图片渲染主题（default/dust/custom）" },
+    "ogImageRenderThemePath": { "label": "自定义 CSS 路径（仅当主题为 custom 时）" }
   }
 }

package/package.json

@@ -1,9 +1,11 @@
 {
   "name": "@kirigaya/openclaw-onebot",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "OneBot v11 protocol channel plugin for OpenClaw (QQ/Lagrange.Core/go-cqhttp)",
   "license": "MIT",
-  "publishConfig": { "access": "public" },
+  "publishConfig": {
+    "access": "public"
+  },
   "author": "LSTM-Kirigaya",
   "repository": {
     "type": "git",
@@ -26,13 +28,19 @@
   "exports": "./dist/index.js",
   "files": [
     "dist",
+    "themes",
     "skills",
     "openclaw.plugin.json",
     "README.md"
   ],
   "openclaw": {
-    "extensions": ["./dist/index.js"],
-    "skills": ["skills/onebot-ops", "skills/onebot-scripts"],
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "skills": [
+      "skills/onebot-ops",
+      "skills/onebot-scripts"
+    ],
     "channel": {
       "id": "onebot",
       "label": "OneBot",
@@ -40,33 +48,50 @@
       "docsPath": "/channels/onebot",
       "blurb": "OneBot v11 protocol via WebSocket (go-cqhttp, Lagrange.Core, etc.)",
       "order": 85,
-      "aliases": ["qq", "lagrange", "cqhttp"]
+      "aliases": [
+        "qq",
+        "lagrange",
+        "cqhttp"
+      ]
     }
   },
   "scripts": {
+    "openclaw": "openclaw",
     "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": {
-    "ws": "^8.17.0",
     "@clack/prompts": "^1.0.0",
+    "cron": "^4.4.0",
+    "fuse.js": "^7.1.0",
+    "highlight.js": "^11.10.0",
+    "marked": "^15.0.0",
     "tsx": "^4.0.0",
-    "cron": "^4.4.0"
+    "ws": "^8.17.0"
+  },
+  "optionalDependencies": {
+    "node-html-to-image": "^3.0.0"
   },
   "peerDependencies": {
-    "openclaw": "*",
     "clawdbot": "*"
   },
   "peerDependenciesMeta": {
-    "clawdbot": { "optional": true },
-    "openclaw": { "optional": true }
+    "clawdbot": {
+      "optional": true
+    },
+    "openclaw": {
+      "optional": true
+    }
   },
   "devDependencies": {
-    "typescript": "^5.4.0",
     "@types/node": "^22.0.0",
-    "@types/ws": "^8.5.10"
+    "@types/ws": "^8.5.10",
+    "typescript": "^5.4.0"
   },
   "engines": {
     "node": ">=22"

package/skills/onebot-ops/SKILL.md

@@ -46,16 +46,27 @@ openclaw plugins install ./openclaw-onebot
 | **图片消息** | message 为 `[{ type: "image", data: { file } }]` |
 | **delete_msg** | 撤回消息 |
 | **get_msg** | 获取单条消息 |
-| **get_group_msg_history** | 获取群历史（Lagrange.Core 扩展） |
+| **get_group_msg_history** | 获取群历史（Lagrange.Core 扩展），支持 reverse_order 分页 |
 | **upload_group_file** | 上传群文件 |
 | **upload_private_file** | 上传私聊文件 |
 | **set_msg_emoji_like** | 表情回应（Lagrange/QQ NT 扩展） |
 
-## 常用命令
+## Agent 工具与 CLI
+
+插件提供群历史、按名字搜 QQ 等能力，既注册为 **Agent 工具**（供 Cron/脚本/AI 调用），也提供等价的 **CLI 命令**，便于 AI 与人工按文档调用。
+
+**详细说明与所有命令用法见：[agent-tools.md](agent-tools.md)**
+
+### 常用 CLI 一览
 
 | 命令 | 说明 |
 |------|------|
 | `openclaw onebot setup` | 交互式配置 OneBot 连接 |
-| `openclaw message send --channel onebot --target group:xxx --message "hi"` | 发送群消息 |
+| `openclaw onebot get-group-msg-history --group-id <群号> [--hours N]` | 获取群历史（单页或最近 N 小时内，从旧到新） |
+| `openclaw onebot search-group-member --group-id <群号> --name <名字>` | 按名字模糊搜群友 QQ 号 |
+| `openclaw onebot upload-file --target group:<群号> --file <路径> --name <文件名>` | 上传文件到群/私聊 |
+| `openclaw message send --channel onebot --target group:xxx --message "hi"` | 发送文本/图片 |
 | `openclaw gateway status` | 查看 Gateway 状态 |
 | `openclaw logs --follow` | 查看日志 |
+
+AI 或脚本需要「获取群历史、查群友 QQ」时，应使用上述 CLI 或查阅 [agent-tools.md](agent-tools.md) 中的完整参数说明。

package/skills/onebot-ops/agent-tools.md

@@ -0,0 +1,116 @@
+# OneBot Agent 工具与 CLI
+
+插件通过 WebSocket 与 OneBot（Lagrange.Core / go-cqhttp）通信，提供 **Agent 工具**（供 Cron/脚本/AI 调用）和等价的 **CLI 命令**（供人工或工作流直接调用）。  
+AI 或脚本应优先使用 **CLI**，便于复现、调试和文档化。
+
+---
+
+## 前置条件
+
+- **Gateway 已启动**：`openclaw gateway`（或 `openclaw gateway run`）
+- OneBot 已运行并连接；若为正向 WS，CLI 会按配置自动建连
+- 配置：`openclaw.json` 的 `channels.onebot` 或环境变量 `ONEBOT_WS_*`
+
+---
+
+## 1. 获取群历史消息
+
+**Agent 工具**：`onebot_get_group_msg_history`  
+**CLI**：
+
+```bash
+openclaw onebot get-group-msg-history --group-id <群号> [--hours <N>] [--count 50] [--message-seq <序号>]
+```
+
+- 指定 **`--hours N`**：获取**从现在到过去 N 小时**内的消息（内部按时间范围分页拉取），例如 `--hours 24` 即过去 24 小时。
+- 不指定 `--hours`：按单页返回，始终**从旧到新**；分页时用上一批最早一条的 `message_seq` 作为 `--message-seq`。
+
+| 参数 | 说明 |
+|------|------|
+| `--group-id` | 群号（必填） |
+| `--hours` | 获取最近 N 小时内的消息（可选；指定后按时间范围拉取） |
+| `--count` | 条数，默认 50（未指定 --hours 时生效） |
+| `--message-seq` | 起始消息序号（可选，分页用，未指定 --hours 时生效） |
+
+示例：
+
+```bash
+openclaw onebot get-group-msg-history --group-id 123456789
+openclaw onebot get-group-msg-history --group-id 123456789 --hours 24
+openclaw onebot get-group-msg-history --group-id 123456789 --hours 1 --limit 500
+```
+
+---
+
+## 2. 按名字模糊搜索群成员（查 QQ 号）
+
+**Agent 工具**：`onebot_search_group_member`  
+**CLI**：
+
+```bash
+openclaw onebot search-group-member --group-id <群号> --name <名字>
+```
+
+| 参数 | 说明 |
+|------|------|
+| `--group-id` | 群号（必填） |
+| `--name` | 要搜的名字（群名片或昵称，模糊匹配） |
+
+输出：匹配到的 QQ 与展示名。
+
+示例：
+
+```bash
+openclaw onebot search-group-member --group-id 123456789 --name 小明
+```
+
+---
+
+## 3. 发送文本
+
+**Agent 工具**：`onebot_send_text`  
+**CLI**（推荐使用主命令）：
+
+```bash
+openclaw message send --channel onebot --target group:<群号> --message "内容"
+openclaw message send --channel onebot --target user:<QQ号> --message "内容"
+```
+
+---
+
+## 4. 发送图片
+
+**Agent 工具**：`onebot_send_image`  
+**CLI**：
+
+```bash
+openclaw message send --channel onebot --target group:<群号> --media "file:///path/to.png"
+openclaw message send --channel onebot --target user:<QQ号> --media "https://example.com/pic.jpg"
+```
+
+---
+
+## 5. 上传文件到群/私聊
+
+**Agent 工具**：`onebot_upload_file`  
+**CLI**：
+
+```bash
+openclaw onebot upload-file --target group:<群号> --file <本地绝对路径> --name <显示文件名>
+openclaw onebot upload-file --target user:<QQ号> --file <本地绝对路径> --name <显示文件名>
+```
+
+---
+
+## 6. 执行脚本（Cron 等）
+
+**Agent 工具**：`onebot_run_script`  
+**CLI**：无直接一对一命令，可由 Cron 或工作流调用脚本，脚本内使用上述 CLI 或 `onebotClient` API。
+
+---
+
+## 使用建议
+
+- **AI / 自动化**：优先使用上述 **CLI 命令**，便于在 Skill 中写明「如何调用」、可复现。
+- **Cron / 内置任务**：在 `openclaw.json` 的 `cronJobs` 中配置 `script`，脚本内通过 `onebotClient` 或子进程调用 CLI。
+- **临时查询**：直接运行 `openclaw onebot search-group-member ...` 等。