clawmatrix 0.1.1 → 0.1.3

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. `["*"]` or `[]` = 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. Use [\"*\"] for all. Empty or [\"*\"] = 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.1",
+  "version": "0.1.3",
   "description": "Decentralized mesh cluster plugin for OpenClaw — inter-gateway communication, model proxy, task handoff, and tool proxy.",
   "type": "module",
   "license": "MIT",

package/src/cluster-service.ts

@@ -1,6 +1,7 @@
 import type {
   OpenClawPluginService,
   OpenClawPluginServiceContext,
+  OpenClawConfig,
   PluginLogger,
 } from "openclaw/plugin-sdk";
 import type { ClawMatrixConfig } from "./config.ts";
@@ -8,7 +9,7 @@ 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,
@@ -21,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;
@@ -30,13 +43,14 @@ 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;
+    const gatewayInfo = resolveGatewayInfo(openclawConfig);
     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.modelProxy = new ModelProxy(config, this.peerManager, gatewayInfo);
+    this.toolProxy = new ToolProxy(config, this.peerManager, gatewayInfo);
   }
 
   start() {
@@ -124,8 +138,8 @@ export class ClusterRuntime {
       return;
     }
 
-    // Fire-and-forget: inject message via openclaw agent
-    spawnProcess(["openclaw", "agent", "--message", message], {
+    // Fire-and-forget: inject message via openclaw agent CLI
+    spawnProcess(["openclaw", "agent", "--agent", agent.id, "--message", message], {
       stdout: "ignore",
       stderr: "ignore",
     });
@@ -144,11 +158,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/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

@@ -148,10 +148,10 @@ export class HandoffManager {
         ? `${payload.task}\n\nContext:\n${payload.context}`
         : payload.task;
 
-      const proc = spawnProcess(["openclaw", "agent", "--message", message], {
-        stdout: "pipe",
-        stderr: "pipe",
-      });
+      const proc = spawnProcess(
+        ["openclaw", "agent", "--agent", agent.id, "--message", message],
+        { stdout: "pipe", stderr: "pipe" },
+      );
 
       const stdout = proc.stdout ? await new Response(proc.stdout).text() : "";
       const exitCode = await proc.exited;

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,6 +1,7 @@
 import { createServer, type Server } from "node:http";
 import type { PeerManager } from "./peer-manager.ts";
 import type { ClawMatrixConfig } from "./config.ts";
+import type { GatewayInfo } from "./tool-proxy.ts";
 import type {
   ModelRequest,
   ModelResponse,
@@ -23,10 +24,12 @@ export class ModelProxy {
   private peerManager: PeerManager;
   private pending = new Map<string, PendingModelReq>();
   private httpServer: Server | null = null;
+  private gatewayInfo: GatewayInfo;
 
-  constructor(config: ClawMatrixConfig, peerManager: PeerManager) {
+  constructor(config: ClawMatrixConfig, peerManager: PeerManager, gatewayInfo: GatewayInfo) {
     this.config = config;
     this.peerManager = peerManager;
+    this.gatewayInfo = gatewayInfo;
   }
 
   /** Start the local HTTP proxy server for OpenAI-compatible requests. */
@@ -372,11 +375,13 @@ export class ModelProxy {
     }
 
     try {
-      const localUrl = `http://127.0.0.1:${process.env.OPENCLAW_GATEWAY_PORT ?? 3000}/v1/chat/completions`;
+      const { port, authHeader } = this.gatewayInfo;
+      const headers: Record<string, string> = { "Content-Type": "application/json" };
+      if (authHeader) headers["Authorization"] = authHeader;
 
-      const response = await fetch(localUrl, {
+      const response = await fetch(`http://127.0.0.1:${port}/v1/chat/completions`, {
         method: "POST",
-        headers: { "Content-Type": "application/json" },
+        headers,
         body: JSON.stringify({
           model: `${model.provider}/${model.id}`,
           messages: payload.messages,

package/src/tool-proxy.ts

@@ -1,8 +1,5 @@
-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 { spawnProcess, readFileText, writeFileText } from "./compat.ts";
 import type { ToolProxyRequest, ToolProxyResponse } from "./types.ts";
 
 const TOOL_TIMEOUT = 30_000;
@@ -13,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`);
@@ -79,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);
@@ -113,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,
@@ -127,7 +104,6 @@ export class ToolProxy {
       return;
     }
 
-    // Check tool allowlist/denylist
     if (!this.isToolAllowed(payload.tool, toolProxyConfig)) {
       this.sendResponse(id, from, {
         success: false,
@@ -137,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, {
@@ -180,138 +138,52 @@ 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 = spawnProcess(["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([
-      proc.stdout ? new Response(proc.stdout).text() : "",
-      proc.stderr ? 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 content = await readFileText(path);
-    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 writeFileText(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;
-    if (tpConfig.allow.length > 0) {
-      return tpConfig.allow.includes(tool as "exec" | "read" | "write" | "ls");
-    }
-    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`);
-      }
-    }
+  private isToolAllowed(tool: string, tpConfig: ToolProxyConfig): boolean {
+    if (tpConfig.deny.includes(tool)) return false;
+    if (tpConfig.allow.length === 0 || tpConfig.allow.includes("*")) return true;
+    return tpConfig.allow.includes(tool);
   }
 
   destroy() {

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 },
-        };
-      }
-    },
-  };
-}