openclaw-webchat-plugin 0.1.0

package/README.md

@@ -0,0 +1,99 @@
+# openclaw-webchat-plugin
+
+Browser WebChat channel for OpenClaw. Chat with your OpenClaw agents directly from a web browser — no third-party IM platform needed.
+
+## Prerequisites
+
+- OpenClaw Gateway >= 2026.3.28
+- A WebChat Chat Server running at a public (or reachable) address
+
+## Install
+
+```bash
+openclaw plugins install openclaw-webchat-plugin
+```
+
+## Quick Start
+
+### 1. Deploy the Chat Server
+
+On any machine with a public IP (or reachable from both browser and plugin), clone the [repo](https://github.com/wutao667/openclaw-wechat) and run:
+
+```bash
+git clone https://github.com/wutao667/openclaw-wechat.git
+cd openclaw-wechat/server
+npm install
+node server.js
+```
+
+The Chat Server listens on port `3100`:
+- Browser → `ws://<host>:3100/ws`
+- Plugin → `ws://<host>:3100/plugin`
+
+For production, add a TLS reverse proxy (Caddy/Nginx) for WSS support.
+
+### 2. Configure Channel
+
+Edit `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "channels": {
+    "webchat": {
+      "enabled": true,
+      "serverUrl": "wss://your-domain.com/plugin",
+      "pluginId": "webchat-openclaw-plugin",
+      "agents": [
+        { "agentId": "main", "name": "我的助手" }
+      ]
+    }
+  }
+}
+```
+
+| Field | Description | Default |
+|-------|-------------|---------|
+| `enabled` | Enable this channel | `true` |
+| `serverUrl` | Chat Server `/plugin` WebSocket URL | `ws://localhost:3100/plugin` |
+| `agents` | Agents exposed to browser users | `[{ agentId: "nezha", name: "哪吒" }]` |
+| `dmPolicy` | Direct message policy | `open` |
+
+### 3. Restart Gateway
+
+```bash
+openclaw gateway restart
+```
+
+### 4. Open Browser
+
+Visit `https://your-domain.com`, enter a username, select an agent, and start chatting.
+
+## Architecture
+
+```
+Browser ──WS──→ Chat Server (public) ──WS──→ Plugin ──dispatch──→ OpenClaw Core → Agent
+```
+
+The plugin initiates an outbound WebSocket connection to the Chat Server (long-connection, not webhook). This means OpenClaw instances behind NAT/firewalls can still connect as long as they have outbound internet access.
+
+## Multiple OpenClaw Instances
+
+Each instance installs the plugin with a different `agentId`, all connecting to the same Chat Server. The server routes messages by `agentId`.
+
+```json
+// Instance A
+{ "agents": [{ "agentId": "instance-a", "name": "Bot A" }] }
+
+// Instance B
+{ "agents": [{ "agentId": "instance-b", "name": "Bot B" }] }
+```
+
+## Session Isolation
+
+- Session key: `webchat:{userId}:{agentId}`
+- Same user + same agent across browsers → shared history
+- Different users → completely isolated
+
+## Development
+
+Full source code at [github.com/wutao667/openclaw-wechat](https://github.com/wutao667/openclaw-wechat).

package/index.js

@@ -0,0 +1,17 @@
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { webchatPlugin } from "./src/channel.js";
+import { setWebChatRuntime } from "./src/runtime.js";
+
+const plugin = {
+  id: "webchat-openclaw-plugin",
+  name: "WebChat",
+  description: "Browser WebChat channel for OpenClaw",
+  configSchema: emptyPluginConfigSchema(),
+
+  register(api) {
+    setWebChatRuntime(api.runtime);
+    api.registerChannel({ plugin: webchatPlugin });
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,38 @@
+{
+  "id": "webchat-openclaw-plugin",
+  "kind": "channel",
+  "channels": ["webchat"],
+  "name": "WebChat",
+  "description": "Browser-based WebChat channel for OpenClaw",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  },
+  "channelConfigs": {
+    "webchat": {
+      "schema": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "enabled": { "type": "boolean" },
+          "serverUrl": { "type": "string", "description": "Chat Server WebSocket URL" },
+          "pluginId": { "type": "string" },
+          "agents": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "agentId": { "type": "string" },
+                "name": { "type": "string" }
+              },
+              "required": ["agentId"]
+            }
+          },
+          "allowFrom": { "type": "array", "items": { "type": "string" } },
+          "dmPolicy": { "type": "string", "enum": ["open", "allowlist", "pairing"] }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "openclaw-webchat-plugin",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "index.js",
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.3.28"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.js"
+    ],
+    "channel": {
+      "id": "webchat",
+      "label": "WebChat",
+      "selectionLabel": "WebChat",
+      "blurb": "Browser chat channel for OpenClaw"
+    }
+  }
+}

