clawmatrix 0.1.0 → 0.1.2

package/llms.txt

@@ -18,7 +18,7 @@ openclaw gateway restart
 
 - **Model Proxy** — Use LLMs hosted on remote nodes as if they were local. A local HTTP proxy bridges cluster WebSocket to OpenAI-compatible API.
 - **Task Handoff** — Delegate complex tasks to agents running on other nodes (e.g. hand off to an internal "coder" agent that has repo access).
-- **Tool Proxy** — Execute single tool calls (shell commands, file read/write, directory listing) on remote nodes without delegating the entire task.
+- **Tool Proxy** — Invoke any OpenClaw tool (exec, read, write, edit, web_search, etc.) on remote nodes without delegating the entire task.
 - **Gossip Discovery** — Nodes discover each other via gossip protocol; no central registry needed.
 - **Auto Failover** — If a node goes down, requests route to backup nodes automatically.
 
@@ -63,10 +63,8 @@ Add to `plugins.entries.clawmatrix.config` in your `openclaw.json`:
   "tags": ["office", "gpu"],
   "toolProxy": {
     "enabled": true,
-    "allow": ["exec", "read", "ls"],
-    "deny": ["write"],
-    "allowPaths": ["/repo", "/data"],
-    "denyPaths": ["/etc", "/root"]
+    "allow": ["exec", "read", "edit", "web_search"],
+    "deny": ["write", "browser", "sessions_spawn"]
   }
 }
 ```
@@ -122,16 +120,13 @@ To use cluster models, set your agent's model to a cluster-proxied model:
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
 | `enabled` | boolean | `false` | Allow remote tool execution on this node |
-| `allow` | array | `[]` | Allowed tools: `"exec"`, `"read"`, `"write"`, `"ls"` |
-| `deny` | array | `[]` | Denied tools (takes precedence over allow) |
-| `allowPaths` | array | `[]` | Allowed path prefixes for file operations |
-| `denyPaths` | array | `[]` | Denied path prefixes |
-| `execAllowlist` | array | `[]` | If non-empty, only these commands are allowed |
+| `allow` | array | `[]` | Allowed OpenClaw tool names (empty = all allowed) |
+| `deny` | array | `[]` | Denied OpenClaw tool names (takes precedence over allow) |
 | `maxOutputBytes` | number | `1048576` | Max output size per tool response (1 MB) |
 
 ## Agent tools
 
-ClawMatrix registers 7 tools available to agents:
+ClawMatrix registers 7 tools available to agents (tool proxy tools correspond to OpenClaw's built-in tools):
 
 ### cluster_peers
 List all reachable peers, their agents, and available models.
@@ -148,27 +143,28 @@ Send a one-way message to another agent (injected into their session).
 - `message`: Message content
 
 ### cluster_exec
-Execute a shell command on a remote node.
+Execute a shell command on a remote node (invokes OpenClaw `exec` tool).
 - `node`: Target nodeId or `"tags:<tag>"`
 - `command`: Shell command
-- `cwd`: Optional working directory
-- `timeout`: Optional timeout in ms (default 30000)
+- `workdir`: Optional working directory
+- `timeout`: Optional timeout in seconds (default 1800)
 
 ### cluster_read
-Read a file from a remote node.
+Read a file from a remote node (invokes OpenClaw `read` tool).
 - `node`: Target nodeId or `"tags:<tag>"`
-- `path`: Absolute file path
+- `path`: File path
 
 ### cluster_write
-Write content to a file on a remote node.
+Write content to a file on a remote node (invokes OpenClaw `write` tool).
 - `node`: Target nodeId or `"tags:<tag>"`
-- `path`: Absolute file path
+- `path`: File path
 - `content`: File content
 
-### cluster_ls
-List directory contents on a remote node.
+### cluster_tool
+Invoke any OpenClaw tool on a remote node (exec, read, write, edit, web_search, web_fetch, browser, process, etc.).
 - `node`: Target nodeId or `"tags:<tag>"`
-- `path`: Directory path
+- `tool`: OpenClaw tool name
+- `args`: Tool arguments (tool-specific)
 
 ## Verify cluster status
 

package/openclaw.plugin.json

@@ -55,11 +55,18 @@
         "type": "object",
         "properties": {
           "enabled": { "type": "boolean", "default": false },
-          "allow": { "type": "array", "items": { "type": "string" }, "default": [] },
-          "deny": { "type": "array", "items": { "type": "string" }, "default": [] },
-          "allowPaths": { "type": "array", "items": { "type": "string" }, "default": [] },
-          "denyPaths": { "type": "array", "items": { "type": "string" }, "default": [] },
-          "execAllowlist": { "type": "array", "items": { "type": "string" }, "default": [] },
+          "allow": {
+            "type": "array",
+            "items": { "type": "string" },
+            "default": [],
+            "description": "Allowed OpenClaw tool names (e.g. exec, read, write, edit, web_search). Empty = all allowed."
+          },
+          "deny": {
+            "type": "array",
+            "items": { "type": "string" },
+            "default": [],
+            "description": "Denied OpenClaw tool names (takes precedence over allow)."
+          },
           "maxOutputBytes": { "type": "number", "default": 1048576 }
         }
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawmatrix",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Decentralized mesh cluster plugin for OpenClaw — inter-gateway communication, model proxy, task handoff, and tool proxy.",
   "type": "module",
   "license": "MIT",
@@ -31,10 +31,12 @@
     "prepublishOnly": "bun test"
   },
   "dependencies": {
+    "ws": "^8.19.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {
     "@types/bun": "latest",
+    "@types/ws": "^8.18.1",
     "openclaw": "^2026.3.2"
   },
   "peerDependencies": {

package/src/cluster-service.ts

@@ -1,13 +1,15 @@
 import type {
   OpenClawPluginService,
   OpenClawPluginServiceContext,
+  OpenClawConfig,
   PluginLogger,
 } from "openclaw/plugin-sdk";
 import type { ClawMatrixConfig } from "./config.ts";
+import { spawnProcess } from "./compat.ts";
 import { PeerManager } from "./peer-manager.ts";
 import { HandoffManager } from "./handoff.ts";
 import { ModelProxy } from "./model-proxy.ts";
-import { ToolProxy } from "./tool-proxy.ts";
+import { ToolProxy, type GatewayInfo } from "./tool-proxy.ts";
 import type {
   AnyClusterFrame,
   HandoffRequest,
@@ -20,6 +22,18 @@ import type {
   ToolProxyResponse,
 } from "./types.ts";
 
+function resolveGatewayInfo(openclawConfig: OpenClawConfig): GatewayInfo {
+  const port = openclawConfig.gateway?.port ?? 18789;
+  const auth = openclawConfig.gateway?.auth;
+  let authHeader: string | undefined;
+  if (auth?.token) {
+    authHeader = `Bearer ${auth.token}`;
+  } else if (auth?.password && typeof auth.password === "string") {
+    authHeader = `Bearer ${auth.password}`;
+  }
+  return { port, authHeader };
+}
+
 /** Singleton cluster state shared across plugin components. */
 export class ClusterRuntime {
   readonly config: ClawMatrixConfig;
@@ -29,13 +43,13 @@ export class ClusterRuntime {
   readonly toolProxy: ToolProxy;
   private logger: PluginLogger;
 
-  constructor(config: ClawMatrixConfig, logger: PluginLogger) {
+  constructor(config: ClawMatrixConfig, logger: PluginLogger, openclawConfig: OpenClawConfig) {
     this.config = config;
     this.logger = logger;
     this.peerManager = new PeerManager(config);
     this.handoffManager = new HandoffManager(config, this.peerManager);
     this.modelProxy = new ModelProxy(config, this.peerManager);
-    this.toolProxy = new ToolProxy(config, this.peerManager);
+    this.toolProxy = new ToolProxy(config, this.peerManager, resolveGatewayInfo(openclawConfig));
   }
 
   start() {
@@ -124,7 +138,7 @@ export class ClusterRuntime {
     }
 
     // Fire-and-forget: inject message via openclaw agent
-    Bun.spawn(["openclaw", "agent", "--message", message], {
+    spawnProcess(["openclaw", "agent", "--message", message], {
       stdout: "ignore",
       stderr: "ignore",
     });
@@ -143,11 +157,12 @@ export function getClusterRuntime(): ClusterRuntime {
 
 export function createClusterService(
   config: ClawMatrixConfig,
+  openclawConfig: OpenClawConfig,
 ): OpenClawPluginService {
   return {
     id: "clawmatrix",
     start(ctx: OpenClawPluginServiceContext) {
-      clusterRuntime = new ClusterRuntime(config, ctx.logger);
+      clusterRuntime = new ClusterRuntime(config, ctx.logger, openclawConfig);
       clusterRuntime.start();
     },
     async stop() {

package/src/compat.ts

@@ -0,0 +1,62 @@
+/**
+ * Runtime compatibility layer — provides Node.js-compatible alternatives
+ * for Bun-specific APIs so the plugin works inside the OpenClaw gateway
+ * (which runs on Node.js).
+ */
+
+import { spawn as cpSpawn } from "node:child_process";
+import { readFile, writeFile } from "node:fs/promises";
+
+export interface SpawnResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+/** Spawn a subprocess and collect stdout/stderr. */
+export function spawnProcess(
+  cmd: string[],
+  opts?: { cwd?: string; stdout?: "pipe" | "ignore"; stderr?: "pipe" | "ignore" },
+): { exited: Promise<number>; stdout: ReadableStream | null; stderr: ReadableStream | null; kill: () => void } {
+  const child = cpSpawn(cmd[0]!, cmd.slice(1), {
+    cwd: opts?.cwd,
+    stdio: [
+      "ignore",
+      opts?.stdout === "ignore" ? "ignore" : "pipe",
+      opts?.stderr === "ignore" ? "ignore" : "pipe",
+    ],
+  });
+
+  const exited = new Promise<number>((resolve, reject) => {
+    child.on("close", (code) => resolve(code ?? 1));
+    child.on("error", reject);
+  });
+
+  function nodeStreamToWeb(stream: import("node:stream").Readable | null): ReadableStream | null {
+    if (!stream) return null;
+    return new ReadableStream({
+      start(controller) {
+        stream.on("data", (chunk: Buffer) => controller.enqueue(chunk));
+        stream.on("end", () => controller.close());
+        stream.on("error", (err) => controller.error(err));
+      },
+    });
+  }
+
+  return {
+    exited,
+    stdout: nodeStreamToWeb(child.stdout),
+    stderr: nodeStreamToWeb(child.stderr),
+    kill: () => child.kill(),
+  };
+}
+
+/** Read a file as text (replaces Bun.file().text()). */
+export async function readFileText(path: string): Promise<string> {
+  return readFile(path, "utf-8");
+}
+
+/** Write text to a file (replaces Bun.write()). */
+export async function writeFileText(path: string, content: string): Promise<void> {
+  await writeFile(path, content, "utf-8");
+}

package/src/config.ts

@@ -19,11 +19,8 @@ const PeerConfigSchema = z.object({
 
 const ToolProxyConfigSchema = z.object({
   enabled: z.boolean().default(false),
-  allow: z.array(z.enum(["exec", "read", "write", "ls"])).default([]),
-  deny: z.array(z.enum(["exec", "read", "write", "ls"])).default([]),
-  allowPaths: z.array(z.string()).default([]),
-  denyPaths: z.array(z.string()).default([]),
-  execAllowlist: z.array(z.string()).default([]),
+  allow: z.array(z.string()).default([]),
+  deny: z.array(z.string()).default([]),
   maxOutputBytes: z.number().default(1_048_576),
 });
 

package/src/handoff.ts

@@ -1,5 +1,6 @@
 import type { PeerManager } from "./peer-manager.ts";
 import type { ClawMatrixConfig } from "./config.ts";
+import { spawnProcess } from "./compat.ts";
 import type {
   HandoffRequest,
   HandoffResponse,
@@ -147,16 +148,16 @@ export class HandoffManager {
         ? `${payload.task}\n\nContext:\n${payload.context}`
         : payload.task;
 
-      const proc = Bun.spawn(["openclaw", "agent", "--message", message], {
+      const proc = spawnProcess(["openclaw", "agent", "--message", message], {
         stdout: "pipe",
         stderr: "pipe",
       });
 
-      const stdout = await new Response(proc.stdout).text();
+      const stdout = proc.stdout ? await new Response(proc.stdout).text() : "";
       const exitCode = await proc.exited;
 
       if (exitCode !== 0) {
-        const stderr = await new Response(proc.stderr).text();
+        const stderr = proc.stderr ? await new Response(proc.stderr).text() : "";
         throw new Error(`Agent exited with code ${exitCode}: ${stderr}`);
       }
 

package/src/index.ts

@@ -7,7 +7,7 @@ import { createClusterPeersTool } from "./tools/cluster-peers.ts";
 import { createClusterExecTool } from "./tools/cluster-exec.ts";
 import { createClusterReadTool } from "./tools/cluster-read.ts";
 import { createClusterWriteTool } from "./tools/cluster-write.ts";
-import { createClusterLsTool } from "./tools/cluster-ls.ts";
+import { createClusterToolTool } from "./tools/cluster-tool.ts";
 import { registerClusterCli } from "./cli.ts";
 
 const plugin = {
@@ -39,7 +39,7 @@ const plugin = {
     const config = parseConfig(api.pluginConfig);
 
     // Background service: manages mesh connections, WS listener, heartbeat
-    api.registerService(createClusterService(config));
+    api.registerService(createClusterService(config, api.config));
 
     // Model provider: register clawmatrix as a provider pointing to local HTTP proxy
     api.registerProvider({
@@ -61,7 +61,7 @@ const plugin = {
     api.registerTool(createClusterExecTool(), { optional: true });
     api.registerTool(createClusterReadTool(), { optional: true });
     api.registerTool(createClusterWriteTool(), { optional: true });
-    api.registerTool(createClusterLsTool(), { optional: true });
+    api.registerTool(createClusterToolTool(), { optional: true });
 
     // CLI subcommand
     api.registerCli(registerClusterCli, { commands: ["clawmatrix"] });
@@ -88,7 +88,7 @@ const plugin = {
         lines.push(
           "",
           "Available cluster tools: cluster_handoff, cluster_send, cluster_peers, " +
-            "cluster_exec, cluster_read, cluster_write, cluster_ls",
+            "cluster_exec, cluster_read, cluster_write, cluster_tool",
         );
 
         return { prependContext: lines.join("\n") };

package/src/model-proxy.ts

@@ -1,3 +1,4 @@
+import { createServer, type Server } from "node:http";
 import type { PeerManager } from "./peer-manager.ts";
 import type { ClawMatrixConfig } from "./config.ts";
 import type {
@@ -21,7 +22,7 @@ export class ModelProxy {
   private config: ClawMatrixConfig;
   private peerManager: PeerManager;
   private pending = new Map<string, PendingModelReq>();
-  private httpServer: ReturnType<typeof Bun.serve> | null = null;
+  private httpServer: Server | null = null;
 
   constructor(config: ClawMatrixConfig, peerManager: PeerManager) {
     this.config = config;
@@ -30,26 +31,28 @@ export class ModelProxy {
 
   /** Start the local HTTP proxy server for OpenAI-compatible requests. */
   start() {
-    this.httpServer = Bun.serve({
-      port: this.config.proxyPort,
-      hostname: "127.0.0.1",
-      routes: {
-        "/v1/chat/completions": {
-          POST: async (req) => this.handleChatCompletion(req),
-        },
-        "/v1/models": {
-          GET: () => this.handleListModels(),
-        },
-      },
-      fetch() {
-        return new Response("Not Found", { status: 404 });
-      },
+    this.httpServer = createServer(async (req, res) => {
+      const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+
+      if (url.pathname === "/v1/chat/completions" && req.method === "POST") {
+        const body = await this.readBody(req);
+        const response = await this.handleChatCompletion(body);
+        this.sendResponse(res, response);
+      } else if (url.pathname === "/v1/models" && req.method === "GET") {
+        const response = this.handleListModels();
+        this.sendResponse(res, response);
+      } else {
+        res.writeHead(404, { "Content-Type": "text/plain" });
+        res.end("Not Found");
+      }
     });
+
+    this.httpServer.listen(this.config.proxyPort, "127.0.0.1");
   }
 
   stop() {
     if (this.httpServer) {
-      this.httpServer.stop();
+      this.httpServer.close();
       this.httpServer = null;
     }
     for (const [, pending] of this.pending) {
@@ -59,8 +62,38 @@ export class ModelProxy {
     this.pending.clear();
   }
 
+  private readBody(req: import("node:http").IncomingMessage): Promise<string> {
+    return new Promise((resolve, reject) => {
+      const chunks: Buffer[] = [];
+      req.on("data", (chunk: Buffer) => chunks.push(chunk));
+      req.on("end", () => resolve(Buffer.concat(chunks).toString()));
+      req.on("error", reject);
+    });
+  }
+
+  private sendResponse(res: import("node:http").ServerResponse, response: { status: number; headers: Record<string, string>; body: string | ReadableStream }) {
+    res.writeHead(response.status, response.headers);
+    if (typeof response.body === "string") {
+      res.end(response.body);
+    } else {
+      // Stream response
+      const reader = response.body.getReader();
+      const pump = (): void => {
+        reader.read().then(({ done, value }) => {
+          if (done) {
+            res.end();
+            return;
+          }
+          res.write(value);
+          pump();
+        }).catch(() => res.end());
+      };
+      pump();
+    }
+  }
+
   // ── HTTP handlers ──────────────────────────────────────────────
-  private async handleChatCompletion(req: Request): Promise<Response> {
+  private async handleChatCompletion(rawBody: string): Promise<{ status: number; headers: Record<string, string>; body: string | ReadableStream }> {
     let body: {
       model: string;
       messages: unknown[];
@@ -70,21 +103,23 @@ export class ModelProxy {
     };
 
     try {
-      body = (await req.json()) as typeof body;
+      body = JSON.parse(rawBody);
     } catch {
-      return new Response(JSON.stringify({ error: "Invalid JSON" }), {
+      return {
         status: 400,
         headers: { "Content-Type": "application/json" },
-      });
+        body: JSON.stringify({ error: "Invalid JSON" }),
+      };
     }
 
     const modelId = body.model;
     const route = this.peerManager.router.resolveModel(modelId);
     if (!route) {
-      return new Response(
-        JSON.stringify({ error: { message: `Model "${modelId}" not found in cluster` } }),
-        { status: 404, headers: { "Content-Type": "application/json" } },
-      );
+      return {
+        status: 404,
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ error: { message: `Model "${modelId}" not found in cluster` } }),
+      };
     }
 
     const stream = body.stream ?? false;
@@ -116,7 +151,7 @@ export class ModelProxy {
     requestId: string,
     targetNodeId: string,
     frame: ModelRequest,
-  ): Response {
+  ): { status: number; headers: Record<string, string>; body: ReadableStream } {
     const encoder = new TextEncoder();
 
     const readable = new ReadableStream({
@@ -159,20 +194,22 @@ export class ModelProxy {
       },
     });
 
-    return new Response(readable, {
+    return {
+      status: 200,
       headers: {
         "Content-Type": "text/event-stream",
         "Cache-Control": "no-cache",
-        Connection: "keep-alive",
+        "Connection": "keep-alive",
       },
-    });
+      body: readable,
+    };
   }
 
   private async handleNonStreamRequest(
     requestId: string,
     targetNodeId: string,
     frame: ModelRequest,
-  ): Promise<Response> {
+  ): Promise<{ status: number; headers: Record<string, string>; body: string }> {
     try {
       const result = await new Promise<ModelResponse["payload"]>(
         (resolve, reject) => {
@@ -199,15 +236,17 @@ export class ModelProxy {
       );
 
       if (!result.success) {
-        return new Response(
-          JSON.stringify({ error: { message: result.error } }),
-          { status: 502, headers: { "Content-Type": "application/json" } },
-        );
+        return {
+          status: 502,
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ error: { message: result.error } }),
+        };
       }
 
-      // OpenAI-compatible response
-      return new Response(
-        JSON.stringify({
+      return {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
           id: `chatcmpl-${requestId}`,
           object: "chat.completion",
           created: Math.floor(Date.now() / 1000),
@@ -227,17 +266,17 @@ export class ModelProxy {
               }
             : undefined,
         }),
-        { headers: { "Content-Type": "application/json" } },
-      );
+      };
     } catch (err) {
-      return new Response(
-        JSON.stringify({ error: { message: err instanceof Error ? err.message : String(err) } }),
-        { status: 502, headers: { "Content-Type": "application/json" } },
-      );
+      return {
+        status: 502,
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ error: { message: err instanceof Error ? err.message : String(err) } }),
+      };
     }
   }
 
-  private handleListModels(): Response {
+  private handleListModels(): { status: number; headers: Record<string, string>; body: string } {
     const models = this.peerManager.router
       .getAllPeers()
       .flatMap((p) =>
@@ -249,10 +288,11 @@ export class ModelProxy {
         })),
       );
 
-    return new Response(
-      JSON.stringify({ object: "list", data: models }),
-      { headers: { "Content-Type": "application/json" } },
-    );
+    return {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ object: "list", data: models }),
+    };
   }
 
   // ── Incoming frame handlers ────────────────────────────────────
@@ -273,7 +313,6 @@ export class ModelProxy {
 
     try {
       if (frame.payload.done) {
-        // Send final chunk with usage if available
         if (frame.payload.usage) {
           const usageChunk = {
             id: `chatcmpl-${frame.id}`,
@@ -310,7 +349,6 @@ export class ModelProxy {
         );
       }
     } catch {
-      // controller may be closed
       clearTimeout(pending.timer);
       this.pending.delete(frame.id);
     }
@@ -320,7 +358,6 @@ export class ModelProxy {
   async handleModelRequest(frame: ModelRequest): Promise<void> {
     const { id, from, payload } = frame;
 
-    // Find the model in our local config
     const model = this.config.models.find((m) => m.id === payload.model);
     if (!model) {
       this.peerManager.sendTo(from, {
@@ -335,9 +372,6 @@ export class ModelProxy {
     }
 
     try {
-      // Use OpenClaw's API to run the model locally
-      // This is done by calling the local gateway's /v1/chat/completions endpoint
-      // The local OpenClaw gateway handles provider routing
       const localUrl = `http://127.0.0.1:${process.env.OPENCLAW_GATEWAY_PORT ?? 3000}/v1/chat/completions`;
 
       const response = await fetch(localUrl, {
@@ -353,7 +387,6 @@ export class ModelProxy {
       });
 
       if (payload.stream) {
-        // Read SSE stream and forward as model_stream frames
         const reader = response.body?.getReader();
         if (!reader) throw new Error("No response body");
 

package/src/peer-manager.ts

@@ -1,5 +1,6 @@
 import { EventEmitter } from "node:events";
-import type { ServerWebSocket } from "bun";
+import { createServer, type IncomingMessage, type Server } from "node:http";
+import { WebSocketServer, WebSocket as WsWebSocket } from "ws";
 import type { ClawMatrixConfig, PeerConfig } from "./config.ts";
 import { Connection } from "./connection.ts";
 import type { WsTransport } from "./connection.ts";
@@ -25,12 +26,13 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
   readonly router: Router;
   private config: ClawMatrixConfig;
   private localCapabilities: NodeCapabilities;
-  private wsServer: ReturnType<typeof Bun.serve> | null = null;
+  private httpServer: Server | null = null;
+  private wss: WebSocketServer | null = null;
   private reconnectTimers = new Map<string, ReturnType<typeof setTimeout>>();
   private reconnectAttempts = new Map<string, number>();
   private stopped = false;
-  /** Map from ServerWebSocket to Connection for inbound connections. */
-  private inboundConnections = new Map<ServerWebSocket<unknown>, Connection>();
+  /** Map from ws WebSocket to Connection for inbound connections. */
+  private inboundConnections = new Map<WsWebSocket, Connection>();
 
   constructor(config: ClawMatrixConfig) {
     super();
@@ -76,50 +78,52 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
       conn.close(1000, "shutdown");
     }
 
-    if (this.wsServer) {
-      this.wsServer.stop();
-      this.wsServer = null;
+    if (this.wss) {
+      this.wss.close();
+      this.wss = null;
+    }
+    if (this.httpServer) {
+      this.httpServer.close();
+      this.httpServer = null;
     }
   }
 
-  // ── Inbound WS server (Bun.serve) ─────────────────────────────
+  // ── Inbound WS server (node:http + ws) ──────────────────────────
   private startListening() {
     const port = this.config.listenPort;
     const hostname = this.config.listenHost;
-    const self = this;
-
-    this.wsServer = Bun.serve<undefined>({
-      port,
-      hostname,
-      fetch(req, server) {
-        if (server.upgrade(req)) {
-          return undefined;
+
+    this.httpServer = createServer((_req, res) => {
+      res.writeHead(426, { "Content-Type": "text/plain" });
+      res.end("WebSocket upgrade required");
+    });
+
+    this.wss = new WebSocketServer({ server: this.httpServer });
+
+    this.wss.on("connection", (ws) => {
+      this.handleInboundOpen(ws);
+
+      ws.on("message", (data) => {
+        const conn = this.inboundConnections.get(ws);
+        if (conn) {
+          conn.feedMessage(typeof data === "string" ? data : String(data));
         }
-        return new Response("WebSocket upgrade required", { status: 426 });
-      },
-      websocket: {
-        open(ws) {
-          self.handleInboundOpen(ws);
-        },
-        message(ws, message) {
-          const conn = self.inboundConnections.get(ws);
-          if (conn) {
-            conn.feedMessage(typeof message === "string" ? message : Buffer.from(message));
-          }
-        },
-        close(ws, code, reason) {
-          const conn = self.inboundConnections.get(ws);
-          if (conn) {
-            conn.feedClose(code, reason);
-            self.inboundConnections.delete(ws);
-          }
-        },
-      },
+      });
+
+      ws.on("close", (code, reason) => {
+        const conn = this.inboundConnections.get(ws);
+        if (conn) {
+          conn.feedClose(code, reason.toString());
+          this.inboundConnections.delete(ws);
+        }
+      });
     });
+
+    this.httpServer.listen(port, hostname);
   }
 
-  private handleInboundOpen(ws: ServerWebSocket<unknown>) {
-    // Wrap Bun's ServerWebSocket into our WsTransport interface
+  private handleInboundOpen(ws: WsWebSocket) {
+    // Wrap ws WebSocket into our WsTransport interface
     const transport: WsTransport = {
       send(data: string) {
         ws.send(data);

package/src/tool-proxy.ts

@@ -1,5 +1,3 @@
-import { readdir, stat } from "node:fs/promises";
-import { join, resolve, normalize } from "node:path";
 import type { PeerManager } from "./peer-manager.ts";
 import type { ClawMatrixConfig, ToolProxyConfig } from "./config.ts";
 import type { ToolProxyRequest, ToolProxyResponse } from "./types.ts";
@@ -12,57 +10,38 @@ interface PendingToolReq {
   timer: ReturnType<typeof setTimeout>;
 }
 
+export interface GatewayInfo {
+  port: number;
+  authHeader?: string;
+}
+
 export class ToolProxy {
   private config: ClawMatrixConfig;
   private peerManager: PeerManager;
   private pending = new Map<string, PendingToolReq>();
+  private gatewayInfo: GatewayInfo;
 
-  constructor(config: ClawMatrixConfig, peerManager: PeerManager) {
+  constructor(config: ClawMatrixConfig, peerManager: PeerManager, gatewayInfo: GatewayInfo) {
     this.config = config;
     this.peerManager = peerManager;
+    this.gatewayInfo = gatewayInfo;
   }
 
   // ── Outbound: request remote execution ─────────────────────────
-  async exec(
+  async invoke(
     node: string,
-    command: string,
-    cwd?: string,
+    tool: string,
+    params: Record<string, unknown>,
     timeout?: number,
-  ): Promise<{ exitCode: number; stdout: string; stderr: string }> {
-    const result = await this.sendToolReq(node, "exec", {
-      command,
-      cwd,
-      timeout: timeout ?? TOOL_TIMEOUT,
-    });
-    return result as { exitCode: number; stdout: string; stderr: string };
-  }
-
-  async read(node: string, path: string): Promise<{ content: string }> {
-    const result = await this.sendToolReq(node, "read", { path });
-    return result as { content: string };
-  }
-
-  async write(
-    node: string,
-    path: string,
-    content: string,
-  ): Promise<{ success: boolean }> {
-    const result = await this.sendToolReq(node, "write", { path, content });
-    return result as { success: boolean };
-  }
-
-  async ls(
-    node: string,
-    path: string,
-  ): Promise<{ entries: { name: string; type: "file" | "dir"; size: number }[] }> {
-    const result = await this.sendToolReq(node, "ls", { path });
-    return result as { entries: { name: string; type: "file" | "dir"; size: number }[] };
+  ): Promise<Record<string, unknown>> {
+    return this.sendToolReq(node, tool, params, timeout);
   }
 
   private async sendToolReq(
     node: string,
-    tool: ToolProxyRequest["payload"]["tool"],
+    tool: string,
     params: Record<string, unknown>,
+    timeout?: number,
   ): Promise<Record<string, unknown>> {
     const route = this.peerManager.router.resolveNode(node);
     if (!route) throw new Error(`Node "${node}" not reachable`);
@@ -78,7 +57,7 @@ export class ToolProxy {
     };
 
     return new Promise((resolve, reject) => {
-      const timeoutMs = (params.timeout as number | undefined) ?? TOOL_TIMEOUT;
+      const timeoutMs = timeout ?? TOOL_TIMEOUT;
       const timer = setTimeout(() => {
         this.pending.delete(id);
         this.peerManager.router.markFailed(id);
@@ -112,12 +91,11 @@ export class ToolProxy {
     }
   }
 
-  // ── Incoming request: execute locally ──────────────────────────
+  // ── Incoming request: execute via local Gateway ────────────────
   async handleRequest(frame: ToolProxyRequest): Promise<void> {
     const { id, from, payload } = frame;
     const toolProxyConfig = this.config.toolProxy;
 
-    // Check if tool proxy is enabled
     if (!toolProxyConfig?.enabled) {
       this.sendResponse(id, from, {
         success: false,
@@ -126,7 +104,6 @@ export class ToolProxy {
       return;
     }
 
-    // Check tool allowlist/denylist
     if (!this.isToolAllowed(payload.tool, toolProxyConfig)) {
       this.sendResponse(id, from, {
         success: false,
@@ -136,25 +113,7 @@ export class ToolProxy {
     }
 
     try {
-      let result: Record<string, unknown>;
-
-      switch (payload.tool) {
-        case "exec":
-          result = await this.executeExec(payload.params, toolProxyConfig);
-          break;
-        case "read":
-          result = await this.executeRead(payload.params, toolProxyConfig);
-          break;
-        case "write":
-          result = await this.executeWrite(payload.params, toolProxyConfig);
-          break;
-        case "ls":
-          result = await this.executeLs(payload.params, toolProxyConfig);
-          break;
-        default:
-          throw new Error(`Unknown tool: ${payload.tool}`);
-      }
-
+      const result = await this.executeViaGateway(payload.tool, payload.params);
       this.sendResponse(id, from, { success: true, result });
     } catch (err) {
       this.sendResponse(id, from, {
@@ -179,141 +138,56 @@ export class ToolProxy {
     } as ToolProxyResponse);
   }
 
-  // ── Local execution ────────────────────────────────────────────
-  private async executeExec(
+  // ── Gateway tool invocation ────────────────────────────────────
+  private async executeViaGateway(
+    tool: string,
     params: Record<string, unknown>,
-    tpConfig: ToolProxyConfig,
   ): Promise<Record<string, unknown>> {
-    const command = params.command as string;
-    if (!command) throw new Error("Missing command");
-
-    // Check exec allowlist
-    if (tpConfig.execAllowlist.length > 0) {
-      const base = command.split(/\s+/)[0]!;
-      if (!tpConfig.execAllowlist.includes(base)) {
-        throw new Error(`Command "${base}" not in exec allowlist`);
-      }
-    }
-
-    const cwd = (params.cwd as string) ?? process.cwd();
-    const timeout = (params.timeout as number) ?? TOOL_TIMEOUT;
-
-    const proc = Bun.spawn(["sh", "-c", command], {
-      cwd,
-      stdout: "pipe",
-      stderr: "pipe",
+    const { port, authHeader } = this.gatewayInfo;
+    const headers: Record<string, string> = { "Content-Type": "application/json" };
+    if (authHeader) headers["Authorization"] = authHeader;
+
+    const res = await fetch(`http://127.0.0.1:${port}/tools/invoke`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ tool, args: params }),
     });
 
-    const timeoutId = setTimeout(() => proc.kill(), timeout);
-
-    const [stdout, stderr] = await Promise.all([
-      new Response(proc.stdout).text(),
-      new Response(proc.stderr).text(),
-    ]);
-    const exitCode = await proc.exited;
-    clearTimeout(timeoutId);
-
-    const maxBytes = tpConfig.maxOutputBytes;
-    return {
-      exitCode,
-      stdout: stdout.slice(0, maxBytes),
-      stderr: stderr.slice(0, maxBytes),
-    };
-  }
-
-  private async executeRead(
-    params: Record<string, unknown>,
-    tpConfig: ToolProxyConfig,
-  ): Promise<Record<string, unknown>> {
-    const path = params.path as string;
-    if (!path) throw new Error("Missing path");
-    this.validatePath(path, tpConfig);
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`Gateway tool invocation failed (${res.status}): ${text}`);
+    }
 
-    const file = Bun.file(path);
-    const content = await file.text();
-    return {
-      content: content.slice(0, tpConfig.maxOutputBytes),
+    const body = (await res.json()) as {
+      ok: boolean;
+      result?: unknown;
+      error?: { type: string; message: string };
     };
-  }
-
-  private async executeWrite(
-    params: Record<string, unknown>,
-    tpConfig: ToolProxyConfig,
-  ): Promise<Record<string, unknown>> {
-    const path = params.path as string;
-    const content = params.content as string;
-    if (!path || content === undefined) throw new Error("Missing path or content");
-    this.validatePath(path, tpConfig);
-
-    await Bun.write(path, content);
-    return { success: true };
-  }
-
-  private async executeLs(
-    params: Record<string, unknown>,
-    tpConfig: ToolProxyConfig,
-  ): Promise<Record<string, unknown>> {
-    const path = params.path as string;
-    if (!path) throw new Error("Missing path");
-    this.validatePath(path, tpConfig);
 
-    const dirEntries = await readdir(path, { withFileTypes: true });
-    const entries: { name: string; type: "file" | "dir"; size: number }[] = [];
+    if (!body.ok) {
+      throw new Error(body.error?.message ?? "Tool invocation failed");
+    }
 
-    for (const entry of dirEntries) {
-      const fullPath = join(path, entry.name);
-      try {
-        const st = await stat(fullPath);
-        entries.push({
-          name: entry.name,
-          type: entry.isDirectory() ? "dir" : "file",
-          size: Number(st.size),
-        });
-      } catch {
-        entries.push({
-          name: entry.name,
-          type: entry.isDirectory() ? "dir" : "file",
-          size: 0,
-        });
-      }
+    const maxBytes = this.config.toolProxy?.maxOutputBytes ?? 1_048_576;
+    const resultStr = JSON.stringify(body.result);
+    if (resultStr.length > maxBytes) {
+      return { truncated: true, result: resultStr.slice(0, maxBytes) };
     }
 
-    return { entries };
+    return typeof body.result === "object" && body.result !== null
+      ? (body.result as Record<string, unknown>)
+      : { result: body.result };
   }
 
   // ── Security ───────────────────────────────────────────────────
-  private isToolAllowed(
-    tool: string,
-    tpConfig: ToolProxyConfig,
-  ): boolean {
-    if (tpConfig.deny.includes(tool as "exec" | "read" | "write" | "ls")) return false;
+  private isToolAllowed(tool: string, tpConfig: ToolProxyConfig): boolean {
+    if (tpConfig.deny.includes(tool)) return false;
     if (tpConfig.allow.length > 0) {
-      return tpConfig.allow.includes(tool as "exec" | "read" | "write" | "ls");
+      return tpConfig.allow.includes(tool);
     }
     return true;
   }
 
-  private validatePath(path: string, tpConfig: ToolProxyConfig) {
-    const normalized = normalize(resolve(path));
-
-    // Check deny paths first
-    for (const denied of tpConfig.denyPaths) {
-      if (normalized.startsWith(normalize(resolve(denied)))) {
-        throw new Error(`Path "${path}" is in denied path prefix`);
-      }
-    }
-
-    // Check allow paths
-    if (tpConfig.allowPaths.length > 0) {
-      const allowed = tpConfig.allowPaths.some((p) =>
-        normalized.startsWith(normalize(resolve(p))),
-      );
-      if (!allowed) {
-        throw new Error(`Path "${path}" is not in allowed path prefixes`);
-      }
-    }
-  }
-
   destroy() {
     for (const [, pending] of this.pending) {
       clearTimeout(pending.timer);

package/src/tools/cluster-exec.ts

@@ -19,28 +19,32 @@ export function createClusterExecTool(): AnyAgentTool {
           type: "string",
           description: "Shell command to execute",
         },
-        cwd: {
+        workdir: {
           type: "string",
           description: "Working directory (optional)",
         },
         timeout: {
           type: "number",
-          description: "Timeout in milliseconds (default 30000)",
+          description: "Timeout in seconds (default 1800)",
         },
       },
       required: ["node", "command"],
     },
     async execute(_toolCallId, params) {
-      const { node, command, cwd, timeout } = params as {
+      const { node, command, workdir, timeout } = params as {
         node: string;
         command: string;
-        cwd?: string;
+        workdir?: string;
         timeout?: number;
       };
 
       try {
         const runtime = getClusterRuntime();
-        const result = await runtime.toolProxy.exec(node, command, cwd, timeout);
+        const result = await runtime.toolProxy.invoke(
+          node,
+          "exec",
+          { command, workdir, timeout },
+        );
         return {
           content: [
             {

package/src/tools/cluster-read.ts

@@ -15,7 +15,7 @@ export function createClusterReadTool(): AnyAgentTool {
         },
         path: {
           type: "string",
-          description: "Absolute file path to read",
+          description: "File path to read",
         },
       },
       required: ["node", "path"],
@@ -25,10 +25,13 @@ export function createClusterReadTool(): AnyAgentTool {
 
       try {
         const runtime = getClusterRuntime();
-        const result = await runtime.toolProxy.read(node, path);
+        const result = await runtime.toolProxy.invoke(node, "read", { path });
         return {
           content: [
-            { type: "text" as const, text: result.content },
+            {
+              type: "text" as const,
+              text: JSON.stringify(result, null, 2),
+            },
           ],
           details: result,
         };

package/src/tools/cluster-tool.ts

@@ -0,0 +1,63 @@
+import type { AnyAgentTool } from "openclaw/plugin-sdk";
+import { getClusterRuntime } from "../cluster-service.ts";
+
+export function createClusterToolTool(): AnyAgentTool {
+  return {
+    name: "cluster_tool",
+    label: "Cluster Tool",
+    description:
+      "Invoke any OpenClaw tool on a remote cluster node. " +
+      "Supports all tools available on the remote node (exec, read, write, edit, " +
+      "web_search, web_fetch, browser, process, etc.). " +
+      "Use nodeId or 'tags:<tag>' to specify the target.",
+    parameters: {
+      type: "object",
+      properties: {
+        node: {
+          type: "string",
+          description: 'Target nodeId or "tags:<tag>"',
+        },
+        tool: {
+          type: "string",
+          description: "Tool name to invoke (e.g. exec, read, write, edit, web_search, web_fetch, browser, process)",
+        },
+        args: {
+          type: "object",
+          description: "Tool arguments (tool-specific)",
+        },
+      },
+      required: ["node", "tool", "args"],
+    },
+    async execute(_toolCallId, params) {
+      const { node, tool, args } = params as {
+        node: string;
+        tool: string;
+        args: Record<string, unknown>;
+      };
+
+      try {
+        const runtime = getClusterRuntime();
+        const result = await runtime.toolProxy.invoke(node, tool, args);
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+          details: result,
+        };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Tool error: ${err instanceof Error ? err.message : String(err)}`,
+            },
+          ],
+          details: { error: true },
+        };
+      }
+    },
+  };
+}

package/src/tools/cluster-write.ts

@@ -15,7 +15,7 @@ export function createClusterWriteTool(): AnyAgentTool {
         },
         path: {
           type: "string",
-          description: "Absolute file path to write",
+          description: "File path to write",
         },
         content: {
           type: "string",
@@ -33,14 +33,16 @@ export function createClusterWriteTool(): AnyAgentTool {
 
       try {
         const runtime = getClusterRuntime();
-        const result = await runtime.toolProxy.write(node, path, content);
+        const result = await runtime.toolProxy.invoke(
+          node,
+          "write",
+          { path, content },
+        );
         return {
           content: [
             {
               type: "text" as const,
-              text: result.success
-                ? `Successfully wrote to ${path} on ${node}`
-                : `Write failed on ${node}`,
+              text: JSON.stringify(result, null, 2),
             },
           ],
           details: result,

package/src/types.ts

@@ -133,7 +133,7 @@ export interface ToolProxyRequest extends ClusterFrame {
   type: "tool_req";
   id: string;
   payload: {
-    tool: "exec" | "read" | "write" | "ls";
+    tool: string;
     params: Record<string, unknown>;
   };
 }

package/src/tools/cluster-ls.ts

@@ -1,51 +0,0 @@
-import type { AnyAgentTool } from "openclaw/plugin-sdk";
-import { getClusterRuntime } from "../cluster-service.ts";
-
-export function createClusterLsTool(): AnyAgentTool {
-  return {
-    name: "cluster_ls",
-    label: "Cluster Ls",
-    description: "List directory contents on a remote cluster node.",
-    parameters: {
-      type: "object",
-      properties: {
-        node: {
-          type: "string",
-          description: 'Target nodeId or "tags:<tag>"',
-        },
-        path: {
-          type: "string",
-          description: "Absolute directory path to list",
-        },
-      },
-      required: ["node", "path"],
-    },
-    async execute(_toolCallId, params) {
-      const { node, path } = params as { node: string; path: string };
-
-      try {
-        const runtime = getClusterRuntime();
-        const result = await runtime.toolProxy.ls(node, path);
-        return {
-          content: [
-            {
-              type: "text" as const,
-              text: JSON.stringify(result.entries, null, 2),
-            },
-          ],
-          details: result,
-        };
-      } catch (err) {
-        return {
-          content: [
-            {
-              type: "text" as const,
-              text: `Ls error: ${err instanceof Error ? err.message : String(err)}`,
-            },
-          ],
-          details: { error: true },
-        };
-      }
-    },
-  };
-}