@zeyiy/openclaw-channel 0.3.7 → 0.3.9

package/README.md

@@ -1,56 +1,46 @@
 # @zeyiy/openclaw-channel
 
-OpenIM channel plugin for OpenClaw Gateway.
+OpenIM channel plugin for [OpenClaw](https://openclaw.ai) 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)
+Connects OpenClaw agents to the [OpenIM](https://www.openim.io/) messaging platform, enabling AI-powered conversations in direct chats and group chats.
 
 ## 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
+- Text / image / file / video message send & receive
+- Quote/reply message context parsing
+- Multi-account concurrent login
+- Group trigger with optional mention-only mode
+- Per-user session isolation (direct) / shared session (group)
 - Auto read-receipt for direct messages
-- Per-user session isolation (direct chat) / shared session (group chat)
-- Agent Portal Bridge — persistent WebSocket connection to agent-portal cloud service
-- Interactive setup command: `openclaw openim setup`
+- Inbound sender whitelist (optional)
+- **Agent Portal Bridge** — persistent WebSocket to agent-portal for remote agent management
+- Interactive setup: `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`
+| Item | Value |
+|------|-------|
+| npm package | `@zeyiy/openclaw-channel` |
+| plugin id | `openclaw-channel` |
+| channel id | `openim` |
+| setup command | `openclaw openim setup` |
 
 ## Configuration
 
-### Option 1: Interactive setup (recommended)
+### Interactive setup (recommended)
 
 ```bash
 openclaw openim setup
 ```
 
-### Option 2: Edit `~/.openclaw/openclaw.json`
+### Manual — edit `~/.openclaw/openclaw.json`
 
 ```json
 {
@@ -59,11 +49,11 @@ openclaw openim setup
       "accounts": {
         "default": {
           "enabled": true,
-          "token": "your_token",
-          "wsAddr": "ws://127.0.0.1:10001",
-          "apiAddr": "http://127.0.0.1:10002",
-          "botId": "my-bot-001",
-          "portalWsAddr": "wss://portal.example.com/ws"
+          "token": "your_jwt_token",
+          "wsAddr": "wss://your-openim-server/msg_gateway",
+          "apiAddr": "https://your-openim-server/api",
+          "botId": "your-bot-id",
+          "portalWsAddr": "wss://agent-portal.example.com/ws/workspace"
         }
       }
     }
@@ -71,87 +61,70 @@ openclaw openim setup
 }
 ```
 
-`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`.
+### Field reference
 
-`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
+| Field | Required | Description |
+|-------|----------|-------------|
+| `token` | Yes | OpenIM JWT token |
+| `wsAddr` | Yes | OpenIM WebSocket endpoint |
+| `apiAddr` | Yes | OpenIM REST API endpoint |
+| `userID` | No | Auto-derived from JWT `UserID` claim |
+| `platformID` | No | Auto-derived from JWT `PlatformID` claim |
+| `enabled` | No | Default `true` |
+| `requireMention` | No | Require @mention in groups, default `true` |
+| `inboundWhitelist` | No | Only process messages from listed user IDs |
+| `botId` | No | Bot ID for agent-portal connection |
+| `portalWsAddr` | No | Agent-portal WebSocket endpoint |
+| `historyLimit` | No | Chat history context limit, default `20` |
 
-`botId` and `portalWsAddr` are optional. When both are set, the plugin establishes a WebSocket connection to the agent-portal cloud service, enabling remote management of agents, files, and models.
+Single-account shorthand (without `accounts` wrapper) is also supported.
 
-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`
+> **Note:** Environment variable fallback has been removed. All configuration is via `openclaw.json`.
 
 ## 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
+| Tool | Parameters | Description |
+|------|-----------|-------------|
+| `openim_send_text` | `target`, `text`, `accountId?` | Send text message |
+| `openim_send_image` | `target`, `image`, `accountId?` | Send image (local path or URL) |
+| `openim_send_file` | `target`, `file`, `name?`, `accountId?` | Send file (local path or URL) |
+| `openim_send_video` | `target`, `video`, `name?`, `accountId?` | Send video as file message |
+
+`target` format: `user:<id>` or `group:<id>`
 
 ## Agent Portal Bridge
 
-When `botId` and `portalWsAddr` are configured, the plugin connects to the agent-portal cloud service via WebSocket. The portal can remotely invoke the following methods:
+When `botId` and `portalWsAddr` are configured, the plugin maintains a WebSocket connection to agent-portal, enabling remote management:
 
 | Method | Description |
-|---|---|
-| `bot.agent.get` | Resolve the agentId bound to the current bot |
-| `models.list` | List available models from config |
-| `agents.list` | List all configured agents |
-| `agents.create` | Create a new agent with workspace |
-| `agents.files.list` | List workspace files for an agent |
-| `agents.files.get` | Read a single workspace file |
-| `agents.files.set` | Write a file to agent workspace |
+|--------|-------------|
+| `bot.agent.get` | Resolve bot's bound agent |
+| `models.list` | List available models |
+| `agents.list` | List configured agents |
+| `agents.create` | Create new agent + workspace |
+| `agents.files.list` | List agent workspace files |
+| `agents.files.get` | Read workspace file |
+| `agents.files.set` | Write workspace file |
 | `tools.catalog` | List available tools |
-| `skills.status` | List installed skills/plugins status |
-| `skills.search` | Search ClawHub for skills (placeholder) |
-| `skills.detail` | Get detail for a specific skill |
-| `cron.list` | List configured cron jobs |
+| `skills.status` | Skill/plugin status |
+| `agent.skills.status` | Per-agent skill status with whitelist |
+| `agent.skills.set` | Enable/disable skill for agent |
+| `agent.model.set` | Switch agent model |
+| `skills.search` | Search ClawHub registry |
+| `skills.install` | Install skill from ClawHub or URL |
+| `skills.set` | Enable/disable skill globally |
+| `cron.list` | List cron jobs |
 
-The connection features automatic reconnect with exponential backoff and heartbeat keepalive.
+Features auto-reconnect with exponential backoff and heartbeat keepalive.
 
 ## Development
 
 ```bash
+pnpm install
 pnpm run build
-pnpm run test:connect
+pnpm run test:connect   # configure .env first
 ```
 
-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).
+AGPL-3.0-only. See [LICENSE](./LICENSE).

package/README.zh-CN.md

@@ -1,56 +1,46 @@
 # @zeyiy/openclaw-channel
 
-OpenClaw Gateway 的 OpenIM 渠道插件。
+[OpenClaw](https://openclaw.ai) 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)
+将 OpenClaw 智能体接入 [OpenIM](https://www.openim.io/) 即时通讯平台，支持私聊和群聊中的 AI 对话。
 
 ## 功能
 
 - 支持私聊与群聊
-- 支持文本/图片/文件消息的收发
-- `openim_send_video` 按文件消息发送（不使用 OpenIM 视频消息）
-- 支持引用消息解析（用于入站上下文）
-- 支持多账号并发（`channels.openim.accounts.<id>`）
-- 支持群聊仅 @ 触发
-- 私聊消息自动标记已读（已读回执）
+- 文本 / 图片 / 文件 / 视频消息收发
+- 引用消息上下文解析
+- 多账号并发登录
+- 群聊 @触发模式（可选）
 - 每用户独立会话（私聊）/ 同群共享会话（群聊）
-- Agent Portal Bridge — 与 agent-portal 云服务保持 WebSocket 长连接，支持远程管理
-- 提供交互式配置命令：`openclaw openim setup`
+- 私聊自动已读回执
+- 入站发送者白名单（可选）
+- **Agent Portal Bridge** — 与 agent-portal 云服务保持 WebSocket 长连接，支持远程管理
+- 交互式配置命令：`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`
+| 项目 | 值 |
+|------|-----|
+| npm 包名 | `@zeyiy/openclaw-channel` |
+| 插件 ID | `openclaw-channel` |
+| 渠道 ID | `openim` |
+| 配置命令 | `openclaw openim setup` |
 
 ## 配置
 
-### 方式一：交互式配置（推荐）
+### 交互式配置（推荐）
 
 ```bash
 openclaw openim setup
 ```
 
-### 方式二：手动编辑 `~/.openclaw/openclaw.json`
+### 手动编辑 `~/.openclaw/openclaw.json`
 
 ```json
 {
@@ -59,11 +49,11 @@ openclaw openim setup
       "accounts": {
         "default": {
           "enabled": true,
-          "token": "your_token",
-          "wsAddr": "ws://127.0.0.1:10001",
-          "apiAddr": "http://127.0.0.1:10002",
-          "botId": "my-bot-001",
-          "portalWsAddr": "wss://portal.example.com/ws"
+          "token": "your_jwt_token",
+          "wsAddr": "wss://your-openim-server/msg_gateway",
+          "apiAddr": "https://your-openim-server/api",
+          "botId": "your-bot-id",
+          "portalWsAddr": "wss://agent-portal.example.com/ws/workspace"
         }
       }
     }
@@ -71,86 +61,70 @@ openclaw openim setup
 }
 ```
 
-`userID` 和 `platformID` 为可选项，未填写时会自动从 JWT token 的 `UserID` / `PlatformID` 声明解析。
-
-`requireMention` 为可选项，默认 `true`。
+### 字段说明
 
-`inboundWhitelist` 为可选项，不填或为空时保持当前逻辑；填了后仅处理白名单用户触发的消息：
-- 给账号发单聊消息
-- 在群里 @ 账号的消息
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `token` | 是 | OpenIM JWT token |
+| `wsAddr` | 是 | OpenIM WebSocket 端点 |
+| `apiAddr` | 是 | OpenIM REST API 端点 |
+| `userID` | 否 | 自动从 JWT `UserID` 声明解析 |
+| `platformID` | 否 | 自动从 JWT `PlatformID` 声明解析 |
+| `enabled` | 否 | 默认 `true` |
+| `requireMention` | 否 | 群聊需 @触发，默认 `true` |
+| `inboundWhitelist` | 否 | 仅处理指定用户 ID 的消息 |
+| `botId` | 否 | 用于 agent-portal 连接的 Bot ID |
+| `portalWsAddr` | 否 | Agent-portal WebSocket 端点 |
+| `historyLimit` | 否 | 聊天历史上下文条数，默认 `20` |
 
-`botId` 和 `portalWsAddr` 为可选项。同时配置后，插件会与 agent-portal 云服务建立 WebSocket 连接，支持远程管理 agent、文件和模型。
+支持单账号简写（不使用 `accounts` 包装）。
 
-支持单账号兜底写法（不使用 `accounts`）。
-
-`default` 账号支持环境变量兜底：
-
-- `OPENIM_TOKEN`
-- `OPENIM_WS_ADDR`
-- `OPENIM_API_ADDR`
-
-可选环境变量覆盖项：
-
-- `OPENIM_USER_ID`
-- `OPENIM_PLATFORM_ID`
+> **注意：** 已移除环境变量配置方式，所有配置通过 `openclaw.json` 完成。
 
 ## 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`（可选）：指定发送账号
+| 工具 | 参数 | 说明 |
+|------|------|------|
+| `openim_send_text` | `target`, `text`, `accountId?` | 发送文本消息 |
+| `openim_send_image` | `target`, `image`, `accountId?` | 发送图片（本地路径或 URL） |
+| `openim_send_file` | `target`, `file`, `name?`, `accountId?` | 发送文件（本地路径或 URL） |
+| `openim_send_video` | `target`, `video`, `name?`, `accountId?` | 发送视频（按文件消息发送） |
+
+`target` 格式：`user:<id>` 或 `group:<id>`
 
 ## Agent Portal Bridge
 
-配置 `botId` 和 `portalWsAddr` 后，插件会通过 WebSocket 连接到 agent-portal 云服务。Portal 可远程调用以下方法：
+配置 `botId` 和 `portalWsAddr` 后，插件与 agent-portal 保持 WebSocket 连接，支持远程管理：
 
 | 方法 | 说明 |
-|---|---|
-| `bot.agent.get` | 获取当前 bot 绑定的 agentId |
-| `models.list` | 列出配置中的可用模型 |
-| `agents.list` | 列出所有已配置的 agent |
-| `agents.create` | 创建新 agent 及工作空间 |
-| `agents.files.list` | 列出 agent 工作空间文件 |
-| `agents.files.get` | 读取单个工作空间文件 |
-| `agents.files.set` | 写入文件到 agent 工作空间 |
+|------|------|
+| `bot.agent.get` | 获取 bot 绑定的 agent |
+| `models.list` | 列出可用模型 |
+| `agents.list` | 列出已配置的 agent |
+| `agents.create` | 创建 agent + 工作空间 |
+| `agents.files.list` | 列出工作空间文件 |
+| `agents.files.get` | 读取工作空间文件 |
+| `agents.files.set` | 写入工作空间文件 |
 | `tools.catalog` | 列出可用工具 |
-| `skills.status` | 列出已安装技能/插件状态 |
-| `skills.search` | 搜索 ClawHub 技能（占位） |
-| `skills.detail` | 获取特定技能详情 |
-| `cron.list` | 列出已配置的定时任务 |
+| `skills.status` | 技能/插件状态 |
+| `agent.skills.status` | Agent 级技能状态（含白名单） |
+| `agent.skills.set` | 启用/禁用 agent 技能 |
+| `agent.model.set` | 切换 agent 模型 |
+| `skills.search` | 搜索 ClawHub 技能 |
+| `skills.install` | 从 ClawHub 或 URL 安装技能 |
+| `skills.set` | 全局启用/禁用技能 |
+| `cron.list` | 列出定时任务 |
 
-连接支持指数退避自动重连和心跳保活。
+支持指数退避自动重连和心跳保活。
 
 ## 开发
 
 ```bash
+pnpm install
 pnpm run build
-pnpm run test:connect
+pnpm run test:connect   # 先配置 .env
 ```
 
-运行 `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) 开发。
+AGPL-3.0-only，详见 [LICENSE](./LICENSE)。

package/dist/clients.js

@@ -3,6 +3,7 @@ import { processInboundMessage } from "./inbound";
 import { startPortalBridge, stopPortalBridge, stopAllPortalBridges } from "./portal";
 import { formatSdkError } from "./utils";
 const clients = new Map();
+const loginInProgress = new Set();
 function detachHandlers(state) {
     state.sdk.off(CbEvents.OnRecvNewMessage, state.handlers.onRecvNewMessage);
     state.sdk.off(CbEvents.OnRecvNewMessages, state.handlers.onRecvNewMessages);
@@ -21,6 +22,26 @@ export function connectedClientCount() {
     return clients.size;
 }
 export async function startAccountClient(api, config) {
+    if (clients.has(config.accountId) || loginInProgress.has(config.accountId)) {
+        api.logger?.debug?.(`[openim] account ${config.accountId} already connected or login in progress, skipping`);
+        return;
+    }
+    loginInProgress.add(config.accountId);
+    // Diagnostic: test raw WebSocket before SDK login
+    const WS = globalThis.WebSocket;
+    api.logger?.info?.(`[openim] WebSocket global: ${typeof WS}, constructor: ${WS?.name ?? "N/A"}`);
+    try {
+        const testWs = new WS(config.wsAddr);
+        await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => { testWs.close(); reject(new Error("timeout")); }, 5000);
+            testWs.onopen = () => { clearTimeout(timer); testWs.close(); resolve(); };
+            testWs.onerror = (e) => { clearTimeout(timer); reject(e); };
+        });
+        api.logger?.info?.(`[openim] raw WebSocket test to ${config.wsAddr}: OK`);
+    }
+    catch (e) {
+        api.logger?.error?.(`[openim] raw WebSocket test to ${config.wsAddr}: FAILED — ${e?.message ?? e}`);
+    }
     const sdk = getSDK();
     const state = {
         sdk,
@@ -62,14 +83,16 @@ export async function startAccountClient(api, config) {
             platformID: config.platformID,
         });
         clients.set(config.accountId, state);
+        loginInProgress.delete(config.accountId);
         api.logger?.info?.(`[openim] account ${config.accountId} connected`);
-        // Start portal bridge after successful OpenIM login
-        startPortalBridge(api, config);
     }
     catch (e) {
         detachHandlers(state);
+        loginInProgress.delete(config.accountId);
         api.logger?.error?.(`[openim] account ${config.accountId} login failed: ${formatSdkError(e)}`);
     }
+    // Start portal bridge regardless of SDK login result — portal is an independent service
+    startPortalBridge(api, config);
 }
 export async function stopAccountClient(api, accountId) {
     // Stop portal bridge before disconnecting OpenIM

package/dist/config.js

@@ -41,32 +41,6 @@ function extractAccountHintsFromToken(token) {
         ...(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,
-        historyLimit: 20,
-        botId,
-        portalWsAddr,
-    };
-}
 function normalizeInboundWhitelist(raw) {
     const values = Array.isArray(raw)
         ? raw
@@ -120,8 +94,6 @@ export function listAccountIds(apiOrCfg) {
     }
     if (ch?.userID || ch?.token || ch?.wsAddr || ch?.apiAddr)
         return ["default"];
-    if (envDefaultAccount())
-        return ["default"];
     return [];
 }
 export function getOpenIMAccountConfig(apiOrCfg, accountId = "default") {
@@ -136,10 +108,6 @@ export function getOpenIMAccountConfig(apiOrCfg, accountId = "default") {
             if (normalized)
                 return normalized;
         }
-        const env = envDefaultAccount();
-        if (env) {
-            return normalizeAccount("default", env);
-        }
     }
     return null;
 }
@@ -162,10 +130,5 @@ export function resolveAccountConfig(apiOrCfg, accountId) {
     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/polyfills.d.ts

@@ -1,9 +1 @@
-declare class NodeFileReaderPolyfill {
-    result: ArrayBuffer | null;
-    error: Error | null;
-    onload: ((ev: {
-        target: NodeFileReaderPolyfill;
-    }) => void) | null;
-    onerror: ((err: unknown) => void) | null;
-    readAsArrayBuffer(blob: Blob): void;
-}
+export {};

package/dist/polyfills.js

@@ -1,4 +1,15 @@
-"use strict";
+import WsWebSocket from "ws";
+// Force ws library over native WebSocket — OpenIM WASM SDK is incompatible
+// with Node.js native WebSocket (undici-based), causing instant "network error".
+globalThis.WebSocket = WsWebSocket;
+// ws library sends Buffer for binary messages; OpenIM SDK calls .arrayBuffer() expecting a Blob.
+// Polyfill Buffer.prototype.arrayBuffer so it returns Promise<ArrayBuffer>.
+if (typeof Buffer !== "undefined" && !Buffer.prototype.arrayBuffer) {
+    Buffer.prototype.arrayBuffer = function () {
+        const ab = this.buffer.slice(this.byteOffset, this.byteOffset + this.byteLength);
+        return Promise.resolve(ab);
+    };
+}
 class NodeFileReaderPolyfill {
     result = null;
     error = null;

package/dist/portal.js

@@ -6,9 +6,10 @@
  * Lifecycle is tied to the OpenIM account: starts/stops alongside the account.
  */
 import { readFile, writeFile, stat, mkdir, unlink, rm } from "node:fs/promises";
-import { accessSync, readdirSync, realpathSync, existsSync, readFileSync, statSync, constants as fsConstants } from "node:fs";
+import { readdirSync, realpathSync, existsSync, readFileSync, statSync } from "node:fs";
+import WsWebSocket from "ws";
 import { resolve, join, dirname, basename } from "node:path";
-import { execFile } from "node:child_process";
+import { execFile, execFileSync } from "node:child_process";
 import { promisify } from "node:util";
 import { tmpdir, homedir } from "node:os";
 const bridges = new Map();
@@ -51,7 +52,7 @@ function resolveDefaultAgentId(cfg) {
 }
 /** Expand leading ~ to $HOME, then resolve to absolute path. */
 function resolveUserPath(p) {
-    const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
+    const home = homedir() || "";
     if (p.startsWith("~/") || p === "~") {
         return resolve(home, p.slice(2));
     }
@@ -65,7 +66,7 @@ function resolveAgentWorkspaceDir(cfg, agentId) {
         return resolveUserPath(entry.workspace.trim());
     const fallback = cfg.agents?.defaults?.workspace?.trim();
     const defaultId = resolveDefaultAgentId(cfg);
-    const home = process.env.HOME ?? process.cwd();
+    const home = homedir() || process.cwd();
     if (id === defaultId) {
         if (fallback)
             return resolveUserPath(fallback);
@@ -498,25 +499,8 @@ function handleToolsCatalog(api, params) {
  * Resolve the openclaw state directory root.
  * Mirrors gateway's resolveStateDir: OPENCLAW_STATE_DIR > dirname(OPENCLAW_CONFIG_PATH) > ~/.openclaw
  */
-/** Resolve the effective home directory, matching gateway's resolveRequiredHomeDir priority:
- *  OPENCLAW_HOME → process.env.HOME → process.env.USERPROFILE → os.homedir() → cwd */
+/** Resolve the effective home directory. */
 function resolveEffectiveHomeDir() {
-    const openclawHome = (process.env.OPENCLAW_HOME ?? "").trim();
-    if (openclawHome && openclawHome !== "undefined" && openclawHome !== "null") {
-        // Support ~/... prefix expansion using os.homedir()
-        if (openclawHome === "~" || openclawHome.startsWith("~/") || openclawHome.startsWith("~\\")) {
-            const osHome = process.env.HOME || process.env.USERPROFILE || homedir();
-            if (osHome)
-                return resolve(openclawHome.replace(/^~(?=$|[\\/])/, osHome));
-        }
-        return resolve(openclawHome);
-    }
-    const envHome = (process.env.HOME ?? "").trim();
-    if (envHome)
-        return resolve(envHome);
-    const userProfile = (process.env.USERPROFILE ?? "").trim();
-    if (userProfile)
-        return resolve(userProfile);
     try {
         return resolve(homedir());
     }
@@ -524,47 +508,26 @@ function resolveEffectiveHomeDir() {
     return resolve(process.cwd());
 }
 function resolveStateDir() {
-    const stateDir = (process.env.OPENCLAW_STATE_DIR ?? "").trim();
-    if (stateDir)
-        return resolve(stateDir.startsWith("~") ? stateDir.replace(/^~(?=$|[\\/])/, resolveEffectiveHomeDir()) : stateDir);
-    const configPath = (process.env.OPENCLAW_CONFIG_PATH ?? "").trim();
-    if (configPath)
-        return resolve(dirname(configPath.startsWith("~") ? configPath.replace(/^~(?=$|[\\/])/, resolveEffectiveHomeDir()) : configPath));
     return join(resolveEffectiveHomeDir(), ".openclaw");
 }
-/**
- * Resolve the openclaw config file path.
- * Mirrors gateway's resolveCanonicalConfigPath: OPENCLAW_CONFIG_PATH > {stateDir}/openclaw.json
- */
 function resolveOpenClawConfigPath() {
-    const configPathOverride = (process.env.OPENCLAW_CONFIG_PATH ?? "").trim();
-    if (configPathOverride)
-        return resolveUserPath(configPathOverride);
     return join(resolveStateDir(), "openclaw.json");
 }
-/** Check if a binary is executable on the system PATH. Mirrors gateway's hasBinary. */
+/** Check if a binary is executable on the system PATH. */
 const _binaryCache = new Map();
 function hasBinarySync(bin) {
     const cached = _binaryCache.get(bin);
     if (cached !== undefined)
         return cached;
-    const delimiter = process.platform === "win32" ? ";" : ":";
-    const parts = (process.env.PATH ?? "").split(delimiter).filter(Boolean);
-    const extensions = process.platform === "win32"
-        ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";")
-        : [""];
-    for (const part of parts) {
-        for (const ext of extensions) {
-            try {
-                accessSync(join(part, bin + ext), fsConstants.X_OK);
-                _binaryCache.set(bin, true);
-                return true;
-            }
-            catch { /* keep searching */ }
-        }
+    try {
+        execFileSync("which", [bin], { stdio: "ignore" });
+        _binaryCache.set(bin, true);
+        return true;
+    }
+    catch {
+        _binaryCache.set(bin, false);
+        return false;
     }
-    _binaryCache.set(bin, false);
-    return false;
 }
 /**
  * Relaxed JSON5 parser: removes trailing commas before } or ].
@@ -767,9 +730,6 @@ function loadSkillsFromDir(dir, source) {
  * Searches multiple known installation paths (npm, pnpm, nvm, etc.)
  */
 function resolveBundledSkillsDir() {
-    const override = (process.env.OPENCLAW_BUNDLED_SKILLS_DIR ?? "").trim();
-    if (override)
-        return override;
     const candidates = [];
     // 1. Adjacent to node binary (nvm-style installs)
     try {
@@ -789,7 +749,7 @@ function resolveBundledSkillsDir() {
     }
     catch { }
     // 4. ~/.npm-global/lib/node_modules/openclaw/skills (common npm prefix)
-    const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
+    const home = homedir() || "";
     if (home) {
         candidates.push(join(home, ".npm-global", "lib", "node_modules", "openclaw", "skills"));
     }
@@ -969,7 +929,7 @@ function buildSkillStatus(entry, cfg) {
     const requiresAnyBins = entry.metadata?.requires?.anyBins ?? [];
     const requiresEnv = entry.metadata?.requires?.env ?? [];
     const requiresConfig = entry.metadata?.requires?.config ?? [];
-    const isEnvSatisfied = (name) => Boolean(process.env[name] || skillCfg?.env?.[name] ||
+    const isEnvSatisfied = (name) => Boolean(skillCfg?.env?.[name] ||
         (skillCfg?.apiKey && entry.metadata?.primaryEnv === name));
     const missingBins = always ? [] : requiresBins.filter(b => !hasBinarySync(b));
     const missingAnyBins = always ? [] :
@@ -1022,9 +982,7 @@ function buildSkillStatus(entry, cfg) {
  * Mirrors gateway's fetchJson (clawhub-t8tftw_j.js).
  */
 async function fetchClawHub(path, searchParams) {
-    const baseUrl = ((process.env.OPENCLAW_CLAWHUB_URL ?? "").trim() ||
-        (process.env.CLAWHUB_URL ?? "").trim() ||
-        "https://clawhub.ai").replace(/\/+$/, "");
+    const baseUrl = "https://clawhub.ai";
     let url = `${baseUrl}${path}`;
     if (searchParams && Object.keys(searchParams).length > 0) {
         url += `?${new URLSearchParams(searchParams).toString()}`;
@@ -1289,7 +1247,7 @@ async function handleSkillsInstall(api, params) {
         let archiveBytes;
         try {
             const searchParams = { version };
-            const archiveUrl = ((process.env.OPENCLAW_CLAWHUB_URL ?? process.env.CLAWHUB_URL ?? "https://clawhub.ai").replace(/\/+$/, "")
+            const archiveUrl = ("https://clawhub.ai"
                 + `/api/v1/packages/${encodeURIComponent(slug)}/download?` + new URLSearchParams(searchParams));
             const controller = new AbortController();
             const timer = setTimeout(() => controller.abort(), 60000);
@@ -1535,22 +1493,14 @@ async function handleAgentModelSet(api, params) {
  * 4. Default: ~/.openclaw/cron/jobs.json
  */
 function resolveCronStorePath(api) {
-    const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
+    const home = homedir() || "";
     const expandHome = (p) => p.startsWith("~/") || p === "~" ? join(home, p.slice(2)) : p;
-    // 1. OPENCLAW_STATE_DIR
-    const stateDir = (process.env.OPENCLAW_STATE_DIR ?? "").trim();
-    if (stateDir)
-        return resolve(join(expandHome(stateDir), "cron", "jobs.json"));
-    // 2. OPENCLAW_CONFIG_PATH
-    const configPath = (process.env.OPENCLAW_CONFIG_PATH ?? "").trim();
-    if (configPath)
-        return resolve(join(dirname(expandHome(configPath)), "cron", "jobs.json"));
-    // 3. cfg.cron?.store
+    // cfg.cron?.store
     const cfg = getConfig(api);
     const cfgStore = String(cfg?.cron?.store ?? "").trim();
     if (cfgStore)
         return resolve(expandHome(cfgStore));
-    // 4. Default
+    // Default
     return join(home, ".openclaw", "cron", "jobs.json");
 }
 /**
@@ -1704,7 +1654,8 @@ async function handlePortalRequest(api, accountId, request) {
 // WebSocket connection management (unchanged logic)
 // ---------------------------------------------------------------------------
 function sendResponse(ws, response) {
-    if (ws.readyState === WebSocket.OPEN) {
+    // readyState 1 === OPEN for both native WebSocket and ws library
+    if (ws.readyState === 1) {
         ws.send(JSON.stringify(response));
     }
 }
@@ -1713,9 +1664,18 @@ function connectPortal(api, bridge) {
         return;
     const url = `${bridge.portalWsAddr}/${bridge.botId}`;
     portalLog(api, "info", `connecting to agent-portal: url=${url} botId=${bridge.botId} accountId=${bridge.accountId}`);
+    // Use `ws` library for wss:// to bypass undici globalDispatcher interference
+    const useWsLib = url.startsWith("wss://");
     let ws;
     try {
-        ws = new WebSocket(url);
+        if (useWsLib) {
+            const wsClient = new WsWebSocket(url);
+            // Wrap ws library instance to match WebSocket API used below
+            ws = wsClient;
+        }
+        else {
+            ws = new WebSocket(url);
+        }
     }
     catch (err) {
         portalLog(api, "error", `WebSocket constructor failed: ${err?.message ?? err}`);
@@ -1724,11 +1684,12 @@ function connectPortal(api, bridge) {
     }
     bridge.ws = ws;
     let reconnectAttempts = 0;
+    const READY_STATE_OPEN = useWsLib ? WsWebSocket.OPEN : WebSocket.OPEN;
     ws.addEventListener("open", () => {
         reconnectAttempts = 0;
         portalLog(api, "info", `connected to agent-portal: botId=${bridge.botId}`);
         bridge.heartbeatTimer = setInterval(() => {
-            if (ws.readyState === WebSocket.OPEN) {
+            if (ws.readyState === READY_STATE_OPEN) {
                 const pingMsg = { id: `ping-${Date.now()}`, method: "ping", params: {} };
                 ws.send(JSON.stringify(pingMsg));
                 portalLog(api, "debug", `heartbeat ping sent: botId=${bridge.botId}`);
@@ -1737,14 +1698,19 @@ function connectPortal(api, bridge) {
     });
     ws.addEventListener("message", async (event) => {
         let raw;
-        if (typeof event.data === "string") {
-            raw = event.data;
+        // ws library: event.data is Buffer/string; native: event.data is string/ArrayBuffer
+        const data = event.data ?? event;
+        if (typeof data === "string") {
+            raw = data;
+        }
+        else if (data instanceof ArrayBuffer) {
+            raw = new TextDecoder().decode(data);
         }
-        else if (event.data instanceof ArrayBuffer) {
-            raw = new TextDecoder().decode(event.data);
+        else if (Buffer.isBuffer(data)) {
+            raw = data.toString("utf-8");
         }
         else {
-            portalLog(api, "warn", `unexpected message data type: ${typeof event.data}`);
+            portalLog(api, "warn", `unexpected message data type: ${typeof data}`);
             return;
         }
         let request;
@@ -1764,7 +1730,7 @@ function connectPortal(api, bridge) {
         portalLog(api, "debug", `response sent: id=${request.id} method=${request.method} ok=${!response.error}`);
     });
     ws.addEventListener("close", (event) => {
-        portalLog(api, "info", `disconnected from agent-portal: botId=${bridge.botId} code=${event.code} reason=${event.reason || "none"}`);
+        portalLog(api, "info", `disconnected from agent-portal: botId=${bridge.botId} code=${event.code ?? 1006} reason=${event.reason || "none"}`);
         clearHeartbeat(bridge);
         bridge.ws = null;
         if (!bridge.stopped) {

package/dist/setup.js

@@ -19,15 +19,15 @@ export async function runOpenIMSetup() {
     clackIntro("OpenIM Channel Setup Wizard");
     const token = guardCancel(await clackText({
         message: "Enter OpenIM Access Token",
-        initialValue: process.env.OPENIM_TOKEN || "",
+        initialValue: "",
     }));
     const wsAddr = guardCancel(await clackText({
         message: "Enter OpenIM WebSocket endpoint",
-        initialValue: process.env.OPENIM_WS_ADDR || "ws://127.0.0.1:10001",
+        initialValue: "ws://127.0.0.1:10001",
     }));
     const apiAddr = guardCancel(await clackText({
         message: "Enter OpenIM REST API endpoint",
-        initialValue: process.env.OPENIM_API_ADDR || "http://127.0.0.1:10002",
+        initialValue: "http://127.0.0.1:10002",
     }));
     const trimmedToken = String(token).trim();
     const trimmedWsAddr = String(wsAddr).trim();

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "openclaw-channel",
   "name": "OpenIM Channel",
-  "version": "0.3.6",
+  "version": "0.3.9",
   "description": "OpenIM protocol channel for OpenClaw",
   "author": "ZeyiY",
   "channels": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeyiy/openclaw-channel",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "description": "OpenIM channel plugin for OpenClaw gateway (fork of @openim/openclaw-channel)",
   "license": "AGPL-3.0-only",
   "author": "ZeyiY",
@@ -49,7 +49,9 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.0.0",
-    "@openim/client-sdk": "^3.8.3"
+    "@openim/client-sdk": "^3.8.3",
+    "@types/ws": "^8.18.1",
+    "ws": "^8.20.0"
   },
   "peerDependencies": {
     "clawdbot": "*",