openclaw-channel-xiaozhu 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 OpenClaw Contributors
+
+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,143 @@
+# openclaw-channel-xiaozhu
+
+小助 — OpenClaw 通用渠道插件，通过标准 HTTP/SSE 接口将任意客户端接入 OpenClaw 对话引擎。与钉钉（`openclaw-channel-dingtalk`）、飞书（`openclaw-channel-feishu`）并列，是面向自定义客户端的通用接入渠道。
+
+## Features
+
+- 同步聊天 (`POST /api/chat`) 与 SSE 流式聊天 (`POST /api/chat/stream`)，流式响应支持文本合并
+- 滑动窗口限流 + 突发控制
+- 消息去重（TTL 集合）
+- 发送者白名单 (`allowFrom`)
+- 群聊支持 (`chatType: "group"`)
+- 多媒体消息：图片、音频、文件（base64 / URL）
+- 媒体文件托管 (`GET /api/media/:id`)
+- 语音转文字 (`POST /api/stt`，基于 Whisper)
+- 文字转语音 (`POST /api/tts`，基于 edge-tts)
+- Webhook 外发消息 (`POST /api/webhook/register`)
+- 可配置 CORS 来源
+- 常量时间 Token 比较（防时序攻击）
+
+## Quick Start
+
+### Prerequisites
+
+- Node.js >= 20
+- OpenClaw >= 2026.1
+
+### Install
+
+```bash
+npm install openclaw-channel-xiaozhu
+```
+
+### Build
+
+```bash
+npm run build
+```
+
+### Deploy
+
+将构建产物部署到 OpenClaw 插件目录，或在 `openclaw.json` 中注册本渠道即可。
+
+## Configuration
+
+在 `openclaw.json` 的 `channels` 中添加：
+
+```json
+{
+  "channels": [
+    {
+      "type": "channel-xiaozhu",
+      "config": {
+        "port": 3000,
+        "token": "your-secret-token",
+        "rateLimitWindowMs": 60000,
+        "rateLimitMax": 60,
+        "rateLimitBurst": 10,
+        "dedupTtlMs": 5000,
+        "allowFrom": ["*"],
+        "webhookUrl": "",
+        "allowOrigins": ["*"]
+      }
+    }
+  ]
+}
+```
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `port` | number | `3000` | HTTP 监听端口 |
+| `token` | string | — | 鉴权 Token（必填） |
+| `rateLimitWindowMs` | number | `60000` | 限流滑动窗口（毫秒） |
+| `rateLimitMax` | number | `60` | 窗口内最大请求数 |
+| `rateLimitBurst` | number | `10` | 突发请求上限 |
+| `dedupTtlMs` | number | `5000` | 消息去重 TTL（毫秒） |
+| `allowFrom` | string[] | `["*"]` | 允许的发送者 ID，`*` 表示全部 |
+| `webhookUrl` | string | `""` | Webhook 回调地址，为空则不启用 |
+| `allowOrigins` | string[] | `["*"]` | CORS 允许的来源 |
+
+## API Overview
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| `POST` | `/api/chat` | Yes | 同步聊天 |
+| `POST` | `/api/chat/stream` | Yes | SSE 流式聊天 |
+| `GET` | `/api/media/:id` | Yes | 获取媒体文件 |
+| `POST` | `/api/stt` | Yes | 语音转文字 |
+| `POST` | `/api/tts` | Yes | 文字转语音 |
+| `POST` | `/api/webhook/register` | Yes | 注册 Webhook |
+| `GET` | `/api/health` | No | 健康检查 |
+
+完整 API 文档见 [docs/API.md](docs/API.md)。
+
+## Environment Variables
+
+| 变量 | 说明 |
+|------|------|
+| `WHISPER_BIN` | Whisper 可执行文件路径，留空则从 PATH 查找 |
+| `EDGE_TTS_BIN` | edge-tts 可执行文件路径，留空则从 PATH 查找 |
+
+可复制 `.env.example` 为 `.env` 进行配置。
+
+## Development
+
+```bash
+git clone https://github.com/openclaw/openclaw-channel-xiaozhu.git
+cd openclaw-channel-xiaozhu
+npm install
+npm run build
+```
+
+### Project Structure
+
+```
+openclaw-channel-xiaozhu/
+├── src/
+│   ├── index.ts          # 插件入口
+│   ├── channel.ts        # Channel 插件对象（四个适配器）
+│   ├── server.ts         # HTTP 服务器（全功能）
+│   ├── types.ts          # 类型定义
+│   └── utils/
+│       ├── rate-limiter.ts  # 滑动窗口速率限制器
+│       ├── ttl-set.ts       # TTL 集合（消息去重）
+│       └── coalescer.ts     # SSE 文本合并缓冲
+├── openclaw.plugin.json  # 插件声明
+├── tsconfig.json
+└── package.json
+```
+
+## Architecture
+
+本插件实现 OpenClaw 渠道接口的四个适配器：
+
+1. **Config** — 读取并校验渠道配置，合并默认值
+2. **Gateway** — 启动 HTTP 服务，处理入站消息，转发至 OpenClaw 对话引擎
+3. **Outbound** — 将引擎回复通过 Webhook 推送到外部系统
+4. **Status** — 暴露 `/api/health`，报告运行时间、请求统计、限流状态
+
+消息流：`客户端 → Gateway → OpenClaw Engine → Outbound → Webhook`
+
+## License
+
+[MIT](LICENSE)

