clawmatrix 0.1.0

package/README.md

@@ -0,0 +1,15 @@
+# clawmatrix
+
+To install dependencies:
+
+```bash
+bun install
+```
+
+To run:
+
+```bash
+bun run index.ts
+```
+
+This project was created using `bun init` in bun v1.3.6. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.

package/llms.txt

@@ -0,0 +1,191 @@
+# ClawMatrix — OpenClaw Mesh Cluster Plugin
+
+> Decentralized mesh network plugin for OpenClaw. Multiple Gateways install the same plugin, form a peer-to-peer mesh via WebSocket, and share agents, models, and tools across nodes.
+
+## Install
+
+```bash
+openclaw plugins install clawmatrix
+```
+
+Then restart the Gateway:
+
+```bash
+openclaw gateway restart
+```
+
+## What it does
+
+- **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.
+- **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.
+
+## Configuration
+
+Add to `plugins.entries.clawmatrix.config` in your `openclaw.json`:
+
+### Public node (relay + own agents)
+
+```json
+{
+  "nodeId": "cloud-01",
+  "secret": "your-shared-secret",
+  "listen": true,
+  "listenPort": 19000,
+  "peers": [],
+  "agents": [
+    { "id": "reviewer", "description": "Reviews code and PRs", "tags": ["review"] }
+  ],
+  "models": [],
+  "tags": ["cloud"]
+}
+```
+
+### Internal node (has models + code repos)
+
+```json
+{
+  "nodeId": "office-01",
+  "secret": "your-shared-secret",
+  "listen": false,
+  "peers": [
+    { "nodeId": "cloud-01", "url": "wss://cloud-01.example.com:19000" }
+  ],
+  "agents": [
+    { "id": "coder", "description": "Writes and debugs code, has repo access", "tags": ["coding"] }
+  ],
+  "models": [
+    { "id": "claude-sonnet", "provider": "anthropic" },
+    { "id": "deepseek-coder", "provider": "ollama" }
+  ],
+  "tags": ["office", "gpu"],
+  "toolProxy": {
+    "enabled": true,
+    "allow": ["exec", "read", "ls"],
+    "deny": ["write"],
+    "allowPaths": ["/repo", "/data"],
+    "denyPaths": ["/etc", "/root"]
+  }
+}
+```
+
+### Home node (lightweight, borrows cluster resources)
+
+```json
+{
+  "nodeId": "home-01",
+  "secret": "your-shared-secret",
+  "listen": false,
+  "peers": [
+    { "nodeId": "cloud-01", "url": "wss://cloud-01.example.com:19000" }
+  ],
+  "agents": [
+    { "id": "assistant", "description": "Personal assistant", "tags": ["general"] }
+  ],
+  "models": [],
+  "tags": ["home"]
+}
+```
+
+To use cluster models, set your agent's model to a cluster-proxied model:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model": "clawmatrix/claude-sonnet"
+    }
+  }
+}
+```
+
+## Config reference
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `nodeId` | string | *required* | Unique identifier for this node |
+| `secret` | string | *required* | Shared HMAC secret for cluster authentication |
+| `listen` | boolean | `false` | Accept inbound WebSocket connections |
+| `listenHost` | string | `"0.0.0.0"` | Bind address for WebSocket listener |
+| `listenPort` | number | `19000` | Port for inbound WebSocket connections |
+| `peers` | array | `[]` | List of `{ nodeId, url }` peers to connect to |
+| `agents` | array | `[]` | Agents this node provides: `{ id, description, tags }` |
+| `models` | array | `[]` | Models this node shares: `{ id, provider, description? }` |
+| `tags` | array | `[]` | Free-form tags for capability routing |
+| `proxyPort` | number | `19001` | Local HTTP proxy port for model requests |
+| `toolProxy` | object | — | Tool proxy settings (see below) |
+
+### toolProxy
+
+| 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 |
+| `maxOutputBytes` | number | `1048576` | Max output size per tool response (1 MB) |
+
+## Agent tools
+
+ClawMatrix registers 7 tools available to agents:
+
+### cluster_peers
+List all reachable peers, their agents, and available models.
+
+### cluster_handoff
+Hand off a task to another agent in the cluster and wait for the result.
+- `target`: Agent ID or `"tags:<tag>"` expression
+- `task`: Task description
+- `context`: Optional additional context
+
+### cluster_send
+Send a one-way message to another agent (injected into their session).
+- `target`: Agent ID or `"tags:<tag>"` expression
+- `message`: Message content
+
+### cluster_exec
+Execute a shell command on a remote node.
+- `node`: Target nodeId or `"tags:<tag>"`
+- `command`: Shell command
+- `cwd`: Optional working directory
+- `timeout`: Optional timeout in ms (default 30000)
+
+### cluster_read
+Read a file from a remote node.
+- `node`: Target nodeId or `"tags:<tag>"`
+- `path`: Absolute file path
+
+### cluster_write
+Write content to a file on a remote node.
+- `node`: Target nodeId or `"tags:<tag>"`
+- `path`: Absolute file path
+- `content`: File content
+
+### cluster_ls
+List directory contents on a remote node.
+- `node`: Target nodeId or `"tags:<tag>"`
+- `path`: Directory path
+
+## Verify cluster status
+
+```bash
+openclaw clawmatrix status
+```
+
+## Architecture
+
+- Nodes form a decentralized mesh over WebSocket (no leader, no consensus protocol)
+- Authentication via HMAC-SHA256 challenge-response (secret never sent in plaintext)
+- Messages relay through intermediate nodes with TTL-based loop prevention
+- Heartbeat every 15s; 3 missed pings = disconnect + peer_leave broadcast
+- Reconnection with exponential backoff (1s to 60s max)
+- Production deployments should use `wss://` (TLS)
+
+## Source
+
+- GitHub: https://github.com/nicepkg/clawmatrix
+- npm: https://www.npmjs.com/package/clawmatrix

