openclaw-channel-openilink 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 openilink
+
+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,148 @@
+# openclaw-channel-openilink
+
+[OpenClaw](https://github.com/openclaw/openclaw) 的 Channel 插件，通过 [OpeniLink Hub](https://github.com/openilink/openilink-hub) 接入微信 Bot。
+
+安装后，OpenClaw AI 可以通过 Hub 管理的微信 Bot 收发消息。
+
+## 工作原理
+
+```
+OpenClaw AI 助手
+    ↕ （插件 SDK）
+[openclaw-channel-openilink]
+    ↕ （WebSocket + HTTP）
+OpeniLink Hub Bot API
+    ↕ （iLink 协议）
+微信 ClawBot
+```
+
+- **收消息**：微信用户发消息 → Hub 通过 WebSocket 推送给插件 → 插件转发给 OpenClaw AI 处理
+- **发消息**：OpenClaw AI 生成回复 → 插件调 Hub Bot API 发送 → Hub 通过 Bot 发到微信
+
+## 安装
+
+```bash
+npm config set @openilink:registry https://npm.pkg.github.com && openclaw plugins install @openilink/openclaw-channel-openilink
+```
+
+## 配置
+
+### 前置步骤
+
+1. 部署或访问一个 [OpeniLink Hub](https://github.com/openilink/openilink-hub) 实例
+2. 在 Hub 上安装 **OpenClaw** App 到你的 Bot（应用市场 → OpenClaw → 安装）
+3. 在安装详情页复制 **Token**
+
+### 单账户
+
+编辑 OpenClaw 配置文件（`openclaw.yaml`）：
+
+```yaml
+channels:
+  openilink:
+    hub_url: "https://hub.openilink.com"
+    app_token: "app_你的token"
+```
+
+### 多账户
+
+连接多个 Hub Bot（不同 Bot 或不同 Hub 实例）：
+
+```yaml
+channels:
+  openilink:
+    accounts:
+      sales-bot:
+        hub_url: "https://hub.openilink.com"
+        app_token: "app_销售bot的token"
+      support-bot:
+        hub_url: "https://hub.openilink.com"
+        app_token: "app_客服bot的token"
+```
+
+每个账户维护独立的 WebSocket 连接，互不干扰。
+
+### 重启 OpenClaw
+
+```bash
+openclaw restart
+```
+
+配置完成后，微信消息会自动转发到 OpenClaw AI 处理。
+
+## 配置参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `hub_url` | string | 是 | OpeniLink Hub 地址（如 `https://hub.openilink.com`） |
+| `app_token` | string | 是 | 从 Hub 安装 OpenClaw App 后获取的 Token |
+
+## 功能
+
+- **实时消息** — 通过 WebSocket 持久连接接收 Hub 消息
+- **自动重连** — 断线后 5 秒自动重连
+- **私聊/群聊** — 支持直接对话和群组消息
+- **媒体消息** — 支持通过 Hub Bot API 发送图片
+- **多账户** — 同时连接多个 Bot
+- **链路追踪** — Trace ID 端到端传递，方便调试
+
+## 开发
+
+```bash
+git clone https://github.com/openilink/openclaw-channel-openilink.git
+cd openclaw-channel-openilink
+npm install
+npm run build
+
+# 本地开发链接
+openclaw plugins install --link .
+```
+
+## 相关链接
+
+- [OpeniLink Hub](https://github.com/openilink/openilink-hub) — 微信 Bot 消息管理平台
+- [OpenClaw](https://github.com/openclaw/openclaw) — 开源 AI 助手
+- [OpenClaw 插件文档](https://docs.openclaw.ai/tools/plugin) — 插件开发指南
+
+## License
+
+MIT
+
+---
+
+## English
+
+OpenClaw channel plugin for [OpeniLink Hub](https://github.com/openilink/openilink-hub) — bridge OpenClaw AI to WeChat bots.
+
+### Quick Start
+
+```bash
+npm config set @openilink:registry https://npm.pkg.github.com && openclaw plugins install @openilink/openclaw-channel-openilink
+```
+
+Configure `openclaw.yaml`:
+
+```yaml
+channels:
+  openilink:
+    hub_url: "https://hub.openilink.com"
+    app_token: "your_app_token"
+```
+
+Then `openclaw restart`.
+
+### How to Get Your Token
+
+1. Log into your OpeniLink Hub
+2. Go to your Bot → App Marketplace → Install **OpenClaw** app
+3. Copy the **Token** from the installation detail page
+4. Paste into your OpenClaw config
+
+### Features
+
+- Real-time messaging via WebSocket
+- Auto-reconnect (5s backoff)
+- Direct and group chat support
+- Media messages (images)
+- Multi-account support
+- Trace ID propagation

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+declare const _default: {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: import("openclaw/plugin-sdk").OpenClawPluginConfigSchema;
+    register: NonNullable<import("openclaw/plugin-sdk/core").OpenClawPluginDefinition["register"]>;
+} & Pick<import("openclaw/plugin-sdk/core").OpenClawPluginDefinition, "kind">;
+export default _default;

package/dist/index.js

@@ -0,0 +1,10 @@
+import { defineChannelPluginEntry } from "openclaw/plugin-sdk/core";
+import { openiLinkChannel } from "./src/channel.js";
+import { setPluginRuntime } from "./src/runtime.js";
+export default defineChannelPluginEntry({
+    id: "openilink",
+    name: "OpeniLink Hub",
+    description: "Bridge WeChat bots via OpeniLink Hub",
+    plugin: openiLinkChannel,
+    setRuntime: setPluginRuntime,
+});

package/dist/src/channel.d.ts

@@ -0,0 +1,34 @@
+import type { OpeniLinkConfig } from "./types.js";
+import { startAccount, stopAccount } from "./gateway.js";
+export declare const openiLinkChannel: {
+    id: any;
+    meta: {
+        id: any;
+        label: string;
+        selectionLabel: string;
+        docsPath: string;
+        blurb: string;
+    };
+    capabilities: {
+        chatTypes: Array<"direct" | "group">;
+        media: boolean;
+    };
+    config: {
+        listAccountIds: (cfg: any) => string[];
+        resolveAccount: (cfg: any, accountId?: string | null) => OpeniLinkConfig;
+        isConfigured: (account: OpeniLinkConfig) => boolean;
+        describeAccount: (account: OpeniLinkConfig) => {
+            status: string;
+            label: string;
+        };
+    };
+    gateway: {
+        startAccount: typeof startAccount;
+        stopAccount: typeof stopAccount;
+    };
+    outbound: {
+        deliveryMode: "direct";
+        sendText(ctx: any): Promise<any>;
+        sendMedia(ctx: any): Promise<any>;
+    };
+};

package/dist/src/channel.js

@@ -0,0 +1,31 @@
+import { resolveConfig, listAccountIds } from "./config.js";
+import { startAccount, stopAccount } from "./gateway.js";
+import { createOutboundAdapter } from "./outbound.js";
+export const openiLinkChannel = {
+    id: "openilink",
+    meta: {
+        id: "openilink",
+        label: "OpeniLink Hub",
+        selectionLabel: "OpeniLink Hub (WeChat Bridge)",
+        docsPath: "channels/openilink",
+        blurb: "Send and receive WeChat messages via OpeniLink Hub",
+    },
+    capabilities: {
+        chatTypes: ["direct", "group"],
+        media: true,
+    },
+    config: {
+        listAccountIds: (cfg) => listAccountIds(cfg),
+        resolveAccount: (cfg, accountId) => resolveConfig(cfg, accountId),
+        isConfigured: (account) => !!(account.hubUrl && account.appToken),
+        describeAccount: (account) => ({
+            status: account.hubUrl ? "configured" : "unconfigured",
+            label: account.hubUrl || "Not configured",
+        }),
+    },
+    gateway: {
+        startAccount,
+        stopAccount,
+    },
+    outbound: createOutboundAdapter(resolveConfig),
+};

package/dist/src/config.d.ts

@@ -0,0 +1,4 @@
+import type { OpeniLinkConfig } from "./types.js";
+export declare function resolveConfig(cfg: any, accountId?: string | null): OpeniLinkConfig;
+export declare function listAccountIds(cfg: any): string[];
+export declare function isConfigured(cfg: any, accountId?: string | null): boolean;

package/dist/src/config.js

@@ -0,0 +1,30 @@
+export function resolveConfig(cfg, accountId) {
+    const channelCfg = cfg?.channels?.openilink || {};
+    // Support multi-account
+    if (accountId && channelCfg.accounts?.[accountId]) {
+        const account = channelCfg.accounts[accountId];
+        return {
+            hubUrl: (account.hub_url || channelCfg.hub_url || "").replace(/\/$/, ""),
+            appToken: account.app_token || channelCfg.app_token || "",
+        };
+    }
+    return {
+        hubUrl: (channelCfg.hub_url || "").replace(/\/$/, ""),
+        appToken: channelCfg.app_token || "",
+    };
+}
+export function listAccountIds(cfg) {
+    const channelCfg = cfg?.channels?.openilink || {};
+    if (channelCfg.accounts) {
+        return Object.keys(channelCfg.accounts);
+    }
+    // Single account mode — return default ID
+    if (channelCfg.hub_url && channelCfg.app_token) {
+        return ["default"];
+    }
+    return [];
+}
+export function isConfigured(cfg, accountId) {
+    const resolved = resolveConfig(cfg, accountId);
+    return !!(resolved.hubUrl && resolved.appToken);
+}

package/dist/src/gateway.d.ts

@@ -0,0 +1,2 @@
+export declare function startAccount(ctx: any): Promise<void>;
+export declare function stopAccount(ctx: any): Promise<void>;

package/dist/src/gateway.js

@@ -0,0 +1,71 @@
+import WebSocket from "ws";
+import { handleInboundEvent } from "./inbound.js";
+const connections = new Map();
+export async function startAccount(ctx) {
+    const { accountId, account, cfg, abortSignal, setStatus } = ctx;
+    const config = account;
+    if (!config.hubUrl || !config.appToken) {
+        setStatus({ status: "error", error: "Missing hub_url or app_token" });
+        return;
+    }
+    const wsUrl = `${config.hubUrl.replace(/^http/, "ws")}/bot/v1/ws?token=${config.appToken}`;
+    function connect() {
+        if (abortSignal.aborted)
+            return;
+        const ws = new WebSocket(wsUrl);
+        connections.set(accountId, ws);
+        ws.on("open", () => {
+            setStatus({ status: "connected" });
+            console.log(`[openilink] Connected to Hub: ${config.hubUrl}`);
+        });
+        ws.on("message", (data) => {
+            try {
+                const msg = JSON.parse(data.toString());
+                if (msg.type === "init") {
+                    console.log(`[openilink] Init: bot=${msg.data.bot_id}, app=${msg.data.app_slug}`);
+                    return;
+                }
+                if (msg.type === "event") {
+                    handleInboundEvent(msg, config, cfg, accountId);
+                    return;
+                }
+                if (msg.type === "pong")
+                    return;
+            }
+            catch (err) {
+                console.error("[openilink] Parse error:", err);
+            }
+        });
+        ws.on("close", () => {
+            connections.delete(accountId);
+            setStatus({ status: "disconnected" });
+            // Reconnect after 5s
+            if (!abortSignal.aborted) {
+                setTimeout(connect, 5000);
+            }
+        });
+        ws.on("error", (err) => {
+            console.error("[openilink] WS error:", err.message);
+            setStatus({ status: "error", error: err.message });
+        });
+        // Ping every 30s
+        const pingInterval = setInterval(() => {
+            if (ws.readyState === WebSocket.OPEN) {
+                ws.send(JSON.stringify({ type: "ping" }));
+            }
+        }, 30000);
+        ws.on("close", () => clearInterval(pingInterval));
+        abortSignal.addEventListener("abort", () => {
+            clearInterval(pingInterval);
+            ws.close();
+        });
+    }
+    connect();
+}
+export async function stopAccount(ctx) {
+    const ws = connections.get(ctx.accountId);
+    if (ws) {
+        ws.close();
+        connections.delete(ctx.accountId);
+    }
+}

package/dist/src/inbound.d.ts

@@ -0,0 +1,2 @@
+import type { HubWSEvent, OpeniLinkConfig } from "./types.js";
+export declare function handleInboundEvent(event: HubWSEvent, config: OpeniLinkConfig, cfg: any, accountId: string): Promise<void>;

package/dist/src/inbound.js

@@ -0,0 +1,97 @@
+import { getPluginRuntime } from "./runtime.js";
+export async function handleInboundEvent(event, config, cfg, accountId) {
+    const rt = getPluginRuntime();
+    if (!rt?.channel)
+        return;
+    const eventData = event.event.data;
+    const sender = eventData.sender;
+    const group = eventData.group;
+    const content = eventData.content || "";
+    const senderId = sender?.id || "unknown";
+    const senderName = sender?.name || senderId;
+    const isDirect = !group;
+    const peerId = isDirect ? senderId : group.id;
+    // Resolve agent route
+    const route = rt.channel.routing.resolveAgentRoute({
+        cfg,
+        channel: "openilink",
+        accountId,
+        peer: { kind: isDirect ? "direct" : "group", id: peerId },
+    });
+    // Format inbound envelope
+    const envelopeOptions = rt.channel.reply.resolveEnvelopeFormatOptions(cfg);
+    const body = rt.channel.reply.formatInboundEnvelope({
+        channel: "OpeniLink",
+        from: senderName,
+        timestamp: event.event.timestamp * 1000,
+        body: content,
+        chatType: isDirect ? "direct" : "group",
+        sender: { name: senderName, id: senderId },
+        envelope: envelopeOptions,
+    });
+    // Build inbound context
+    const ctx = rt.channel.reply.finalizeInboundContext({
+        Body: body,
+        RawBody: content,
+        CommandBody: content,
+        From: peerId,
+        To: peerId,
+        SessionKey: route.sessionKey,
+        AccountId: accountId,
+        ChatType: isDirect ? "direct" : "group",
+        SenderName: senderName,
+        SenderId: senderId,
+        Provider: "openilink",
+        Surface: "openilink",
+        MessageSid: event.event.id || `${event.trace_id}-${Date.now()}`,
+        Timestamp: event.event.timestamp * 1000,
+        CommandAuthorized: true,
+        OriginatingChannel: "openilink",
+        OriginatingTo: peerId,
+    });
+    // Record inbound session
+    const storePath = rt.channel.session.resolveStorePath(`openilink/${accountId}`);
+    await rt.channel.session.recordInboundSession({
+        storePath,
+        sessionKey: route.sessionKey,
+        ctx,
+        onRecordError: (err) => {
+            console.error("[openilink] Session record error:", err);
+        },
+    });
+    // Dispatch to AI and deliver response
+    await rt.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+        ctx,
+        cfg,
+        dispatcherOptions: {
+            responsePrefix: "",
+            deliver: async (payload) => {
+                // Send AI response back to Hub
+                if (payload.text) {
+                    await sendToHub(config, payload.text, event.trace_id);
+                }
+                if (payload.mediaUrl) {
+                    await sendToHub(config, payload.mediaUrl, event.trace_id);
+                }
+            },
+        },
+        replyOptions: {},
+    });
+}
+async function sendToHub(config, content, traceId) {
+    const body = { content };
+    if (traceId)
+        body.trace_id = traceId;
+    const resp = await fetch(`${config.hubUrl}/bot/v1/message/send`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${config.appToken}`,
+        },
+        body: JSON.stringify(body),
+    });
+    if (!resp.ok) {
+        const text = await resp.text();
+        console.error(`[openilink] Send failed: ${resp.status} ${text}`);
+    }
+}

package/dist/src/outbound.d.ts

@@ -0,0 +1,6 @@
+import type { OpeniLinkConfig } from "./types.js";
+export declare function createOutboundAdapter(resolveConfig: (cfg: any, accountId?: string | null) => OpeniLinkConfig): {
+    deliveryMode: "direct";
+    sendText(ctx: any): Promise<any>;
+    sendMedia(ctx: any): Promise<any>;
+};

package/dist/src/outbound.js

@@ -0,0 +1,43 @@
+export function createOutboundAdapter(resolveConfig) {
+    return {
+        deliveryMode: "direct",
+        async sendText(ctx) {
+            const config = resolveConfig(ctx.cfg, ctx.accountId);
+            const body = { content: ctx.text };
+            const resp = await fetch(`${config.hubUrl}/bot/v1/message/send`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${config.appToken}`,
+                },
+                body: JSON.stringify(body),
+            });
+            if (!resp.ok) {
+                return { ok: false, error: `Hub returned ${resp.status}` };
+            }
+            const result = await resp.json();
+            return { ok: true, messageId: result.client_id };
+        },
+        async sendMedia(ctx) {
+            const config = resolveConfig(ctx.cfg, ctx.accountId);
+            const body = {
+                content: ctx.text || "",
+                type: "image",
+                url: ctx.mediaUrl || "",
+            };
+            const resp = await fetch(`${config.hubUrl}/bot/v1/message/send`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${config.appToken}`,
+                },
+                body: JSON.stringify(body),
+            });
+            if (!resp.ok) {
+                return { ok: false, error: `Hub returned ${resp.status}` };
+            }
+            const result = await resp.json();
+            return { ok: true, messageId: result.client_id };
+        },
+    };
+}

package/dist/src/runtime.d.ts

@@ -0,0 +1,3 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk/core";
+export declare function setPluginRuntime(rt: PluginRuntime): void;
+export declare function getPluginRuntime(): PluginRuntime;

package/dist/src/runtime.js

@@ -0,0 +1,7 @@
+let runtime;
+export function setPluginRuntime(rt) {
+    runtime = rt;
+}
+export function getPluginRuntime() {
+    return runtime;
+}

package/dist/src/types.d.ts

@@ -0,0 +1,54 @@
+export interface OpeniLinkConfig {
+    hubUrl: string;
+    appToken: string;
+}
+export interface HubWSInit {
+    type: "init";
+    data: {
+        installation_id: string;
+        bot_id: string;
+        app_name: string;
+        app_slug: string;
+    };
+}
+export interface HubWSEvent {
+    type: "event";
+    v: number;
+    trace_id: string;
+    installation_id: string;
+    bot: {
+        id: string;
+    };
+    event: {
+        type: string;
+        id: string;
+        timestamp: number;
+        data: {
+            content?: string;
+            sender?: {
+                id: string;
+                name: string;
+            };
+            group?: {
+                id: string;
+                name: string;
+            } | null;
+            msg_type?: string;
+            message_id?: string;
+            [key: string]: unknown;
+        };
+    };
+}
+export interface HubWSAck {
+    type: "ack";
+    req_id: string;
+    ok: boolean;
+}
+export interface HubWSError {
+    type: "error";
+    req_id?: string;
+    error: string;
+}
+export type HubWSMessage = HubWSInit | HubWSEvent | HubWSAck | HubWSError | {
+    type: "pong";
+};

package/dist/src/types.js

@@ -0,0 +1 @@
+export {};

package/openclaw.plugin.json

@@ -0,0 +1,18 @@
+{
+  "id": "openilink",
+  "channels": ["openilink"],
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "hub_url": {
+        "type": "string",
+        "description": "OpeniLink Hub URL (e.g., https://hub.openilink.com)"
+      },
+      "app_token": {
+        "type": "string",
+        "description": "App installation token from Hub"
+      }
+    },
+    "required": ["hub_url", "app_token"]
+  }
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "openclaw-channel-openilink",
+  "version": "0.1.0",
+  "description": "OpenClaw channel plugin for OpeniLink Hub — bridge WeChat bots via Hub",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/",
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["openclaw", "openclaw-plugin", "openilink", "wechat"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/openilink/openclaw-channel-openilink"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2025.0.0"
+  },
+  "devDependencies": {
+    "openclaw": "*",
+    "typescript": "^5.0.0",
+    "ws": "^8.0.0",
+    "@types/ws": "^8.0.0"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  }
+}