package/dist/channel.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Channel 插件对象 — config / gateway / outbound / status 四个适配器
+ */
+import type { HttpApiAccount, PluginRuntime, ChannelConfig, GatewayContext } from "./types.js";
+export declare function setRuntime(rt: PluginRuntime): void;
+export declare const httpChannelPlugin: {
+    id: string;
+    meta: {
+        id: string;
+        label: string;
+        selectionLabel: string;
+        blurb: string;
+        order: number;
+        aliases: string[];
+    };
+    capabilities: {
+        chatTypes: readonly ["direct", "group"];
+        reactions: boolean;
+        threads: boolean;
+        media: boolean;
+        nativeCommands: boolean;
+        blockStreaming: boolean;
+    };
+    config: {
+        listAccountIds: (cfg: ChannelConfig) => string[];
+        resolveAccount: (cfg: ChannelConfig, accountId: string) => HttpApiAccount;
+        defaultAccountId: (_cfg: ChannelConfig) => string;
+        isConfigured: (account: HttpApiAccount) => boolean;
+        describeAccount: (account: HttpApiAccount) => {
+            accountId: string;
+            name: string;
+            enabled: boolean;
+            configured: boolean;
+        };
+        setAccountEnabled: ({ cfg, accountId, enabled }: {
+            cfg: ChannelConfig;
+            accountId: string;
+            enabled: boolean;
+        }) => {
+            channels: {
+                "channel-xiaozhu": {
+                    enabled: boolean;
+                };
+            };
+        };
+        deleteAccount: ({ cfg, accountId }: {
+            cfg: ChannelConfig;
+            accountId: string;
+        }) => {
+            channels: {
+                [x: string]: Record<string, unknown>;
+            };
+        };
+    };
+    gateway: {
+        startAccount: (ctx: GatewayContext) => Promise<void>;
+    };
+    outbound: {
+        deliveryMode: "direct";
+        textChunkLimit: number;
+        sendText: (opts: Record<string, unknown>) => Promise<{
+            channel: string;
+            ok: boolean;
+            error: Error;
+        } | {
+            channel: string;
+            ok: boolean;
+            error?: undefined;
+        }>;
+        sendMedia: (opts: Record<string, unknown>) => Promise<{
+            channel: string;
+            ok: boolean;
+            error: Error;
+        } | {
+            channel: string;
+            ok: boolean;
+            error?: undefined;
+        }>;
+    };
+    status: {
+        defaultRuntime: {
+            accountId: string;
+            running: boolean;
+            connected: boolean;
+            lastStartAt: null;
+            lastError: null;
+        };
+        probeAccount: ({ account }: {
+            account: HttpApiAccount;
+            timeoutMs?: number;
+        }) => Promise<{
+            ok: boolean;
+            latencyMs: number;
+        }>;
+    };
+};

package/dist/channel.js