package/openclaw.plugin.json

@@ -0,0 +1,76 @@
+{
+  "id": "clawmatrix",
+  "name": "ClawMatrix",
+  "description": "Decentralized mesh cluster for inter-gateway communication, model proxy, task handoff, and tool proxy.",
+  "providers": ["clawmatrix"],
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "nodeId": { "type": "string" },
+      "secret": { "type": "string" },
+      "listen": { "type": "boolean", "default": false },
+      "listenHost": { "type": "string", "default": "0.0.0.0" },
+      "listenPort": { "type": "number", "default": 19000 },
+      "peers": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "nodeId": { "type": "string" },
+            "url": { "type": "string" }
+          },
+          "required": ["nodeId", "url"]
+        },
+        "default": []
+      },
+      "agents": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "id": { "type": "string" },
+            "description": { "type": "string" },
+            "tags": { "type": "array", "items": { "type": "string" }, "default": [] }
+          },
+          "required": ["id", "description"]
+        },
+        "default": []
+      },
+      "models": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "id": { "type": "string" },
+            "provider": { "type": "string" },
+            "description": { "type": "string" }
+          },
+          "required": ["id", "provider"]
+        },
+        "default": []
+      },
+      "tags": { "type": "array", "items": { "type": "string" }, "default": [] },
+      "proxyPort": { "type": "number", "default": 19001 },
+      "toolProxy": {
+        "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": [] },
+          "maxOutputBytes": { "type": "number", "default": 1048576 }
+        }
+      }
+    },
+    "required": ["nodeId", "secret"]
+  },
+  "uiHints": {
+    "secret": { "sensitive": true, "label": "Cluster Secret", "help": "Shared secret for HMAC authentication between nodes" },
+    "nodeId": { "label": "Node ID", "help": "Unique identifier for this node in the cluster" },
+    "listenHost": { "label": "Listen Host", "help": "Bind address (use 127.0.0.1 with Cloudflare Tunnel)", "advanced": true },
+    "listenPort": { "label": "Listen Port", "help": "Port for inbound WebSocket connections", "advanced": true },
+    "proxyPort": { "label": "Proxy Port", "help": "Port for local model proxy HTTP server", "advanced": true }
+  }
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "clawmatrix",
+  "version": "0.1.0",
+  "description": "Decentralized mesh cluster plugin for OpenClaw — inter-gateway communication, model proxy, task handoff, and tool proxy.",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "mesh",
+    "cluster",
+    "gateway",
+    "decentralized",
+    "model-proxy",
+    "handoff"
+  ],
+  "files": [
+    "src/",
+    "!src/**/*.test.ts",
+    "openclaw.plugin.json",
+    "llms.txt",
+    "README.md"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "test": "bun test",
+    "prepublishOnly": "bun test"
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "openclaw": "^2026.3.2"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}

