clawmatrix 0.1.2 → 0.1.5

package/llms.txt

@@ -120,7 +120,7 @@ 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 OpenClaw tool names (empty = all 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) |
 

package/openclaw.plugin.json

@@ -59,7 +59,7 @@
             "type": "array",
             "items": { "type": "string" },
             "default": [],
-            "description": "Allowed OpenClaw tool names (e.g. exec, read, write, edit, web_search). Empty = all allowed."
+            "description": "Allowed OpenClaw tool names. Use [\"*\"] for all. Empty or [\"*\"] = all allowed."
           },
           "deny": {
             "type": "array",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawmatrix",
-  "version": "0.1.2",
+  "version": "0.1.5",
   "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

@@ -46,10 +46,11 @@ export class ClusterRuntime {
   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, resolveGatewayInfo(openclawConfig));
+    this.modelProxy = new ModelProxy(config, this.peerManager, gatewayInfo);
+    this.toolProxy = new ToolProxy(config, this.peerManager, gatewayInfo);
   }
 
   start() {
@@ -137,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",
     });

package/src/config.ts

@@ -6,10 +6,29 @@ const AgentInfoSchema = z.object({
   tags: z.array(z.string()).default([]),
 });
 
+const ModelParamsSchema = {
+  api: z.enum([
+    "openai-completions", "openai-responses", "openai-codex-responses",
+    "anthropic-messages", "google-generative-ai", "github-copilot",
+    "bedrock-converse-stream", "ollama",
+  ]).optional(),
+  contextWindow: z.number().optional(),
+  maxTokens: z.number().optional(),
+  reasoning: z.boolean().optional(),
+  input: z.array(z.enum(["text", "image"])).optional(),
+  cost: z.object({
+    input: z.number(),
+    output: z.number(),
+    cacheRead: z.number(),
+    cacheWrite: z.number(),
+  }).optional(),
+};
+
 const ModelInfoSchema = z.object({
   id: z.string(),
   provider: z.string(),
   description: z.string().optional(),
+  ...ModelParamsSchema,
 });
 
 const PeerConfigSchema = z.object({
@@ -24,15 +43,23 @@ const ToolProxyConfigSchema = z.object({
   maxOutputBytes: z.number().default(1_048_576),
 });
 
+const ProxyModelSchema = z.object({
+  id: z.string(),
+  nodeId: z.string().optional(),
+  description: z.string().optional(),
+  ...ModelParamsSchema,
+});
+
 export const ClawMatrixConfigSchema = z.object({
   nodeId: z.string(),
-  secret: z.string(),
+  secret: z.string().min(16, "secret must be at least 16 characters"),
   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([]),
+  proxyModels: z.array(ProxyModelSchema).default([]),
   tags: z.array(z.string()).default([]),
   proxyPort: z.number().default(19001),
   toolProxy: ToolProxyConfigSchema.optional(),

package/src/connection.ts

@@ -1,10 +1,12 @@
 import { EventEmitter } from "node:events";
 import type {
+  AgentInfo,
   AnyClusterFrame,
   AuthChallenge,
   AuthOk,
   AuthFail,
   ClusterFrame,
+  ModelInfo,
   NodeCapabilities,
 } from "./types.ts";
 import { generateNonce, computeHmac, verifyHmac } from "./auth.ts";
@@ -12,6 +14,7 @@ import { generateNonce, computeHmac, verifyHmac } from "./auth.ts";
 const HEARTBEAT_BASE = 12_000;
 const HEARTBEAT_JITTER = 6_000;
 const HEARTBEAT_TIMEOUT_COUNT = 3;
+const AUTH_TIMEOUT = 10_000;
 
 export type ConnectionRole = "inbound" | "outbound";
 
@@ -41,6 +44,7 @@ export class Connection extends EventEmitter<ConnectionEvents> {
   authenticated = false;
 
   private heartbeatTimer: ReturnType<typeof setTimeout> | null = null;
+  private authTimer: ReturnType<typeof setTimeout> | null = null;
   private missedPongs = 0;
   private pendingNonce: string | null = null;
   private closed = false;
@@ -61,6 +65,11 @@ export class Connection extends EventEmitter<ConnectionEvents> {
 
     if (role === "inbound") {
       this.sendAuthChallenge();
+      this.authTimer = setTimeout(() => {
+        if (!this.authenticated) {
+          this.close(4003, "auth timeout");
+        }
+      }, AUTH_TIMEOUT);
     }
   }
 
@@ -142,7 +151,13 @@ export class Connection extends EventEmitter<ConnectionEvents> {
   private async handleAuthMessage(frame: AnyClusterFrame) {
     if (this.role === "inbound") {
       if (frame.type !== "auth") return;
-      const { nodeId, sig } = frame.payload as { nodeId: string; sig: string };
+      const { nodeId, sig, agents, models, tags } = frame.payload as {
+        nodeId: string;
+        sig: string;
+        agents?: AgentInfo[];
+        models?: ModelInfo[];
+        tags?: string[];
+      };
       if (!this.pendingNonce) return;
 
       const valid = await verifyHmac(this.pendingNonce, this.secret, sig);
@@ -160,7 +175,14 @@ export class Connection extends EventEmitter<ConnectionEvents> {
       }
 
       this.remoteNodeId = nodeId;
+      this.remoteCapabilities = {
+        nodeId,
+        agents: agents ?? [],
+        models: models ?? [],
+        tags: tags ?? [],
+      };
       this.authenticated = true;
+      this.clearAuthTimer();
 
       this.sendRaw({
         type: "auth_ok",
@@ -175,12 +197,7 @@ export class Connection extends EventEmitter<ConnectionEvents> {
       } satisfies AuthOk);
 
       this.startHeartbeat();
-      this.emit("authenticated", {
-        nodeId,
-        agents: [],
-        models: [],
-        tags: [],
-      });
+      this.emit("authenticated", this.remoteCapabilities);
     } else {
       if (frame.type === "auth_challenge") {
         const { nonce } = (frame as AuthChallenge).payload;
@@ -189,7 +206,13 @@ export class Connection extends EventEmitter<ConnectionEvents> {
           type: "auth",
           from: this.nodeId,
           timestamp: Date.now(),
-          payload: { nodeId: this.nodeId, sig },
+          payload: {
+            nodeId: this.nodeId,
+            sig,
+            agents: this.localCapabilities.agents,
+            models: this.localCapabilities.models,
+            tags: this.localCapabilities.tags,
+          },
         });
         return;
       }
@@ -217,6 +240,13 @@ export class Connection extends EventEmitter<ConnectionEvents> {
     }
   }
 
+  private clearAuthTimer() {
+    if (this.authTimer) {
+      clearTimeout(this.authTimer);
+      this.authTimer = null;
+    }
+  }
+
   // ── Heartbeat ──────────────────────────────────────────────────
   private startHeartbeat() {
     const scheduleNext = () => {
@@ -243,6 +273,7 @@ export class Connection extends EventEmitter<ConnectionEvents> {
   close(code = 1000, reason = "normal") {
     if (this.closed) return;
     this.closed = true;
+    this.clearAuthTimer();
     if (this.heartbeatTimer) {
       clearTimeout(this.heartbeatTimer);
       this.heartbeatTimer = null;

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

@@ -74,21 +74,39 @@ const plugin = {
         if (peers.length === 0) return;
 
         const lines = [
-          `[ClawMatrix Cluster] This node: ${config.nodeId}`,
-          `Connected peers:`,
+          `[ClawMatrix Cluster]`,
+          `You are on node "${config.nodeId}"${config.tags.length ? ` (tags: ${config.tags.join(", ")})` : ""}.`,
         ];
+
+        if (config.agents.length > 0) {
+          const localAgent = config.agents[0]!;
+          lines.push(`Your role: ${localAgent.description}`);
+        }
+
+        lines.push("", "Remote nodes in the cluster:");
         for (const peer of peers) {
-          const agents = peer.agents.map((a) => a.id).join(", ") || "none";
-          const models = peer.models.map((m) => m.id).join(", ") || "none";
           const status = peer.connection?.isOpen ? "connected" : "via relay";
-          lines.push(
-            `  - ${peer.nodeId} (${status}): agents=[${agents}], models=[${models}]`,
-          );
+          const tags = peer.tags.length ? ` [${peer.tags.join(", ")}]` : "";
+          lines.push(`  - ${peer.nodeId} (${status})${tags}`);
+          for (const agent of peer.agents) {
+            lines.push(`    agent "${agent.id}": ${agent.description}`);
+          }
+          if (peer.models.length > 0) {
+            lines.push(`    models: ${peer.models.map((m) => m.id).join(", ")}`);
+          }
         }
+
         lines.push(
           "",
-          "Available cluster tools: cluster_handoff, cluster_send, cluster_peers, " +
-            "cluster_exec, cluster_read, cluster_write, cluster_tool",
+          "When a task involves resources on a remote node (files, commands, services), " +
+            "use cluster tools to operate there directly:",
+          "  - cluster_exec / cluster_read / cluster_write — run commands, read/write files on a remote node",
+          "  - cluster_tool — invoke any OpenClaw tool on a remote node",
+          "  - cluster_handoff — delegate a complex task to a remote agent for autonomous execution",
+          "  - cluster_send — send a one-way message to a remote agent",
+          "  - cluster_peers — inspect cluster topology",
+          "Use the node's description and tags to decide which node to target. " +
+            "For simple operations, prefer cluster_exec/read/write; for complex multi-step tasks, prefer cluster_handoff.",
         );
 
         return { prependContext: lines.join("\n") };
@@ -100,19 +118,24 @@ const plugin = {
 };
 
 function getAllClusterModels(config: ReturnType<typeof parseConfig>) {
-  // We register placeholder models from config.
-  // The actual model list is dynamic (from cluster peers),
-  // but we need to declare known models at registration time.
-  // The local HTTP proxy handles routing to the right cluster node.
-  return config.models.map((m) => ({
+  // models = models this node serves to the cluster
+  // proxyModels = remote models this node wants to consume from the cluster
+  // Both need to be registered with the OpenClaw provider so it routes requests to our local proxy.
+  const seen = new Set<string>();
+  const all = [...config.models, ...config.proxyModels].filter((m) => {
+    if (seen.has(m.id)) return false;
+    seen.add(m.id);
+    return true;
+  });
+  return all.map((m) => ({
     id: m.id,
-    name: m.id,
-    api: "openai-completions" as const,
-    reasoning: false,
-    input: ["text" as const],
-    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-    contextWindow: 128_000,
-    maxTokens: 4096,
+    name: m.description ?? m.id,
+    api: m.api ?? ("openai-completions" as const),
+    reasoning: m.reasoning ?? false,
+    input: (m.input as Array<"text" | "image">) ?? ["text" as const],
+    cost: m.cost ?? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: m.contextWindow ?? 128_000,
+    maxTokens: m.maxTokens ?? 4096,
   }));
 }
 

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. */
@@ -113,7 +116,11 @@ export class ModelProxy {
     }
 
     const modelId = body.model;
-    const route = this.peerManager.router.resolveModel(modelId);
+    // Check proxyModels for a nodeId routing hint
+    const proxyModel = this.config.proxyModels.find((m) => m.id === modelId);
+    const route = proxyModel?.nodeId
+      ? this.peerManager.router.getRoute(proxyModel.nodeId)
+      : this.peerManager.router.resolveModel(modelId);
     if (!route) {
       return {
         status: 404,
@@ -372,11 +379,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/peer-manager.ts

@@ -256,6 +256,9 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
 
   // ── Message handling ───────────────────────────────────────────
   private onFrame(frame: AnyClusterFrame, from: Connection) {
+    // Validate from field: must be the direct peer or a known node (relayed)
+    if (frame.from && frame.from !== from.remoteNodeId && !this.router.getRoute(frame.from)) return;
+
     if (frame.id && this.router.isDuplicate(frame.id)) return;
 
     if (frame.type === "peer_sync") {

package/src/tool-proxy.ts

@@ -182,10 +182,8 @@ export class ToolProxy {
   // ── Security ───────────────────────────────────────────────────
   private isToolAllowed(tool: string, tpConfig: ToolProxyConfig): boolean {
     if (tpConfig.deny.includes(tool)) return false;
-    if (tpConfig.allow.length > 0) {
-      return tpConfig.allow.includes(tool);
-    }
-    return true;
+    if (tpConfig.allow.length === 0 || tpConfig.allow.includes("*")) return true;
+    return tpConfig.allow.includes(tool);
   }
 
   destroy() {

package/src/types.ts

@@ -17,7 +17,13 @@ export interface AuthChallenge extends ClusterFrame {
 
 export interface AuthRequest extends ClusterFrame {
   type: "auth";
-  payload: { nodeId: string; sig: string };
+  payload: {
+    nodeId: string;
+    sig: string;
+    agents?: AgentInfo[];
+    models?: ModelInfo[];
+    tags?: string[];
+  };
 }
 
 export interface AuthOk extends ClusterFrame {