@@ -0,0 +1,225 @@
+/**
+ * Channel 插件对象 — config / gateway / outbound / status 四个适配器
+ */
+import { startHttpServer, getRuntimeWebhookUrl } from "./server.js";
+const CHANNEL_ID = "channel-xiaozhu";
+const DEFAULT_PORT = 18800;
+let pluginRuntime = null;
+export function setRuntime(rt) {
+    pluginRuntime = rt;
+}
+function getChannelConfig(cfg) {
+    return cfg?.channels?.[CHANNEL_ID] || {};
+}
+export const httpChannelPlugin = {
+    id: CHANNEL_ID,
+    meta: {
+        id: CHANNEL_ID,
+        label: "小助",
+        selectionLabel: "小助",
+        blurb: "通过 HTTP/SSE 接口接入对话的通用渠道",
+        order: 90,
+        aliases: ["xiaozhu", "http", "api", "rest"],
+    },
+    capabilities: {
+        chatTypes: ["direct", "group"],
+        reactions: false,
+        threads: false,
+        media: true,
+        nativeCommands: false,
+        blockStreaming: true,
+    },
+    // ── config 适配器 ──
+    config: {
+        listAccountIds: (cfg) => {
+            const ch = getChannelConfig(cfg);
+            if (ch && typeof ch === "object" && !Array.isArray(ch)) {
+                return ["default"];
+            }
+            return [];
+        },
+        resolveAccount: (cfg, accountId) => {
+            const ch = getChannelConfig(cfg);
+            return {
+                accountId,
+                enabled: ch.enabled !== false,
+                port: ch.port || DEFAULT_PORT,
+                token: ch.token || "",
+                rateLimitWindowMs: ch.rateLimitWindowMs,
+                rateLimitMax: ch.rateLimitMax,
+                rateLimitBurst: ch.rateLimitBurst,
+                dedupTtlMs: ch.dedupTtlMs,
+                allowFrom: ch.allowFrom,
+                webhookUrl: ch.webhookUrl,
+                allowOrigins: ch.allowOrigins,
+            };
+        },
+        defaultAccountId: (_cfg) => "default",
+        isConfigured: (account) => {
+            return !!account.token;
+        },
+        describeAccount: (account) => ({
+            accountId: account.accountId,
+            name: `HTTP API :${account.port}`,
+            enabled: account.enabled,
+            configured: !!account.token,
+        }),
+        setAccountEnabled: ({ cfg, accountId, enabled }) => {
+            const ch = getChannelConfig(cfg) || {};
+            return { ...cfg, channels: { ...cfg.channels, [CHANNEL_ID]: { ...ch, enabled } } };
+        },
+        deleteAccount: ({ cfg, accountId }) => {
+            const channels = { ...cfg.channels };
+            delete channels[CHANNEL_ID];
+            return { ...cfg, channels };
+        },
+    },
+    // ── gateway 适配器 ──
+    gateway: {
+        startAccount: async (ctx) => {
+            const account = ctx.account;
+            const { abortSignal, log } = ctx;
+            ctx.setStatus({
+                accountId: account.accountId,
+                running: true,
+                connected: false,
+                lastStartAt: Date.now(),
+            });
+            const rt = pluginRuntime || ctx.runtime;
+            const cfg = ctx.cfg;
+            try {
+                await startHttpServer({
+                    port: account.port,
+                    token: account.token,
+                    accountId: account.accountId,
+                    account,
+                    runtime: rt,
+                    config: cfg,
+                    log,
+                    abortSignal,
+                    onReady: () => {
+                        ctx.setStatus({ accountId: account.accountId, connected: true });
+                    },
+                });
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                log.error(`[${CHANNEL_ID}] Failed to start HTTP server:`, msg);
+                ctx.setStatus({
+                    accountId: account.accountId,
+                    running: false,
+                    connected: false,
+                    lastError: msg,
+                });
+                return;
+            }
+            // 等待关闭信号
+            await new Promise((resolve) => {
+                abortSignal.addEventListener("abort", () => resolve(), { once: true });
+            });
+            ctx.setStatus({
+                accountId: account.accountId,
+                running: false,
+                connected: false,
+            });
+        },
+    },
+    // ── outbound 适配器 ──
+    outbound: {
+        deliveryMode: "direct",
+        textChunkLimit: 4000,
+        sendText: async (opts) => {
+            const account = opts?.account;
+            const text = opts?.text || "";
+            const session = opts?.session || opts?.to || "";
+            // 优先使用运行时注册的 webhook，其次使用配置的 webhook
+            const webhookUrl = getRuntimeWebhookUrl() || account?.webhookUrl;
+            if (!webhookUrl) {
+                return { channel: CHANNEL_ID, ok: false, error: new Error("HTTP API channel is passive; configure webhookUrl or register via /api/webhook/register") };
+            }
+            try {
+                const payload = JSON.stringify({
+                    type: "text",
+                    text,
+                    session,
+                    from: "openclaw",
+                    channel: CHANNEL_ID,
+                    timestamp: Date.now(),
+                });
+                const res = await fetch(webhookUrl, {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/json",
+                        "Authorization": `Bearer ${account?.token || ""}`,
+                    },
+                    body: payload,
+                    signal: AbortSignal.timeout(10000),
+                });
+                if (!res.ok) {
+                    return { channel: CHANNEL_ID, ok: false, error: new Error(`Webhook returned ${res.status}`) };
+                }
+                return { channel: CHANNEL_ID, ok: true };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return { channel: CHANNEL_ID, ok: false, error: new Error(`Webhook failed: ${msg}`) };
+            }
+        },
+        sendMedia: async (opts) => {
+            const account = opts?.account;
+            const mediaUrl = opts?.mediaUrl || "";
+            const session = opts?.session || opts?.to || "";
+            const webhookUrl = getRuntimeWebhookUrl() || account?.webhookUrl;
+            if (!webhookUrl) {
+                return { channel: CHANNEL_ID, ok: false, error: new Error("No webhookUrl configured for media delivery") };
+            }
+            try {
+                const payload = JSON.stringify({
+                    type: "media",
+                    mediaUrl,
+                    session,
+                    from: "openclaw",
+                    channel: CHANNEL_ID,
+                    timestamp: Date.now(),
+                });
+                const res = await fetch(webhookUrl, {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/json",
+                        "Authorization": `Bearer ${account?.token || ""}`,
+                    },
+                    body: payload,
+                    signal: AbortSignal.timeout(10000),
+                });
+                if (!res.ok) {
+                    return { channel: CHANNEL_ID, ok: false, error: new Error(`Webhook returned ${res.status}`) };
+                }
+                return { channel: CHANNEL_ID, ok: true };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return { channel: CHANNEL_ID, ok: false, error: new Error(`Webhook media failed: ${msg}`) };
+            }
+        },
+    },
+    // ── status 适配器 ──
+    status: {
+        defaultRuntime: {
+            accountId: "default",
+            running: false,
+            connected: false,
+            lastStartAt: null,
+            lastError: null,
+        },
+        probeAccount: async ({ account }) => {
+            try {
+                const res = await fetch(`http://127.0.0.1:${account.port}/api/health`, { signal: AbortSignal.timeout(3000) });
+                const data = await res.json();
+                return { ok: data?.ok === true, latencyMs: 0 };
+            }
+            catch {
+                return { ok: false, latencyMs: 0 };
+            }
+        },
+    },
+};

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * OpenClaw 小助渠道插件 — 入口
+ */
+import type { PluginApi } from "./types.js";
+declare const plugin: {
+    id: string;
+    name: string;
+    description: string;
+    register(api: PluginApi): void;
+};
+export default plugin;