package/src/auth.ts

@@ -0,0 +1,38 @@
+export function generateNonce(): string {
+  const bytes = crypto.getRandomValues(new Uint8Array(32));
+  return Buffer.from(bytes).toString("hex");
+}
+
+export async function computeHmac(
+  nonce: string,
+  secret: string,
+): Promise<string> {
+  const key = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const sig = await crypto.subtle.sign(
+    "HMAC",
+    key,
+    new TextEncoder().encode(nonce),
+  );
+  return Buffer.from(sig).toString("hex");
+}
+
+export async function verifyHmac(
+  nonce: string,
+  secret: string,
+  sig: string,
+): Promise<boolean> {
+  const expected = await computeHmac(nonce, secret);
+  if (expected.length !== sig.length) return false;
+  // Constant-time comparison
+  let diff = 0;
+  for (let i = 0; i < expected.length; i++) {
+    diff |= expected.charCodeAt(i) ^ sig.charCodeAt(i);
+  }
+  return diff === 0;
+}

package/src/cli.ts

@@ -0,0 +1,84 @@
+import type { Command } from "commander";
+import { getClusterRuntime } from "./cluster-service.ts";
+
+export const registerClusterCli = ({ program }: { program: Command }) => {
+  const cmd = program.command("clawmatrix").description("ClawMatrix cluster management");
+
+  cmd
+    .command("status")
+    .description("Show cluster topology and peer status")
+    .action(() => {
+      let runtime: ReturnType<typeof getClusterRuntime>;
+      try {
+        runtime = getClusterRuntime();
+      } catch {
+        console.log("ClawMatrix service not running.");
+        return;
+      }
+
+      const config = runtime.config;
+      const peers = runtime.peerManager.router.getAllPeers();
+
+      // Header
+      console.log(`\nNode: ${config.nodeId}`);
+      console.log(
+        `Listen: ${config.listen ? `port ${config.listenPort}` : "no"}`,
+      );
+      console.log(`Model proxy: port ${config.proxyPort}`);
+      console.log(`Agents: [${config.agents.map((a) => a.id).join(", ")}]`);
+      console.log(
+        `Models: [${config.models.map((m) => m.id).join(", ")}]`,
+      );
+      console.log("");
+
+      if (peers.length === 0) {
+        console.log("No peers connected.");
+        return;
+      }
+
+      // Peer table
+      const header = padRow("NODE", "AGENTS", "MODELS", "STATUS", "LATENCY");
+      console.log(header);
+      console.log("-".repeat(header.length));
+
+      for (const peer of peers) {
+        const agents = peer.agents.map((a) => a.id).join(", ") || "-";
+        const models = peer.models.map((m) => m.id).join(", ") || "-";
+        const status = peer.connection?.isOpen ? "connected" : "unreachable";
+        const latency = peer.latencyMs > 0 ? `${peer.latencyMs}ms` : "-";
+        console.log(
+          padRow(peer.nodeId, `[${agents}]`, `[${models}]`, status, latency),
+        );
+      }
+      console.log("");
+    });
+
+  cmd
+    .command("peers")
+    .description("List known peers (JSON)")
+    .action(() => {
+      let runtime: ReturnType<typeof getClusterRuntime>;
+      try {
+        runtime = getClusterRuntime();
+      } catch {
+        console.log("[]");
+        return;
+      }
+
+      const peers = runtime.peerManager.router.getAllPeers().map((p) => ({
+        nodeId: p.nodeId,
+        agents: p.agents,
+        models: p.models,
+        tags: p.tags,
+        connected: !!p.connection?.isOpen,
+        reachableVia: p.reachableVia,
+        latencyMs: p.latencyMs,
+      }));
+      console.log(JSON.stringify(peers, null, 2));
+    });
+};
+
+function padRow(...cols: string[]): string {
+  const widths = [16, 24, 30, 14, 8];
+  return cols.map((c, i) => c.padEnd(widths[i] ?? 12)).join("  ");
+}