package/src/accounts.js

@@ -0,0 +1,27 @@
+import { DEFAULT_ACCOUNT_ID, DEFAULT_PLUGIN_ID, DEFAULT_SERVER_URL } from "./const.js";
+
+export function resolveWebChatConfig(cfg) {
+  if (!cfg || !cfg.channels) return {};
+  return cfg.channels.webchat || {};
+}
+
+export function listWebChatAccountIds(_cfg) {
+  return [DEFAULT_ACCOUNT_ID];
+}
+
+export function resolveDefaultWebChatAccountId(_cfg) {
+  return DEFAULT_ACCOUNT_ID;
+}
+
+export function resolveWebChatAccount(cfg, accountId = DEFAULT_ACCOUNT_ID) {
+  const section = resolveWebChatConfig(cfg);
+  return {
+    accountId,
+    enabled: section.enabled !== false,
+    serverUrl: section.serverUrl || DEFAULT_SERVER_URL,
+    pluginId: section.pluginId || DEFAULT_PLUGIN_ID,
+    agents: section.agents || [{ agentId: "nezha", name: "哪吒" }],
+    allowFrom: section.allowFrom || ["*"],
+    dmPolicy: section.dmPolicy || "open",
+  };
+}

package/src/channel.js

@@ -0,0 +1,101 @@
+import { CHANNEL_ID, TEXT_CHUNK_LIMIT } from "./const.js";
+import { startWebChatWsClient, stopWebChatWsClient, sendOutgoingMessage } from "./ws-client.js";
+import { listWebChatAccountIds, resolveWebChatAccount, resolveDefaultWebChatAccountId } from "./accounts.js";
+import { getWebChatRuntime } from "./runtime.js";
+
+export const webchatPlugin = {
+  id: CHANNEL_ID,
+  meta: {
+    label: "WebChat",
+    selectionLabel: "WebChat",
+    blurb: "Browser chat channel for OpenClaw",
+  },
+
+  capabilities: {
+    blockStreaming: true,
+    directChatOnly: true,
+  },
+
+  config: {
+    listAccountIds: listWebChatAccountIds,
+    resolveAccount: async ({ cfg, accountId }) => resolveWebChatAccount(cfg, accountId),
+    isConfigured: async ({ cfg, accountId }) => {
+      const account = resolveWebChatAccount(cfg, accountId);
+      return account.enabled;
+    },
+    describeAccount: async ({ cfg, accountId }) => {
+      const account = resolveWebChatAccount(cfg, accountId);
+      return {
+        label: CHANNEL_ID,
+        description: "WebChat channel",
+        configured: account.enabled,
+        inbound: true,
+        outbound: true,
+      };
+    },
+    resolveAllowFrom: async ({ cfg, accountId }) => {
+      const account = resolveWebChatAccount(cfg, accountId);
+      return { allowFrom: account.allowFrom };
+    },
+  },
+
+  security: {
+    resolveDmPolicy: async ({ cfg, accountId }) => {
+      const account = resolveWebChatAccount(cfg, accountId);
+      return account.dmPolicy;
+    },
+  },
+
+  messaging: {
+    normalizeTarget: async ({ to }) => {
+      return { target: to };
+    },
+    targetResolver: async ({ to }) => {
+      const result = { targets: [{ to, chatId: to }] };
+      return result;
+    },
+  },
+
+  outbound: {
+    deliveryMode: "gateway",
+    chunker: (text, limit) => getWebChatRuntime().channel.text.chunkMarkdownText(text, limit),
+    textChunkLimit: TEXT_CHUNK_LIMIT,
+    sendText: async ({ to, text, accountId, cfg }) => {
+      return sendOutgoingMessage({ to, text, accountId, cfg });
+    },
+  },
+
+  status: {
+    defaultRuntime: async ({ cfg }) => {
+      return {
+        accountId: resolveDefaultWebChatAccountId(cfg),
+        status: "starting",
+      };
+    },
+    collectStatusIssues: async ({ cfg, accountId }) => {
+      const account = resolveWebChatAccount(cfg, accountId);
+      const issues = [];
+      if (!account.enabled) {
+        issues.push({ kind: "warning", message: "WebChat channel is disabled" });
+      }
+      return issues;
+    },
+    buildChannelSummary: async ({ cfg, accountId }) => {
+      const account = resolveWebChatAccount(cfg, accountId);
+      return { label: CHANNEL_ID, summary: `WebChat: ${account.serverUrl}` };
+    },
+  },
+
+  gateway: {
+    startAccount: async ({ cfg, accountId }) => {
+      const account = resolveWebChatAccount(cfg, accountId);
+      const runtime = getWebChatRuntime();
+      startWebChatWsClient(runtime, account);
+      return { accountId };
+    },
+    logoutAccount: async ({ cfg, accountId }) => {
+      stopWebChatWsClient();
+      return { accountId };
+    },
+  },
+};

