@kirigaya/openclaw-onebot 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LSTM-Kirigaya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,134 @@
+# openclaw-onebot
+
+将 **OneBot v11 协议**（QQ/Lagrange.Core、go-cqhttp 等）接入 [OpenClaw](https://openclaw.ai) Gateway 的渠道插件。
+
+[![npm version](https://img.shields.io/npm/v/openclaw-onebot.svg)](https://www.npmjs.com/package/openclaw-onebot)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+## 功能
+
+- ✅ 私聊：所有消息 AI 都会回复
+- ✅ 群聊：仅当用户 @ 机器人时回复（可配置）
+- ✅ 正向 / 反向 WebSocket 连接
+- ✅ TUI 配置向导：`openclaw onebot setup`
+- ✅ 新成员入群欢迎
+- ✅ 通过 `openclaw message send` CLI 发送（无 Agent 工具，降低 token 消耗）
+- ✅ **内置定时任务**：配置 `cronJobs` 后，在指定时间直接执行脚本并推送到群聊，**无需 AI 介入**
+
+## 安装
+
+```bash
+openclaw plugins install openclaw-onebot
+```
+
+或从 GitHub 安装：
+
+```bash
+openclaw plugins install https://github.com/LSTM-Kirigaya/openclaw-onebot.git
+```
+
+## 配置
+
+### 方式一：TUI 向导（推荐）
+
+```bash
+openclaw onebot setup
+```
+
+交互式输入：连接类型、主机、端口、Access Token。
+
+### 方式二：手动编辑 `~/.openclaw/openclaw.json`
+
+```json
+{
+  "channels": {
+    "onebot": {
+      "type": "forward-websocket",
+      "host": "127.0.0.1",
+      "port": 3001,
+      "accessToken": "可选",
+      "enabled": true,
+      "requireMention": true,
+      "groupIncrease": {
+        "enabled": true,
+        "message": "欢迎 {userId} 加入群聊！"
+      },
+      "cronJobs": [
+        {
+          "name": "每日科技新闻",
+          "cron": "0 8 * * *",
+          "timezone": "Asia/Shanghai",
+          "script": "./Tiphareth/src/openclaw/cron/daily-news.ts",
+          "groupIds": [782833642]
+        },
+        {
+          "name": "每日GitHub热榜",
+          "cron": "0 9 * * *",
+          "timezone": "Asia/Shanghai",
+          "script": "./Tiphareth/src/openclaw/cron/github-trending.ts",
+          "groupIds": [782833642]
+        }
+      ]
+    }
+  }
+}
+```
+
+**说明**：`cronJobs` 为内置定时任务，在指定时间**直接执行脚本**并推送到群聊，不经过 Agent，无 token 消耗。脚本路径相对 `process.cwd()`（通常为启动 OpenClaw 时的目录），请确保从项目根目录启动。
+
+### 连接类型
+
+| 类型 | 说明 |
+|------|------|
+| `forward-websocket` | 插件主动连接 OneBot（go-cqhttp、Lagrange.Core 正向 WS） |
+| `backward-websocket` | 插件作为服务端，OneBot 连接过来 |
+
+### 环境变量
+
+可替代配置文件，适用于 Lagrange 等：
+
+| 变量 | 说明 |
+|------|------|
+| `LAGRANGE_WS_TYPE` | forward-websocket / backward-websocket |
+| `LAGRANGE_WS_HOST` | 主机地址 |
+| `LAGRANGE_WS_PORT` | 端口 |
+| `LAGRANGE_WS_ACCESS_TOKEN` | 访问令牌 |
+
+## 使用
+
+1. 安装并配置
+2. 重启 Gateway：`openclaw gateway restart`
+3. 在 QQ 私聊或群聊中发消息（群聊需 @ 机器人）
+
+## 主动发送消息
+
+通过 `openclaw message send` CLI（无需 Agent 工具）：
+
+```bash
+# 发送文本
+openclaw message send --channel onebot --target user:123456789 --message "你好"
+
+# 发送图片
+openclaw message send --channel onebot --target group:987654321 --media "file:///path/to/image.png"
+```
+
+`--target` 格式：`user:QQ号` 或 `group:群号`。回复场景由 deliver 自动投递，Agent 输出 text/mediaUrl 即会送达。
+
+## 测试连接
+
+项目内提供测试脚本（需 `.env` 或环境变量）：
+
+```bash
+cd openclaw-onebot
+npm run test:connect
+```
+
+## 协议参考
+
+- [OneBot 11](https://github.com/botuniverse/onebot-11)
+- [go-cqhttp](https://docs.go-cqhttp.org/)
+- [Lagrange.Core](https://github.com/LSTM-Kirigaya/Lagrange.Core)
+
+## License
+
+MIT © [LSTM-Kirigaya](https://github.com/LSTM-Kirigaya)

package/dist/channel.d.ts

@@ -0,0 +1,100 @@
+/**
+ * OneBot Channel 插件定义
+ * 仿照 openclaw-feishu channel.ts 结构，接入 OneBot v11 协议（QQ/Lagrange.Core/go-cqhttp）
+ *
+ * 对应 Lagrange.onebot context.ts 的 API：
+ * - sendPrivateMsg / sendGroupMsg / sendMsg
+ * - sendGroupImage / sendPrivateImage（图片）
+ * - deleteMsg / getMsg / getGroupMsgHistory
+ * - uploadGroupFile / uploadPrivateFile
+ */
+declare function normalizeOneBotMessagingTarget(raw: string): string | undefined;
+export declare const OneBotChannelPlugin: {
+    id: string;
+    meta: {
+        id: string;
+        label: string;
+        selectionLabel: string;
+        docsPath: string;
+        blurb: string;
+        aliases: string[];
+        docsLabel: string;
+        order: number;
+    };
+    capabilities: {
+        chatTypes: readonly ["direct", "group"];
+        media: boolean;
+        reactions: boolean;
+        threads: boolean;
+        polls: boolean;
+    };
+    reload: {
+        configPrefixes: readonly ["channels.onebot"];
+    };
+    config: {
+        listAccountIds: (cfg: any) => string[];
+        resolveAccount: (cfg: any, accountId?: string) => any;
+    };
+    groups: {
+        resolveRequireMention: () => boolean;
+    };
+    messaging: {
+        normalizeTarget: typeof normalizeOneBotMessagingTarget;
+        targetResolver: {
+            looksLikeId: (raw: string) => boolean;
+            hint: string;
+        };
+    };
+    outbound: {
+        deliveryMode: "direct";
+        chunker: (text: string, limit: number) => string[];
+        chunkerMode: "text";
+        textChunkLimit: number;
+        resolveTarget: ({ to }: {
+            to?: string;
+        }) => {
+            ok: boolean;
+            error: Error;
+            to?: undefined;
+        } | {
+            ok: boolean;
+            to: string;
+            error?: undefined;
+        };
+        sendText: ({ to, text, accountId, cfg }: {
+            to: string;
+            text: string;
+            accountId?: string;
+            cfg?: any;
+        }) => Promise<{
+            channel: string;
+            ok: boolean;
+            messageId: string;
+            error: Error;
+        } | {
+            channel: string;
+            ok: boolean;
+            messageId: string;
+            error?: undefined;
+        }>;
+        sendMedia: (params: {
+            to: string;
+            text?: string;
+            mediaUrl?: string;
+            media?: string;
+            accountId?: string;
+            cfg?: any;
+        }) => Promise<{
+            channel: string;
+            ok: boolean;
+            messageId: string;
+            error: Error;
+        } | {
+            channel: string;
+            ok: boolean;
+            messageId: string;
+            error?: undefined;
+        }>;
+    };
+};
+export {};

package/dist/channel.js

@@ -0,0 +1,173 @@
+/**
+ * OneBot Channel 插件定义
+ * 仿照 openclaw-feishu channel.ts 结构，接入 OneBot v11 协议（QQ/Lagrange.Core/go-cqhttp）
+ *
+ * 对应 Lagrange.onebot context.ts 的 API：
+ * - sendPrivateMsg / sendGroupMsg / sendMsg
+ * - sendGroupImage / sendPrivateImage（图片）
+ * - deleteMsg / getMsg / getGroupMsgHistory
+ * - uploadGroupFile / uploadPrivateFile
+ */
+import { getOneBotConfig, listAccountIds } from "./config.js";
+import { sendTextMessage, sendMediaMessage } from "./send.js";
+const meta = {
+    id: "onebot",
+    label: "OneBot",
+    selectionLabel: "OneBot (QQ/Lagrange)",
+    docsPath: "/channels/onebot",
+    docsLabel: "onebot",
+    blurb: "OneBot v11 protocol via WebSocket (go-cqhttp, Lagrange.Core)",
+    aliases: ["qq", "lagrange", "cqhttp"],
+    order: 85,
+};
+function normalizeOneBotMessagingTarget(raw) {
+    const trimmed = raw?.trim();
+    if (!trimmed)
+        return undefined;
+    return trimmed.replace(/^(onebot|qq|lagrange):/i, "").trim();
+}
+function parseTarget(to) {
+    const t = to.replace(/^(onebot|qq|lagrange):/i, "").trim();
+    if (!t)
+        return null;
+    if (t.startsWith("group:")) {
+        const id = parseInt(t.slice(6), 10);
+        if (isNaN(id))
+            return null;
+        return { type: "group", id };
+    }
+    const rawId = t.replace(/^user:/, "");
+    const id = parseInt(rawId, 10);
+    if (isNaN(id))
+        return null;
+    if (rawId === t && !t.includes(":")) {
+        return { type: id > 100000000 ? "user" : "group", id };
+    }
+    return { type: "user", id };
+}
+export const OneBotChannelPlugin = {
+    id: "onebot",
+    meta: {
+        ...meta,
+        id: meta.id,
+        label: meta.label,
+        selectionLabel: meta.selectionLabel,
+        docsPath: meta.docsPath,
+        blurb: meta.blurb,
+        aliases: meta.aliases,
+    },
+    capabilities: {
+        chatTypes: ["direct", "group"],
+        media: true,
+        reactions: false,
+        threads: false,
+        polls: false,
+    },
+    reload: { configPrefixes: ["channels.onebot"] },
+    config: {
+        listAccountIds: (cfg) => listAccountIds(cfg),
+        resolveAccount: (cfg, accountId) => {
+            const id = accountId ?? "default";
+            const acc = cfg?.channels?.onebot?.accounts?.[id];
+            if (acc)
+                return { accountId: id, ...acc };
+            const ch = cfg?.channels?.onebot;
+            if (ch?.host)
+                return { accountId: id, ...ch };
+            return { accountId: id };
+        },
+    },
+    groups: {
+        resolveRequireMention: () => true,
+    },
+    messaging: {
+        normalizeTarget: normalizeOneBotMessagingTarget,
+        targetResolver: {
+            looksLikeId: (raw) => {
+                const trimmed = raw.trim();
+                if (!trimmed)
+                    return false;
+                return /^group:\d+$/.test(trimmed) || /^user:\d+$/.test(trimmed) || /^\d{6,}$/.test(trimmed);
+            },
+            hint: "user:<QQ号> 或 group:<群号>",
+        },
+    },
+    outbound: {
+        deliveryMode: "direct",
+        chunker: (text, limit) => {
+            if (!text)
+                return [];
+            if (limit <= 0 || text.length <= limit)
+                return [text];
+            const chunks = [];
+            let remaining = text;
+            while (remaining.length > limit) {
+                const window = remaining.slice(0, limit);
+                const lastNewline = window.lastIndexOf("\n");
+                const lastSpace = window.lastIndexOf(" ");
+                let breakIdx = lastNewline > 0 ? lastNewline : lastSpace;
+                if (breakIdx <= 0)
+                    breakIdx = limit;
+                const rawChunk = remaining.slice(0, breakIdx);
+                const chunk = rawChunk.trimEnd();
+                if (chunk.length > 0)
+                    chunks.push(chunk);
+                const brokeOnSeparator = breakIdx < remaining.length && /\s/.test(remaining[breakIdx]);
+                const nextStart = Math.min(remaining.length, breakIdx + (brokeOnSeparator ? 1 : 0));
+                remaining = remaining.slice(nextStart).trimStart();
+            }
+            if (remaining.length)
+                chunks.push(remaining);
+            return chunks;
+        },
+        chunkerMode: "text",
+        textChunkLimit: 4000,
+        resolveTarget: ({ to }) => {
+            const t = to?.trim();
+            if (!t)
+                return { ok: false, error: new Error("OneBot requires --to <user_id|group_id>") };
+            return { ok: true, to: t };
+        },
+        sendText: async ({ to, text, accountId, cfg }) => {
+            const api = cfg ? { config: cfg } : globalThis.__onebotApi;
+            const config = getOneBotConfig(api, accountId);
+            if (!config) {
+                return { channel: "onebot", ok: false, messageId: "", error: new Error("OneBot not configured") };
+            }
+            const getConfig = () => getOneBotConfig(api, accountId);
+            try {
+                const result = await sendTextMessage(to, text, getConfig);
+                if (!result.ok) {
+                    return { channel: "onebot", ok: false, messageId: "", error: new Error(result.error) };
+                }
+                return { channel: "onebot", ok: true, messageId: result.messageId ?? "" };
+            }
+            catch (e) {
+                return { channel: "onebot", ok: false, messageId: "", error: e instanceof Error ? e : new Error(String(e)) };
+            }
+        },
+        sendMedia: async (params) => {
+            const { to, text, accountId, cfg } = params;
+            const mediaUrl = params.mediaUrl ?? params.media;
+            const api = cfg ? { config: cfg } : globalThis.__onebotApi;
+            const config = getOneBotConfig(api, accountId);
+            if (!config) {
+                return { channel: "onebot", ok: false, messageId: "", error: new Error("OneBot not configured") };
+            }
+            if (!mediaUrl?.trim()) {
+                return { channel: "onebot", ok: false, messageId: "", error: new Error("mediaUrl is required") };
+            }
+            const getConfig = () => getOneBotConfig(api, accountId);
+            try {
+                const result = await sendMediaMessage(to, mediaUrl, text, getConfig);
+                if (!result.ok) {
+                    return { channel: "onebot", ok: false, messageId: "", error: new Error(result.error) };
+                }
+                return { channel: "onebot", ok: true, messageId: result.messageId ?? "" };
+            }
+            catch (e) {
+                return { channel: "onebot", ok: false, messageId: "", error: e instanceof Error ? e : new Error(String(e)) };
+            }
+        },
+    },
+};

package/dist/config.d.ts

@@ -0,0 +1,6 @@
+/**
+ * OneBot 配置解析
+ */
+import type { OneBotAccountConfig } from "./types.js";
+export declare function getOneBotConfig(api: any, accountId?: string): OneBotAccountConfig | null;
+export declare function listAccountIds(apiOrCfg: any): string[];

package/dist/config.js

@@ -0,0 +1,62 @@
+/**
+ * OneBot 配置解析
+ */
+export function getOneBotConfig(api, accountId) {
+    const cfg = api?.config ?? globalThis.__onebotGatewayConfig;
+    const id = accountId ?? "default";
+    const channel = cfg?.channels?.onebot;
+    const account = channel?.accounts?.[id];
+    if (account) {
+        const { type, host, port, accessToken, path } = account;
+        if (host && port) {
+            return {
+                accountId: id,
+                type: type ?? "forward-websocket",
+                host,
+                port,
+                accessToken,
+                path: path ?? "/onebot/v11/ws",
+                enabled: account.enabled !== false,
+            };
+        }
+    }
+    if (channel?.host && channel?.port) {
+        return {
+            accountId: id,
+            type: channel.type ?? "forward-websocket",
+            host: channel.host,
+            port: channel.port,
+            accessToken: channel.accessToken,
+            path: channel.path ?? "/onebot/v11/ws",
+        };
+    }
+    const type = process.env.LAGRANGE_WS_TYPE;
+    const host = process.env.LAGRANGE_WS_HOST;
+    const portStr = process.env.LAGRANGE_WS_PORT;
+    const accessToken = process.env.LAGRANGE_WS_ACCESS_TOKEN;
+    const path = process.env.LAGRANGE_WS_PATH ?? "/onebot/v11/ws";
+    if (host && portStr) {
+        const port = parseInt(portStr, 10);
+        if (Number.isFinite(port)) {
+            return {
+                accountId: id,
+                type: type === "backward-websocket" ? "backward-websocket" : "forward-websocket",
+                host,
+                port,
+                accessToken: accessToken || undefined,
+                path,
+            };
+        }
+    }
+    return null;
+}
+export function listAccountIds(apiOrCfg) {
+    const cfg = apiOrCfg?.config ?? apiOrCfg ?? globalThis.__onebotGatewayConfig;
+    const accounts = cfg?.channels?.onebot?.accounts;
+    if (accounts && Object.keys(accounts).length > 0) {
+        return Object.keys(accounts);
+    }
+    if (cfg?.channels?.onebot?.host)
+        return ["default"];
+    return [];
+}

package/dist/connection.d.ts

@@ -0,0 +1,94 @@
+/**
+ * OneBot WebSocket 连接与 API 调用
+ *
+ * 图片消息：网络 URL 会先下载到本地再发送（兼容 Lagrange.Core retcode 1200），
+ * 并定期清理临时文件。
+ */
+import WebSocket from "ws";
+import type { OneBotAccountConfig } from "./types.js";
+/** 启动临时图片定期清理（每小时执行一次） */
+export declare function startImageTempCleanup(): void;
+/** 停止临时图片定期清理 */
+export declare function stopImageTempCleanup(): void;
+export declare function handleEchoResponse(payload: any): boolean;
+export declare function getWs(): WebSocket | null;
+/** 等待 WebSocket 连接就绪（service 启动后异步建立连接，发送前需先等待） */
+export declare function waitForConnection(timeoutMs?: number): Promise<WebSocket>;
+/**
+ * 确保有可用的 WebSocket 连接。当 service 未启动时，
+ * forward-websocket 模式直接建立连接（message send 可独立运行）；
+ * backward-websocket 模式需等待 gateway 的 service 建立连接。
+ */
+export declare function ensureConnection(getConfig: () => OneBotAccountConfig | null, timeoutMs?: number): Promise<WebSocket>;
+export declare function sendPrivateMsg(userId: number, text: string, getConfig?: () => OneBotAccountConfig | null): Promise<number | undefined>;
+export declare function sendGroupMsg(groupId: number, text: string, getConfig?: () => OneBotAccountConfig | null): Promise<number | undefined>;
+export declare function sendGroupImage(groupId: number, image: string, log?: {
+    info?: (s: string) => void;
+    warn?: (s: string) => void;
+}, getConfig?: () => OneBotAccountConfig | null): Promise<number | undefined>;
+export declare function sendPrivateImage(userId: number, image: string, log?: {
+    info?: (s: string) => void;
+    warn?: (s: string) => void;
+}, getConfig?: () => OneBotAccountConfig | null): Promise<number | undefined>;
+export declare function uploadGroupFile(groupId: number, file: string, name: string): Promise<void>;
+export declare function uploadPrivateFile(userId: number, file: string, name: string): Promise<void>;
+/** 撤回消息 */
+export declare function deleteMsg(messageId: number): Promise<void>;
+/**
+ * 对消息进行表情回应（Lagrange/QQ NT 扩展 API）
+ * @param message_id 需要回应的消息 ID（用户发送的消息）
+ * @param emoji_id 表情 ID，1 通常为点赞
+ * @param is_set true 添加，false 取消
+ */
+export declare function setMsgEmojiLike(message_id: number, emoji_id: number, is_set?: boolean): Promise<void>;
+/** 获取陌生人信息（含 nickname） */
+export declare function getStrangerInfo(userId: number): Promise<{
+    nickname: string;
+} | null>;
+/** 获取群成员信息（含 nickname、card） */
+export declare function getGroupMemberInfo(groupId: number, userId: number): Promise<{
+    nickname: string;
+    card: string;
+} | null>;
+/** 获取群信息（含 group_name） */
+export declare function getGroupInfo(groupId: number): Promise<{
+    group_name: string;
+} | null>;
+/** QQ 头像 URL，s=640 为常用尺寸 */
+export declare function getAvatarUrl(userId: number, size?: number): string;
+/** 获取单条消息（需 OneBot 实现支持） */
+export declare function getMsg(messageId: number): Promise<{
+    time: number;
+    message_type: string;
+    message_id: number;
+    real_id: number;
+    sender: {
+        user_id?: number;
+        nickname?: string;
+    };
+    message: string | unknown[];
+} | null>;
+/**
+ * 获取群聊历史消息（Lagrange.Core 扩展 API，go-cqhttp 等可能不支持）
+ * @param groupId 群号
+ * @param opts message_seq 起始序号；message_id 起始消息 ID；count 数量
+ */
+export declare function getGroupMsgHistory(groupId: number, opts?: {
+    message_seq?: number;
+    message_id?: number;
+    count: number;
+}): Promise<Array<{
+    time: number;
+    message_type: string;
+    message_id: number;
+    real_id: number;
+    sender: {
+        user_id?: number;
+        nickname?: string;
+    };
+    message: string | unknown[];
+}>>;
+export declare function connectForward(config: OneBotAccountConfig): Promise<WebSocket>;
+export declare function createServerAndWait(config: OneBotAccountConfig): Promise<WebSocket>;
+export declare function setWs(socket: WebSocket | null): void;
+export declare function stopConnection(): void;