package/src/cluster-service.ts

@@ -0,0 +1,160 @@
+import type {
+  OpenClawPluginService,
+  OpenClawPluginServiceContext,
+  PluginLogger,
+} from "openclaw/plugin-sdk";
+import type { ClawMatrixConfig } from "./config.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 type {
+  AnyClusterFrame,
+  HandoffRequest,
+  HandoffResponse,
+  ModelRequest,
+  ModelResponse,
+  ModelStreamChunk,
+  SendMessage,
+  ToolProxyRequest,
+  ToolProxyResponse,
+} from "./types.ts";
+
+/** Singleton cluster state shared across plugin components. */
+export class ClusterRuntime {
+  readonly config: ClawMatrixConfig;
+  readonly peerManager: PeerManager;
+  readonly handoffManager: HandoffManager;
+  readonly modelProxy: ModelProxy;
+  readonly toolProxy: ToolProxy;
+  private logger: PluginLogger;
+
+  constructor(config: ClawMatrixConfig, logger: PluginLogger) {
+    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);
+  }
+
+  start() {
+    // Wire up frame dispatch
+    this.peerManager.on("frame", (frame, conn) => {
+      this.dispatchFrame(frame);
+    });
+
+    this.peerManager.on("peerConnected", (nodeId) => {
+      this.logger.info(`[clawmatrix] Peer connected: ${nodeId}`);
+    });
+
+    this.peerManager.on("peerDisconnected", (nodeId) => {
+      this.logger.info(`[clawmatrix] Peer disconnected: ${nodeId}`);
+    });
+
+    // Start subsystems
+    this.peerManager.start();
+    this.modelProxy.start();
+
+    this.logger.info(
+      `[clawmatrix] Node "${this.config.nodeId}" started` +
+        (this.config.listen ? ` (listening on port ${this.config.listenPort})` : "") +
+        ` (model proxy on port ${this.config.proxyPort})`,
+    );
+  }
+
+  async stop() {
+    this.handoffManager.destroy();
+    this.modelProxy.stop();
+    this.toolProxy.destroy();
+    await this.peerManager.stop();
+    this.logger.info(`[clawmatrix] Node "${this.config.nodeId}" stopped`);
+  }
+
+  private dispatchFrame(frame: AnyClusterFrame) {
+    switch (frame.type) {
+      case "handoff_req":
+        this.handoffManager.handleRequest(frame as HandoffRequest).catch((err) => {
+          this.logger.error(`[clawmatrix] Handoff request error: ${err}`);
+        });
+        break;
+      case "handoff_res":
+        this.handoffManager.handleResponse(frame as HandoffResponse);
+        break;
+      case "model_req":
+        this.modelProxy.handleModelRequest(frame as ModelRequest).catch((err) => {
+          this.logger.error(`[clawmatrix] Model request error: ${err}`);
+        });
+        break;
+      case "model_res":
+        this.modelProxy.handleModelResponse(frame as ModelResponse);
+        break;
+      case "model_stream":
+        this.modelProxy.handleModelStream(frame as ModelStreamChunk);
+        break;
+      case "tool_req":
+        this.toolProxy.handleRequest(frame as ToolProxyRequest).catch((err) => {
+          this.logger.error(`[clawmatrix] Tool request error: ${err}`);
+        });
+        break;
+      case "tool_res":
+        this.toolProxy.handleResponse(frame as ToolProxyResponse);
+        break;
+      case "send":
+        this.handleSendMessage(frame as SendMessage);
+        break;
+    }
+  }
+
+  private handleSendMessage(frame: SendMessage) {
+    // Inject message into local agent session via openclaw CLI
+    const { target, message } = frame.payload;
+    const agent = this.config.agents.find((a) => {
+      if (target.startsWith("tags:")) {
+        return a.tags.includes(target.slice(5));
+      }
+      return a.id === target;
+    });
+
+    if (!agent) {
+      this.logger.warn(
+        `[clawmatrix] Received send for unknown target "${target}"`,
+      );
+      return;
+    }
+
+    // Fire-and-forget: inject message via openclaw agent
+    Bun.spawn(["openclaw", "agent", "--message", message], {
+      stdout: "ignore",
+      stderr: "ignore",
+    });
+  }
+}
+
+// ── Singleton accessor ───────────────────────────────────────────
+let clusterRuntime: ClusterRuntime | null = null;
+
+export function getClusterRuntime(): ClusterRuntime {
+  if (!clusterRuntime) {
+    throw new Error("ClawMatrix cluster runtime not initialized");
+  }
+  return clusterRuntime;
+}
+
+export function createClusterService(
+  config: ClawMatrixConfig,
+): OpenClawPluginService {
+  return {
+    id: "clawmatrix",
+    start(ctx: OpenClawPluginServiceContext) {
+      clusterRuntime = new ClusterRuntime(config, ctx.logger);
+      clusterRuntime.start();
+    },
+    async stop() {
+      if (clusterRuntime) {
+        await clusterRuntime.stop();
+        clusterRuntime = null;
+      }
+    },
+  };
+}