package/dist/index.js

@@ -0,0 +1,15 @@
+/**
+ * OpenClaw 小助渠道插件 — 入口
+ */
+import { httpChannelPlugin, setRuntime } from "./channel.js";
+const plugin = {
+    id: "channel-xiaozhu",
+    name: "小助",
+    description: "小助 — 通过 HTTP/SSE 接口接入 OpenClaw 对话的通用渠道",
+    register(api) {
+        setRuntime(api.runtime);
+        api.registerChannel({ plugin: httpChannelPlugin });
+        api.logger.info("[channel-xiaozhu] 小助渠道插件已注册");
+    },
+};
+export default plugin;

package/dist/server.d.ts

@@ -0,0 +1,24 @@
+/**
+ * HTTP 服务器 — SSE 流式、速率限制、去重、allowFrom、群聊、webhook、增强健康检查
+ */
+import { type Server } from "node:http";
+import type { HttpApiAccount } from "./types.js";
+interface ServerOptions {
+    port: number;
+    token: string;
+    accountId: string;
+    account: HttpApiAccount;
+    runtime: Record<string, any>;
+    config: Record<string, unknown>;
+    log: {
+        info: (...a: unknown[]) => void;
+        warn: (...a: unknown[]) => void;
+        error: (...a: unknown[]) => void;
+    };
+    abortSignal: AbortSignal;
+    onReady?: () => void;
+}
+export declare function startHttpServer(opts: ServerOptions): Promise<Server>;
+/** 获取当前运行时 webhook URL（供 outbound 适配器使用） */
+export declare function getRuntimeWebhookUrl(): string | null;
+export {};