package/src/const.js

@@ -0,0 +1,5 @@
+export const CHANNEL_ID = "webchat";
+export const DEFAULT_ACCOUNT_ID = "default";
+export const DEFAULT_PLUGIN_ID = "webchat-openclaw-plugin";
+export const DEFAULT_SERVER_URL = process.env.WEBCHAT_SERVER_URL || "ws://localhost:3100/plugin";
+export const TEXT_CHUNK_LIMIT = 3500;

package/src/runtime.js

@@ -0,0 +1,6 @@
+import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
+
+const { setRuntime: setWebChatRuntime, getRuntime: getWebChatRuntime } =
+  createPluginRuntimeStore("WebChat runtime not initialized");
+
+export { setWebChatRuntime, getWebChatRuntime };

package/src/ws-client.js

@@ -0,0 +1,257 @@
+import fs from "fs";
+import path from "path";
+import os from "os";
+import { WebSocket } from "ws";
+import { CHANNEL_ID } from "./const.js";
+
+let state = {
+  ws: null,
+  runtime: null,
+  account: null,
+  reconnectTimer: null,
+  heartbeatTimer: null,
+  reconnectAttempts: 0,
+  intentionalClose: false,
+  fullCfg: {},
+};
+
+function loadGatewayConfig() {
+  try {
+    const configPath = path.resolve(os.homedir(), ".openclaw/openclaw.json");
+    const content = fs.readFileSync(configPath, "utf8");
+    return JSON.parse(content);
+  } catch (err) {
+    console.warn("[webchat] could not load gateway config:", err.message);
+    return {};
+  }
+}
+
+function clearReconnectTimer() {
+  if (state.reconnectTimer) {
+    clearTimeout(state.reconnectTimer);
+    state.reconnectTimer = null;
+  }
+}
+
+function clearHeartbeatTimer() {
+  if (state.heartbeatTimer) {
+    clearInterval(state.heartbeatTimer);
+    state.heartbeatTimer = null;
+  }
+}
+
+function startHeartbeat() {
+  clearHeartbeatTimer();
+  state.heartbeatTimer = setInterval(() => {
+    if (state.ws?.readyState === WebSocket.OPEN) {
+      state.ws.send(JSON.stringify({ type: "ping", pluginId: state.account?.pluginId }));
+    }
+  }, 30_000);
+}
+
+function scheduleReconnect() {
+  if (state.intentionalClose || state.reconnectTimer) return;
+
+  state.reconnectAttempts += 1;
+  const delay = Math.min(30_000, Math.max(2_000, 2 ** state.reconnectAttempts * 1_000));
+
+  state.reconnectTimer = setTimeout(() => {
+    state.reconnectTimer = null;
+    connectWebSocket();
+  }, delay);
+}
+
+function connectWebSocket() {
+  const account = state.account;
+  if (!account?.serverUrl) return;
+
+  clearReconnectTimer();
+  clearHeartbeatTimer();
+
+  const ws = new WebSocket(account.serverUrl);
+  state.ws = ws;
+
+  ws.on("open", () => {
+    state.reconnectAttempts = 0;
+    ws.send(
+      JSON.stringify({
+        type: "register",
+        pluginId: account.pluginId,
+        agents: account.agents,
+      }),
+    );
+    startHeartbeat();
+  });
+
+  ws.on("message", async (data) => {
+    let message;
+    try {
+      message = JSON.parse(String(data));
+    } catch (err) {
+      console.error("[webchat] failed to parse websocket message", err);
+      return;
+    }
+
+    if (message.type === "incoming") {
+      try {
+        await dispatchIncoming(message);
+      } catch (err) {
+        console.error("[webchat] failed to dispatch incoming message", err);
+      }
+      return;
+    }
+
+    if (message.type === "registered") {
+      console.log("[webchat] registered with chat server");
+      return;
+    }
+
+    if (message.type === "agent_list") {
+      console.log("[webchat] agent list received", message.agents || []);
+    }
+  });
+
+  ws.on("close", () => {
+    if (state.ws === ws) {
+      state.ws = null;
+    }
+    clearHeartbeatTimer();
+    if (!state.intentionalClose) {
+      scheduleReconnect();
+    }
+  });
+
+  ws.on("error", (err) => {
+    console.error("[webchat] websocket error", err);
+    ws.close();
+  });
+}
+
+export function startWebChatWsClient(runtime, account) {
+  state.runtime = runtime;
+  state.account = account;
+  state.fullCfg = loadGatewayConfig();
+  state.intentionalClose = false;
+  connectWebSocket();
+}
+
+export function stopWebChatWsClient() {
+  state.intentionalClose = true;
+  clearReconnectTimer();
+  clearHeartbeatTimer();
+
+  if (state.ws) {
+    state.ws.close();
+    state.ws = null;
+  }
+}
+
+export function sendOutgoingMessage({ to, text, accountId, cfg }) {
+  const acc = state.account;
+  const rawTo = String(to || "");
+  let userId = rawTo.replace(/^webchat:/, "");
+  if (!userId) {
+    userId = rawTo.match(/webchat:([^:\s/]+)/)?.[1] || rawTo.match(/([^:\s/]+)$/)?.[1] || "";
+  }
+
+  const agentId = acc?.agents?.[0]?.agentId || "default";
+  const messageId = `webchat_out_${Date.now()}`;
+
+  if (!state.ws || state.ws.readyState !== WebSocket.OPEN) {
+    throw new Error("WebChat websocket is not connected");
+  }
+
+  state.ws.send(
+    JSON.stringify({
+      type: "outgoing",
+      pluginId: acc?.pluginId,
+      agentId,
+      userId,
+      content: text,
+      messageId,
+    }),
+  );
+
+  return { channel: CHANNEL_ID, messageId, chatId: userId };
+}
+
+async function dispatchIncoming(message) {
+  const core = state.runtime;
+  if (!core) return;
+
+  const content = String(message.content || message.Body || "");
+  const userId = String(message.userId || "");
+  const userName = String(message.userName || userId);
+  const agentId = String(message.agentId || "");
+  const conversationId = String(message.conversationId || userId);
+  const acc = state.account;
+  const cfg = state.fullCfg || {};
+
+  const route = core.channel.routing.resolveAgentRoute({
+    cfg,
+    channel: CHANNEL_ID,
+    accountId: acc.accountId,
+    peer: { kind: "direct", id: conversationId },
+    agentId: agentId || acc.agents?.[0]?.agentId || "default",
+  });
+
+  route.sessionKey = `${CHANNEL_ID}:${userId}:${agentId}`;
+
+  const storePath = core.channel.session.resolveStorePath(cfg.session?.store, {
+    agentId: route.agentId,
+  });
+
+  const ctxPayload = core.channel.reply.finalizeInboundContext({
+    Body: content,
+    RawBody: content,
+    CommandBody: content,
+    MessageSid: message.messageId || `webchat_${Date.now()}`,
+    From: `${CHANNEL_ID}:${userId}`,
+    To: `${CHANNEL_ID}:${conversationId}`,
+    SenderId: userId,
+    SessionKey: route.sessionKey,
+    AccountId: route.accountId,
+    ChatType: "direct",
+    ConversationLabel: `user:${userName}`,
+    Timestamp: Date.now(),
+    Provider: CHANNEL_ID,
+    Surface: CHANNEL_ID,
+    OriginatingChannel: CHANNEL_ID,
+    OriginatingTo: `${CHANNEL_ID}:${conversationId}`,
+    CommandAuthorized: true,
+  });
+
+  await core.channel.session.recordInboundSession({
+    storePath,
+    sessionKey: ctxPayload.SessionKey || route.sessionKey,
+    ctx: ctxPayload,
+    updateLastRoute: {
+      sessionKey: route.mainSessionKey || route.sessionKey,
+      channel: CHANNEL_ID,
+      to: `${CHANNEL_ID}:${conversationId}`,
+      accountId: route.accountId,
+    },
+  });
+
+  await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+    ctx: ctxPayload,
+    cfg,
+    dispatcherOptions: {
+      deliver: async (payload) => {
+        if (!payload.text) return;
+        if (state.ws?.readyState === WebSocket.OPEN) {
+          state.ws.send(
+            JSON.stringify({
+              type: "outgoing",
+              pluginId: acc.pluginId,
+              agentId: message.agentId,
+              userId,
+              content: payload.text,
+              messageId: `webchat_reply_${Date.now()}`,
+            }),
+          );
+        }
+      },
+    },
+  });
+}