package/src/config.ts

@@ -0,0 +1,50 @@
+import { z } from "zod/v4";
+
+const AgentInfoSchema = z.object({
+  id: z.string(),
+  description: z.string(),
+  tags: z.array(z.string()).default([]),
+});
+
+const ModelInfoSchema = z.object({
+  id: z.string(),
+  provider: z.string(),
+  description: z.string().optional(),
+});
+
+const PeerConfigSchema = z.object({
+  nodeId: z.string(),
+  url: z.string(),
+});
+
+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([]),
+  maxOutputBytes: z.number().default(1_048_576),
+});
+
+export const ClawMatrixConfigSchema = z.object({
+  nodeId: z.string(),
+  secret: z.string(),
+  listen: z.boolean().default(false),
+  listenHost: z.string().default("0.0.0.0"),
+  listenPort: z.number().default(19000),
+  peers: z.array(PeerConfigSchema).default([]),
+  agents: z.array(AgentInfoSchema).default([]),
+  models: z.array(ModelInfoSchema).default([]),
+  tags: z.array(z.string()).default([]),
+  proxyPort: z.number().default(19001),
+  toolProxy: ToolProxyConfigSchema.optional(),
+});
+
+export type ClawMatrixConfig = z.infer<typeof ClawMatrixConfigSchema>;
+export type PeerConfig = z.infer<typeof PeerConfigSchema>;
+export type ToolProxyConfig = z.infer<typeof ToolProxyConfigSchema>;
+
+export function parseConfig(raw: unknown): ClawMatrixConfig {
+  return ClawMatrixConfigSchema.parse(raw);
+}