@zeyiy/openclaw-channel 0.3.4

package/LICENSE

@@ -0,0 +1,18 @@
+GNU AFFERO GENERAL PUBLIC LICENSE
+Version 3, 19 November 2007
+
+SPDX-License-Identifier: AGPL-3.0-only
+
+This project is licensed under the GNU Affero General Public License v3.0 only.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/agpl-3.0.txt>.
+
+---
+
+This project is a fork of https://github.com/openimsdk/openclaw-channel
+Original authors: blooming and contributors
+Copyright (c) openimsdk contributors
+
+Modifications copyright (c) 2026 ZeyiY
+All modifications are also licensed under AGPL-3.0-only.

package/README.md

@@ -0,0 +1,129 @@
+# @zeyiy/openclaw-channel
+
+OpenIM channel plugin for OpenClaw Gateway.
+
+> Forked from [@openim/openclaw-channel](https://github.com/openimsdk/openclaw-channel). Licensed under AGPL-3.0-only.
+
+Chinese documentation: [README.zh-CN.md](https://github.com/ZeyiY/openclaw-channel/blob/main/README.zh-CN.md)
+
+## Features
+
+- Direct chat and group chat support
+- Inbound and outbound text/image/file messages
+- `openim_send_video` is intentionally sent as a file message
+- Quote/reply message parsing for inbound context
+- Multi-account login via `channels.openim.accounts.<id>`
+- Group trigger policy with optional mention-only mode
+- Interactive setup command: `openclaw openim setup`
+
+## Installation
+
+Install from npm:
+
+```bash
+openclaw plugins install @zeyiy/openclaw-channel
+```
+
+Or install from local path:
+
+```bash
+openclaw plugins install /path/to/openclaw-channel
+```
+
+Repository: https://github.com/ZeyiY/openclaw-channel
+
+## Identity Mapping
+
+- npm package name: `@zeyiy/openclaw-channel`
+- plugin id: `openclaw-channel` (used in `plugins.entries` and `plugins.allow`)
+- channel id: `openim` (used in `channels.openim`)
+- setup command: `openclaw openim setup`
+
+## Configuration
+
+### Option 1: Interactive setup (recommended)
+
+```bash
+openclaw openim setup
+```
+
+### Option 2: Edit `~/.openclaw/openclaw.json`
+
+```json
+{
+  "channels": {
+    "openim": {
+      "accounts": {
+        "default": {
+          "enabled": true,
+          "token": "your_token",
+          "wsAddr": "ws://127.0.0.1:10001",
+          "apiAddr": "http://127.0.0.1:10002"
+        }
+      }
+    }
+  }
+}
+```
+
+`userID` and `platformID` are optional. If omitted, they are auto-derived from JWT token claims (`UserID` and `PlatformID`).
+
+`requireMention` is optional and defaults to `true`.
+
+`inboundWhitelist` is optional. If omitted or empty, inbound handling keeps existing behavior.
+If set, only these users can trigger processing:
+- direct messages to the account
+- group messages where they `@` the account
+
+Single-account fallback (without `accounts`) is supported.
+
+Environment fallback is supported for the `default` account:
+
+- `OPENIM_TOKEN`
+- `OPENIM_WS_ADDR`
+- `OPENIM_API_ADDR`
+
+Optional env overrides:
+
+- `OPENIM_USER_ID`
+- `OPENIM_PLATFORM_ID`
+
+## Agent Tools
+
+- `openim_send_text`
+  - `target`: `user:<id>` or `group:<id>`
+  - `text`: message text
+  - `accountId` (optional): select sending account
+
+- `openim_send_image`
+  - `target`: `user:<id>` or `group:<id>`
+  - `image`: local path (`file://` supported) or `http(s)` URL
+  - `accountId` (optional): select sending account
+
+- `openim_send_video`
+  - `target`: `user:<id>` or `group:<id>`
+  - `video`: local path (`file://` supported) or `http(s)` URL
+  - behavior: sent as a file message (not OpenIM video message)
+  - `name` (optional): override filename for URL input
+  - `accountId` (optional): select sending account
+
+- `openim_send_file`
+  - `target`: `user:<id>` or `group:<id>`
+  - `file`: local path (`file://` supported) or `http(s)` URL
+  - `name` (optional): override filename for URL input
+  - `accountId` (optional): select sending account
+
+## Development
+
+```bash
+pnpm run build
+pnpm run test:connect
+```
+
+For `test:connect`, configure `.env` first (see `.env.example`).
+
+## License
+
+AGPL-3.0-only. See [LICENSE](https://github.com/ZeyiY/openclaw-channel/blob/main/LICENSE).
+
+Originally developed by [openimsdk](https://github.com/openimsdk/openclaw-channel).

package/README.zh-CN.md

@@ -0,0 +1,128 @@
+# @zeyiy/openclaw-channel
+
+OpenClaw Gateway 的 OpenIM 渠道插件。
+
+> 从 [@openim/openclaw-channel](https://github.com/openimsdk/openclaw-channel) fork 而来，采用 AGPL-3.0-only 许可证。
+
+English documentation: [README.md](https://github.com/ZeyiY/openclaw-channel/blob/main/README.md)
+
+## 功能
+
+- 支持私聊与群聊
+- 支持文本/图片/文件消息的收发
+- `openim_send_video` 按文件消息发送（不使用 OpenIM 视频消息）
+- 支持引用消息解析（用于入站上下文）
+- 支持多账号并发（`channels.openim.accounts.<id>`）
+- 支持群聊仅 @ 触发
+- 提供交互式配置命令：`openclaw openim setup`
+
+## 安装
+
+从 npm 安装：
+
+```bash
+openclaw plugins install @zeyiy/openclaw-channel
+```
+
+本地路径安装：
+
+```bash
+openclaw plugins install /path/to/openclaw-channel
+```
+
+仓库地址：https://github.com/ZeyiY/openclaw-channel
+
+## 标识说明
+
+- npm 包名：`@zeyiy/openclaw-channel`
+- 插件 id：`openclaw-channel`（用于 `plugins.entries` / `plugins.allow`）
+- 渠道 id：`openim`（用于 `channels.openim`）
+- 配置命令：`openclaw openim setup`
+
+## 配置
+
+### 方式一：交互式配置（推荐）
+
+```bash
+openclaw openim setup
+```
+
+### 方式二：手动编辑 `~/.openclaw/openclaw.json`
+
+```json
+{
+  "channels": {
+    "openim": {
+      "accounts": {
+        "default": {
+          "enabled": true,
+          "token": "your_token",
+          "wsAddr": "ws://127.0.0.1:10001",
+          "apiAddr": "http://127.0.0.1:10002"
+        }
+      }
+    }
+  }
+}
+```
+
+`userID` 和 `platformID` 为可选项，未填写时会自动从 JWT token 的 `UserID` / `PlatformID` 声明解析。
+
+`requireMention` 为可选项，默认 `true`。
+
+`inboundWhitelist` 为可选项，不填或为空时保持当前逻辑；填了后仅处理白名单用户触发的消息：
+- 给账号发单聊消息
+- 在群里 @ 账号的消息
+
+支持单账号兜底写法（不使用 `accounts`）。
+
+`default` 账号支持环境变量兜底：
+
+- `OPENIM_TOKEN`
+- `OPENIM_WS_ADDR`
+- `OPENIM_API_ADDR`
+
+可选环境变量覆盖项：
+
+- `OPENIM_USER_ID`
+- `OPENIM_PLATFORM_ID`
+
+## Agent 工具
+
+- `openim_send_text`
+  - `target`: `user:<id>` 或 `group:<id>`
+  - `text`: 文本内容
+  - `accountId`（可选）：指定发送账号
+
+- `openim_send_image`
+  - `target`: `user:<id>` 或 `group:<id>`
+  - `image`: 本地路径（支持 `file://`）或 `http(s)` URL
+  - `accountId`（可选）：指定发送账号
+
+- `openim_send_video`
+  - `target`: `user:<id>` 或 `group:<id>`
+  - `video`: 本地路径（支持 `file://`）或 `http(s)` URL
+  - 行为：按文件消息发送（不是视频消息）
+  - `name`（可选）：URL 输入时覆盖文件名
+  - `accountId`（可选）：指定发送账号
+
+- `openim_send_file`
+  - `target`: `user:<id>` 或 `group:<id>`
+  - `file`: 本地路径（支持 `file://`）或 `http(s)` URL
+  - `name`（可选）：URL 输入时覆盖文件名
+  - `accountId`（可选）：指定发送账号
+
+## 开发
+
+```bash
+pnpm run build
+pnpm run test:connect
+```
+
+运行 `test:connect` 前请先配置 `.env`（参考 `.env.example`）。
+
+## 许可证
+
+本项目采用 `AGPL-3.0-only` 许可证。详见 [LICENSE](https://github.com/ZeyiY/openclaw-channel/blob/main/LICENSE)。
+
+原始项目由 [openimsdk](https://github.com/openimsdk/openclaw-channel) 开发。

package/dist/channel.d.ts

@@ -0,0 +1,51 @@
+export declare const OpenIMChannelPlugin: {
+    id: string;
+    meta: {
+        id: string;
+        label: string;
+        selectionLabel: string;
+        docsPath: string;
+        blurb: string;
+        aliases: string[];
+    };
+    capabilities: {
+        chatTypes: string[];
+    };
+    config: {
+        listAccountIds: (cfg: any) => string[];
+        resolveAccount: (cfg: any, accountId?: string) => {
+            [k: string]: unknown;
+            accountId: string;
+        };
+    };
+    gateway: {
+        startAccount: (ctx: any) => Promise<void>;
+    };
+    outbound: {
+        deliveryMode: "direct";
+        resolveTarget: ({ to }: {
+            to?: string;
+        }) => {
+            ok: boolean;
+            error: Error;
+            to?: undefined;
+        } | {
+            ok: boolean;
+            to: string;
+            error?: undefined;
+        };
+        sendText: ({ to, text, accountId }: {
+            to: string;
+            text: string;
+            accountId?: string;
+        }) => Promise<{
+            ok: boolean;
+            error: Error;
+            provider?: undefined;
+        } | {
+            ok: boolean;
+            provider: string;
+            error?: undefined;
+        }>;
+    };
+};

package/dist/channel.js

@@ -0,0 +1,74 @@
+import { getConnectedClient, startAccountClient, stopAccountClient } from "./clients";
+import { listAccountIds, resolveAccountConfig, getOpenIMAccountConfig } from "./config";
+import { sendTextToTarget } from "./media";
+import { parseTarget } from "./targets";
+import { formatSdkError } from "./utils";
+export const OpenIMChannelPlugin = {
+    id: "openim",
+    meta: {
+        id: "openim",
+        label: "OpenIM",
+        selectionLabel: "OpenIM",
+        docsPath: "/channels/openim",
+        blurb: "OpenIM protocol channel via @openim/client-sdk",
+        aliases: ["openim", "im"],
+    },
+    capabilities: {
+        chatTypes: ["direct", "group"],
+    },
+    config: {
+        listAccountIds: (cfg) => listAccountIds(cfg),
+        resolveAccount: (cfg, accountId) => resolveAccountConfig(cfg, accountId),
+    },
+    gateway: {
+        startAccount: async (ctx) => {
+            const api = globalThis.__openimApi;
+            if (!api) {
+                ctx.log?.error?.("[openim] api not initialized");
+                return;
+            }
+            const config = getOpenIMAccountConfig(ctx.cfg ?? api.config, ctx.accountId);
+            if (!config || !config.enabled)
+                return;
+            if (!getConnectedClient(ctx.accountId)) {
+                await startAccountClient(api, config);
+            }
+            await new Promise((resolve) => {
+                if (ctx.abortSignal?.aborted) {
+                    resolve();
+                }
+                else {
+                    ctx.abortSignal?.addEventListener("abort", () => resolve(), { once: true });
+                }
+            });
+            await stopAccountClient(api, ctx.accountId);
+        },
+    },
+    outbound: {
+        deliveryMode: "direct",
+        resolveTarget: ({ to }) => {
+            const target = parseTarget(to);
+            if (!target) {
+                return { ok: false, error: new Error("OpenIM requires --to <user:ID|group:ID>") };
+            }
+            return { ok: true, to: `${target.kind}:${target.id}` };
+        },
+        sendText: async ({ to, text, accountId }) => {
+            const target = parseTarget(to);
+            if (!target) {
+                return { ok: false, error: new Error("invalid target, expected user:<id> or group:<id>") };
+            }
+            const client = getConnectedClient(accountId);
+            if (!client) {
+                return { ok: false, error: new Error("OpenIM not connected") };
+            }
+            try {
+                await sendTextToTarget(client, target, text);
+                return { ok: true, provider: "openim" };
+            }
+            catch (e) {
+                return { ok: false, error: new Error(formatSdkError(e)) };
+            }
+        },
+    },
+};

package/dist/clients.d.ts

@@ -0,0 +1,6 @@
+import type { OpenIMAccountConfig, OpenIMClientState } from "./types";
+export declare function getConnectedClient(accountId?: string): OpenIMClientState | null;
+export declare function connectedClientCount(): number;
+export declare function startAccountClient(api: any, config: OpenIMAccountConfig): Promise<void>;
+export declare function stopAccountClient(api: any, accountId: string): Promise<void>;
+export declare function stopAllClients(api: any): Promise<void>;

package/dist/clients.js

@@ -0,0 +1,103 @@
+import { CbEvents, getSDK } from "@openim/client-sdk";
+import { processInboundMessage } from "./inbound";
+import { startPortalBridge, stopPortalBridge, stopAllPortalBridges } from "./portal";
+import { formatSdkError } from "./utils";
+const clients = new Map();
+function detachHandlers(state) {
+    state.sdk.off(CbEvents.OnRecvNewMessage, state.handlers.onRecvNewMessage);
+    state.sdk.off(CbEvents.OnRecvNewMessages, state.handlers.onRecvNewMessages);
+    state.sdk.off(CbEvents.OnRecvOfflineNewMessages, state.handlers.onRecvOfflineNewMessages);
+}
+export function getConnectedClient(accountId) {
+    if (accountId && clients.has(accountId)) {
+        return clients.get(accountId) ?? null;
+    }
+    if (clients.has("default"))
+        return clients.get("default") ?? null;
+    const first = clients.values().next();
+    return first.done ? null : first.value;
+}
+export function connectedClientCount() {
+    return clients.size;
+}
+export async function startAccountClient(api, config) {
+    const sdk = getSDK();
+    const state = {
+        sdk,
+        config,
+        handlers: {
+            onRecvNewMessage: () => undefined,
+            onRecvNewMessages: () => undefined,
+            onRecvOfflineNewMessages: () => undefined,
+        },
+    };
+    const consumeMessage = (msg) => {
+        processInboundMessage(api, state, msg).catch((e) => {
+            api.logger?.error?.(`[openim] processInboundMessage failed: ${formatSdkError(e)}`);
+        });
+    };
+    state.handlers.onRecvNewMessage = (event) => {
+        if (event?.data)
+            consumeMessage(event.data);
+    };
+    state.handlers.onRecvNewMessages = (event) => {
+        const list = Array.isArray(event?.data) ? event.data : [];
+        for (const msg of list)
+            consumeMessage(msg);
+    };
+    state.handlers.onRecvOfflineNewMessages = (event) => {
+        const list = Array.isArray(event?.data) ? event.data : [];
+        for (const msg of list)
+            consumeMessage(msg);
+    };
+    sdk.on(CbEvents.OnRecvNewMessage, state.handlers.onRecvNewMessage);
+    sdk.on(CbEvents.OnRecvNewMessages, state.handlers.onRecvNewMessages);
+    sdk.on(CbEvents.OnRecvOfflineNewMessages, state.handlers.onRecvOfflineNewMessages);
+    try {
+        await sdk.login({
+            userID: config.userID,
+            token: config.token,
+            wsAddr: config.wsAddr,
+            apiAddr: config.apiAddr,
+            platformID: config.platformID,
+        });
+        clients.set(config.accountId, state);
+        api.logger?.info?.(`[openim] account ${config.accountId} connected`);
+        // Start portal bridge after successful OpenIM login
+        startPortalBridge(api, config);
+    }
+    catch (e) {
+        detachHandlers(state);
+        api.logger?.error?.(`[openim] account ${config.accountId} login failed: ${formatSdkError(e)}`);
+    }
+}
+export async function stopAccountClient(api, accountId) {
+    // Stop portal bridge before disconnecting OpenIM
+    stopPortalBridge(api, accountId);
+    const state = clients.get(accountId);
+    if (!state)
+        return;
+    clients.delete(accountId);
+    detachHandlers(state);
+    try {
+        await state.sdk.logout();
+    }
+    catch (e) {
+        api.logger?.warn?.(`[openim] account ${accountId} logout failed: ${formatSdkError(e)}`);
+    }
+}
+export async function stopAllClients(api) {
+    // Stop all portal bridges first
+    stopAllPortalBridges(api);
+    const items = Array.from(clients.values());
+    clients.clear();
+    for (const state of items) {
+        detachHandlers(state);
+        try {
+            await state.sdk.logout();
+        }
+        catch (e) {
+            api.logger?.warn?.(`[openim] account ${state.config.accountId} logout failed: ${formatSdkError(e)}`);
+        }
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,9 @@
+import type { OpenIMAccountConfig } from "./types";
+export declare function getOpenIMChannelConfig(apiOrCfg: any): any;
+export declare function listAccountIds(apiOrCfg: any): string[];
+export declare function getOpenIMAccountConfig(apiOrCfg: any, accountId?: string): OpenIMAccountConfig | null;
+export declare function listEnabledAccountConfigs(apiOrCfg: any): OpenIMAccountConfig[];
+export declare function resolveAccountConfig(apiOrCfg: any, accountId?: string): {
+    accountId: string;
+    [k: string]: unknown;
+};

package/dist/config.js

@@ -0,0 +1,168 @@
+import { toFiniteNumber } from "./utils";
+function getConfigRoot(apiOrCfg) {
+    if (apiOrCfg?.config)
+        return apiOrCfg.config;
+    if (apiOrCfg?.channels)
+        return apiOrCfg;
+    return globalThis.__openimGatewayConfig ?? {};
+}
+export function getOpenIMChannelConfig(apiOrCfg) {
+    const root = getConfigRoot(apiOrCfg);
+    return root?.channels?.openim ?? {};
+}
+function decodeJwtPayload(token) {
+    const parts = token.split(".");
+    if (parts.length < 2)
+        return null;
+    const payload = parts[1];
+    if (!payload)
+        return null;
+    try {
+        const normalized = payload.replace(/-/g, "+").replace(/_/g, "/");
+        const padded = normalized.padEnd(normalized.length + ((4 - (normalized.length % 4)) % 4), "=");
+        const json = Buffer.from(padded, "base64").toString("utf8");
+        const parsed = JSON.parse(json);
+        return parsed && typeof parsed === "object" ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function extractAccountHintsFromToken(token) {
+    const payload = decodeJwtPayload(token);
+    if (!payload)
+        return {};
+    const userIDRaw = payload.UserID ?? payload.userID;
+    const userID = String(userIDRaw ?? "").trim();
+    const platformRaw = payload.PlatformID ?? payload.platformID;
+    const platformID = toFiniteNumber(platformRaw, NaN);
+    return {
+        ...(userID ? { userID } : {}),
+        ...(Number.isFinite(platformID) ? { platformID } : {}),
+    };
+}
+function envDefaultAccount() {
+    const token = String(process.env.OPENIM_TOKEN ?? "").trim();
+    const wsAddr = String(process.env.OPENIM_WS_ADDR ?? "").trim();
+    const apiAddr = String(process.env.OPENIM_API_ADDR ?? "").trim();
+    if (!token || !wsAddr || !apiAddr)
+        return null;
+    const hints = extractAccountHintsFromToken(token);
+    const userID = String(process.env.OPENIM_USER_ID ?? hints.userID ?? "").trim();
+    const platformID = toFiniteNumber(process.env.OPENIM_PLATFORM_ID ?? hints.platformID, 5);
+    if (!userID)
+        return null;
+    const botId = String(process.env.OPENIM_BOT_ID ?? "").trim() || undefined;
+    const portalWsAddr = String(process.env.OPENIM_PORTAL_WS_ADDR ?? "").trim() || undefined;
+    return {
+        userID,
+        token,
+        wsAddr,
+        apiAddr,
+        platformID,
+        enabled: true,
+        requireMention: true,
+        botId,
+        portalWsAddr,
+    };
+}
+function normalizeInboundWhitelist(raw) {
+    const values = Array.isArray(raw)
+        ? raw
+        : typeof raw === "string"
+            ? raw.split(",")
+            : [];
+    const normalized = values.map((item) => String(item ?? "").trim()).filter(Boolean);
+    return Array.from(new Set(normalized));
+}
+function normalizeAccount(accountId, raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const token = String(raw.token ?? "").trim();
+    const wsAddr = String(raw.wsAddr ?? "").trim();
+    const apiAddr = String(raw.apiAddr ?? "").trim();
+    if (!token || !wsAddr || !apiAddr)
+        return null;
+    const hints = extractAccountHintsFromToken(token);
+    const userID = String(raw.userID ?? hints.userID ?? "").trim();
+    const platformID = toFiniteNumber(raw.platformID ?? hints.platformID, 5);
+    const enabled = raw.enabled !== false;
+    const requireMention = raw.requireMention !== false;
+    const inboundWhitelist = normalizeInboundWhitelist(raw.inboundWhitelist);
+    const botId = String(raw.botId ?? "").trim() || undefined;
+    const portalWsAddr = String(raw.portalWsAddr ?? "").trim() || undefined;
+    if (!userID)
+        return null;
+    return {
+        accountId,
+        enabled,
+        userID,
+        token,
+        wsAddr,
+        apiAddr,
+        platformID,
+        requireMention,
+        inboundWhitelist,
+        botId,
+        portalWsAddr,
+    };
+}
+export function listAccountIds(apiOrCfg) {
+    const ch = getOpenIMChannelConfig(apiOrCfg);
+    const accounts = ch?.accounts;
+    if (accounts && typeof accounts === "object") {
+        const ids = Object.keys(accounts);
+        if (ids.length > 0)
+            return ids;
+    }
+    if (ch?.userID || ch?.token || ch?.wsAddr || ch?.apiAddr)
+        return ["default"];
+    if (envDefaultAccount())
+        return ["default"];
+    return [];
+}
+export function getOpenIMAccountConfig(apiOrCfg, accountId = "default") {
+    const ch = getOpenIMChannelConfig(apiOrCfg);
+    const accountRaw = ch?.accounts?.[accountId];
+    if (accountRaw) {
+        return normalizeAccount(accountId, accountRaw);
+    }
+    if (accountId === "default") {
+        if (ch?.userID || ch?.token || ch?.wsAddr || ch?.apiAddr) {
+            const normalized = normalizeAccount("default", ch);
+            if (normalized)
+                return normalized;
+        }
+        const env = envDefaultAccount();
+        if (env) {
+            return normalizeAccount("default", env);
+        }
+    }
+    return null;
+}
+export function listEnabledAccountConfigs(apiOrCfg) {
+    const ids = listAccountIds(apiOrCfg);
+    const out = [];
+    for (const id of ids) {
+        const cfg = getOpenIMAccountConfig(apiOrCfg, id);
+        if (cfg && cfg.enabled)
+            out.push(cfg);
+    }
+    return out;
+}
+export function resolveAccountConfig(apiOrCfg, accountId) {
+    const id = accountId ?? "default";
+    const ch = getOpenIMChannelConfig(apiOrCfg);
+    if (ch?.accounts?.[id]) {
+        return { accountId: id, ...ch.accounts[id] };
+    }
+    if (id === "default" && (ch?.userID || ch?.token || ch?.wsAddr || ch?.apiAddr)) {
+        return { accountId: id, ...ch };
+    }
+    if (id === "default") {
+        const env = envDefaultAccount();
+        if (env)
+            return { accountId: id, ...env };
+    }
+    return { accountId: id };
+}

package/dist/inbound.d.ts

@@ -0,0 +1,3 @@
+import { type MessageItem } from "@openim/client-sdk";
+import type { OpenIMClientState } from "./types";
+export declare function processInboundMessage(api: any, client: OpenIMClientState, msg: MessageItem): Promise<void>;