clawmatrix 0.1.14 → 0.1.15

package/BOOTSTRAP.md

@@ -122,7 +122,8 @@ openclaw clawmatrix status
   ],
   "models": [],
   "proxyModels": [
-    { "id": "claude-sonnet", "nodeId": "office-01" }
+    { "id": "gpt-5", "nodeId": "office-01", "description": "GPT-5", "input": ["text", "image"], "contextWindow": 400000, "maxTokens": 128000 },
+    { "id": "gemini-2.5-pro", "nodeId": "office-01", "description": "Gemini 2.5 Pro", "input": ["text", "image"], "contextWindow": 1048576, "maxTokens": 65535 }
   ],
   "tags": ["home"]
 }
@@ -165,9 +166,40 @@ openclaw clawmatrix status
 | `toolProxy.deny` | array | `[]` | 禁止的工具名（优先于 allow） |
 | `toolProxy.maxOutputBytes` | number | `1048576` | 单次响应最大字节数 |
 
-## 安装后 Agent 获得的工具
+## 启用集群工具
 
-安装后，本节点的 Agent 自动获得 7 个集群工具：
+ClawMatrix 的 Agent 工具注册为可选工具（optional），需要在 OpenClaw 配置中显式启用。
+
+在 `openclaw.json` 中添加：
+
+```json
+{
+  "tools": {
+    "allow": ["clawmatrix"]
+  }
+}
+```
+
+或按 Agent 粒度启用：
+
+```json
+{
+  "agents": {
+    "list": [
+      {
+        "id": "main",
+        "tools": {
+          "allow": ["clawmatrix"]
+        }
+      }
+    ]
+  }
+}
+```
+
+> 如果不配置，Agent 的系统提示中会提到集群工具，但实际无法调用。
+
+启用后，本节点的 Agent 获得 7 个集群工具：
 
 | 工具 | 用途 | 关键参数 |
 |------|------|----------|
@@ -199,13 +231,13 @@ openclaw clawmatrix status
         "api": "openai-completions",
         "models": [
           {
-            "id": "<模型ID>",
-            "name": "<显示名>",
+            "id": "gpt-5",
+            "name": "GPT-5",
             "reasoning": false,
-            "input": ["text"],
+            "input": ["text", "image"],
             "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
-            "contextWindow": 200000,
-            "maxTokens": 32000
+            "contextWindow": 400000,
+            "maxTokens": 128000
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawmatrix",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "Decentralized mesh cluster plugin for OpenClaw — inter-gateway communication, model proxy, task handoff, and tool proxy.",
   "type": "module",
   "license": "MIT",
@@ -41,6 +41,8 @@
     "@types/ws": "^8.18.1"
   },
   "peerDependencies": {
+    "openclaw": ">=2026.3.7",
     "typescript": "^5"
-  }
+  },
+  "overrides": {}
 }

package/src/cluster-service.ts

@@ -46,11 +46,11 @@ export class ClusterRuntime {
   readonly toolProxy: ToolProxy;
   private logger: PluginLogger;
 
-  constructor(config: ClawMatrixConfig, logger: PluginLogger, openclawConfig: OpenClawConfig) {
+  constructor(config: ClawMatrixConfig, logger: PluginLogger, openclawConfig: OpenClawConfig, openclawVersion?: string) {
     this.config = config;
     this.logger = logger;
     const gatewayInfo = resolveGatewayInfo(openclawConfig);
-    this.peerManager = new PeerManager(config);
+    this.peerManager = new PeerManager(config, openclawVersion);
     this.handoffManager = new HandoffManager(config, this.peerManager);
     this.modelProxy = new ModelProxy(config, this.peerManager, gatewayInfo, openclawConfig);
     this.toolProxy = new ToolProxy(config, this.peerManager, gatewayInfo);
@@ -72,7 +72,7 @@ export class ClusterRuntime {
 
     // Web dashboard (must be set before peerManager.start() creates the HTTP server)
     if (this.config.web?.enabled) {
-      const webHandler = new WebHandler(this.config, this.peerManager);
+      const webHandler = new WebHandler(this.config, this.peerManager, this.handoffManager);
       this.peerManager.setHttpHandler((req, res) => webHandler.handle(req, res));
       this.logger.info(`[clawmatrix] Web dashboard enabled on listen port`);
     }
@@ -178,11 +178,12 @@ export function getClusterRuntime(): ClusterRuntime {
 export function createClusterService(
   config: ClawMatrixConfig,
   openclawConfig: OpenClawConfig,
+  openclawVersion?: string,
 ): OpenClawPluginService {
   return {
     id: "clawmatrix",
     start(ctx: OpenClawPluginServiceContext) {
-      clusterRuntime = new ClusterRuntime(config, ctx.logger, openclawConfig);
+      clusterRuntime = new ClusterRuntime(config, ctx.logger, openclawConfig, openclawVersion);
       clusterRuntime.start();
     },
     async stop() {

package/src/config.ts

@@ -61,19 +61,28 @@ const ToolProxyConfigSchema = z.object({
   maxOutputBytes: z.number().default(1_048_576),
 });
 
-const ProxyModelSchema = z.object({
+// Per-model entry inside a proxy group (minimal — inherits group-level fields)
+const ProxyModelEntrySchema = z.object({
   id: z.string(),
-  nodeId: z.string().optional(),
   description: z.string().optional(),
   ...ModelParamsSchema,
 });
 
+// Grouped proxy models: shared nodeId/api/provider, list of models
+const ProxyModelGroupSchema = z.object({
+  nodeId: z.string(),
+  provider: z.string().optional(),
+  description: z.string().optional(),
+  ...ModelParamsSchema,
+  models: z.array(ProxyModelEntrySchema),
+});
+
 const WebConfigSchema = z.object({
   enabled: z.boolean().default(false),
   token: z.string().min(8, "web token must be at least 8 characters"),
 }).optional();
 
-export const ClawMatrixConfigSchema = z.object({
+const RawClawMatrixConfigSchema = z.object({
   nodeId: z.string(),
   secret: z.string().min(16, "secret must be at least 16 characters"),
   listen: z.boolean().default(false),
@@ -82,7 +91,7 @@ export const ClawMatrixConfigSchema = z.object({
   peers: z.array(PeerConfigSchema).default([]),
   agents: z.array(AgentInfoSchema).default([]),
   models: z.array(ModelInfoSchema).default([]),
-  proxyModels: z.array(ProxyModelSchema).default([]),
+  proxyModels: z.array(ProxyModelGroupSchema).default([]),
   tags: z.array(z.string()).default([]),
   proxyPort: z.number().default(19001),
   toolProxy: ToolProxyConfigSchema.optional(),
@@ -90,10 +99,52 @@ export const ClawMatrixConfigSchema = z.object({
   web: WebConfigSchema,
 });
 
-export type ClawMatrixConfig = z.infer<typeof ClawMatrixConfigSchema>;
+/** Flat proxy model after group expansion (used internally). */
+export interface ProxyModel {
+  id: string;
+  nodeId: string;
+  provider?: string;
+  description?: string;
+  api?: string;
+  contextWindow?: number;
+  maxTokens?: number;
+  reasoning?: boolean;
+  input?: ("text" | "image")[];
+  cost?: { input: number; output: number; cacheRead: number; cacheWrite: number };
+  compat?: z.infer<typeof ModelCompatSchema>;
+}
+
+export type ClawMatrixConfig = Omit<z.infer<typeof RawClawMatrixConfigSchema>, "proxyModels"> & {
+  proxyModels: ProxyModel[];
+};
+
+export { RawClawMatrixConfigSchema as ClawMatrixConfigSchema };
 export type PeerConfig = z.infer<typeof PeerConfigSchema>;
 export type ToolProxyConfig = z.infer<typeof ToolProxyConfigSchema>;
 
+/** Parse and flatten grouped proxyModels into flat array. */
 export function parseConfig(raw: unknown): ClawMatrixConfig {
-  return ClawMatrixConfigSchema.parse(raw);
+  const parsed = RawClawMatrixConfigSchema.parse(raw);
+
+  // Flatten proxy model groups
+  const proxyModels: ProxyModel[] = [];
+  for (const group of parsed.proxyModels) {
+    for (const m of group.models) {
+      proxyModels.push({
+        id: m.id,
+        nodeId: group.nodeId,
+        provider: group.provider,
+        description: m.description ?? group.description,
+        api: m.api ?? group.api,
+        contextWindow: m.contextWindow ?? group.contextWindow,
+        maxTokens: m.maxTokens ?? group.maxTokens,
+        reasoning: m.reasoning ?? group.reasoning,
+        input: m.input ?? group.input,
+        cost: m.cost ?? group.cost,
+        compat: m.compat ?? group.compat,
+      });
+    }
+  }
+
+  return { ...parsed, proxyModels };
 }

package/src/connection.ts

@@ -6,6 +6,7 @@ import type {
   AuthOk,
   AuthFail,
   ClusterFrame,
+  DeviceInfo,
   ModelInfo,
   NodeCapabilities,
 } from "./types.ts";
@@ -28,6 +29,7 @@ export interface WsTransport {
 export interface ConnectionEvents {
   message: [frame: AnyClusterFrame];
   authenticated: [capabilities: NodeCapabilities];
+  latency: [ms: number];
   close: [code: number, reason: string];
   error: [error: Error];
 }
@@ -48,6 +50,9 @@ export class Connection extends EventEmitter<ConnectionEvents> {
   private missedPongs = 0;
   private pendingNonce: string | null = null;
   private closed = false;
+  private lastPingSentAt = 0;
+  /** Exponential moving average of heartbeat RTT in milliseconds. */
+  latencyMs = 0;
 
   constructor(
     transport: WsTransport,
@@ -142,6 +147,12 @@ export class Connection extends EventEmitter<ConnectionEvents> {
     }
     if (frame.type === "pong") {
       this.missedPongs = 0;
+      if (this.lastPingSentAt > 0) {
+        const rtt = Date.now() - this.lastPingSentAt;
+        // Exponential moving average (α = 0.3)
+        this.latencyMs = this.latencyMs === 0 ? rtt : Math.round(this.latencyMs * 0.7 + rtt * 0.3);
+        this.emit("latency", this.latencyMs);
+      }
       return;
     }
 
@@ -151,12 +162,13 @@ export class Connection extends EventEmitter<ConnectionEvents> {
   private async handleAuthMessage(frame: AnyClusterFrame) {
     if (this.role === "inbound") {
       if (frame.type !== "auth") return;
-      const { nodeId, sig, agents, models, tags } = frame.payload as {
+      const { nodeId, sig, agents, models, tags, deviceInfo } = frame.payload as {
         nodeId: string;
         sig: string;
         agents?: AgentInfo[];
         models?: ModelInfo[];
         tags?: string[];
+        deviceInfo?: DeviceInfo;
       };
       if (!this.pendingNonce) return;
 
@@ -180,6 +192,7 @@ export class Connection extends EventEmitter<ConnectionEvents> {
         agents: agents ?? [],
         models: models ?? [],
         tags: tags ?? [],
+        deviceInfo,
       };
       this.authenticated = true;
       this.clearAuthTimer();
@@ -193,8 +206,9 @@ export class Connection extends EventEmitter<ConnectionEvents> {
           agents: this.localCapabilities.agents,
           models: this.localCapabilities.models,
           tags: this.localCapabilities.tags,
+          deviceInfo: this.localCapabilities.deviceInfo,
         },
-      } satisfies AuthOk);
+      } as AuthOk);
 
       this.startHeartbeat();
       this.emit("authenticated", this.remoteCapabilities);
@@ -212,6 +226,7 @@ export class Connection extends EventEmitter<ConnectionEvents> {
             agents: this.localCapabilities.agents,
             models: this.localCapabilities.models,
             tags: this.localCapabilities.tags,
+            deviceInfo: this.localCapabilities.deviceInfo,
           },
         });
         return;
@@ -225,6 +240,7 @@ export class Connection extends EventEmitter<ConnectionEvents> {
           agents: ok.payload.agents,
           models: ok.payload.models,
           tags: ok.payload.tags,
+          deviceInfo: ok.payload.deviceInfo,
         };
         this.authenticated = true;
         this.startHeartbeat();
@@ -258,10 +274,11 @@ export class Connection extends EventEmitter<ConnectionEvents> {
           this.close(4002, "heartbeat timeout");
           return;
         }
+        this.lastPingSentAt = Date.now();
         this.sendRaw({
           type: "ping",
           from: this.nodeId,
-          timestamp: Date.now(),
+          timestamp: this.lastPingSentAt,
         });
         scheduleNext();
       }, interval);

package/src/device-info.ts

@@ -0,0 +1,48 @@
+/**
+ * Collect local device/system information using Node.js os module.
+ */
+import { arch, cpus, hostname, totalmem, type, release } from "node:os";
+import { dirname, join } from "node:path";
+import { readFileSync } from "node:fs";
+import type { DeviceInfo } from "./types.ts";
+
+function readVersionFromPkgJson(dir: string): string | undefined {
+  try {
+    const raw = readFileSync(join(dir, "package.json"), "utf-8");
+    const pkg = JSON.parse(raw) as { name?: string; version?: string };
+    if (pkg.name === "openclaw" && pkg.version) return pkg.version;
+  } catch { /* not found */ }
+  return undefined;
+}
+
+function resolveOpenclawVersion(hint?: string): string | undefined {
+  if (hint && hint !== "unknown") return hint;
+  // Walk up from the OpenClaw entry script (process.argv[1]) to find package.json
+  try {
+    const entry = process.argv[1];
+    if (!entry) return undefined;
+    let dir = dirname(entry);
+    for (let i = 0; i < 10; i++) {
+      const v = readVersionFromPkgJson(dir);
+      if (v) return v;
+      const parent = dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  } catch { /* best effort */ }
+  return undefined;
+}
+
+/** Collect device info once at startup. */
+export function collectDeviceInfo(openclawVersion?: string): DeviceInfo {
+  const cpuList = cpus();
+  return {
+    os: `${type()} ${release()}`,
+    arch: arch(),
+    cpuModel: cpuList[0]?.model?.trim() ?? "unknown",
+    cpuCores: cpuList.length,
+    totalMemoryMB: Math.round(totalmem() / (1024 * 1024)),
+    hostname: hostname(),
+    openclawVersion: resolveOpenclawVersion(openclawVersion),
+  };
+}

package/src/handoff.ts

@@ -19,6 +19,7 @@ interface PendingHandoff {
   task: string;
   context?: string;
   accumulated: string;
+  onStream?: (delta: string) => void;
 }
 
 export class HandoffManager {
@@ -36,13 +37,19 @@ export class HandoffManager {
     target: string,
     task: string,
     context?: string,
+    options?: { nodeId?: string; onStream?: (delta: string) => void },
   ): Promise<HandoffResponse["payload"]> {
+    if (options?.nodeId) {
+      // Direct node targeting (e.g. from web UI) — skip router resolution
+      return this.sendHandoff(options.nodeId, target, task, context, 0, options.onStream);
+    }
+
     const route = this.peerManager.router.resolveAgent(target);
     if (!route) {
       throw new Error(`No reachable agent for target "${target}"`);
     }
 
-    return this.sendHandoff(route.nodeId, target, task, context, MAX_RETRIES);
+    return this.sendHandoff(route.nodeId, target, task, context, MAX_RETRIES, options?.onStream);
   }
 
   private sendHandoff(
@@ -51,13 +58,14 @@ export class HandoffManager {
     task: string,
     context: string | undefined,
     retriesLeft: number,
+    onStream?: (delta: string) => void,
   ): Promise<HandoffResponse["payload"]> {
     const id = crypto.randomUUID();
 
     return new Promise<HandoffResponse["payload"]>((resolve, reject) => {
-      const timer = this.createTimeout(id, targetNodeId, target, task, context, retriesLeft, resolve, reject);
+      const timer = this.createTimeout(id, targetNodeId, target, task, context, retriesLeft, resolve, reject, onStream);
 
-      this.pending.set(id, { resolve, reject, timer, target, retriesLeft, task, context, accumulated: "" });
+      this.pending.set(id, { resolve, reject, timer, target, retriesLeft, task, context, accumulated: "", onStream });
 
       const frame: HandoffRequest = {
         type: "handoff_req",
@@ -77,7 +85,7 @@ export class HandoffManager {
         if (retriesLeft > 0) {
           const nextRoute = this.peerManager.router.resolveAgent(target);
           if (nextRoute && nextRoute.nodeId !== targetNodeId) {
-            this.sendHandoff(nextRoute.nodeId, target, task, context, retriesLeft - 1)
+            this.sendHandoff(nextRoute.nodeId, target, task, context, retriesLeft - 1, onStream)
               .then(resolve)
               .catch(reject);
             return;
@@ -97,6 +105,7 @@ export class HandoffManager {
     retriesLeft: number,
     resolve: (result: HandoffResponse["payload"]) => void,
     reject: (error: Error) => void,
+    onStream?: (delta: string) => void,
   ): ReturnType<typeof setTimeout> {
     return setTimeout(() => {
       this.pending.delete(id);
@@ -106,7 +115,7 @@ export class HandoffManager {
       if (retriesLeft > 0) {
         const nextRoute = this.peerManager.router.resolveAgent(target);
         if (nextRoute && nextRoute.nodeId !== targetNodeId) {
-          this.sendHandoff(nextRoute.nodeId, target, task, context, retriesLeft - 1)
+          this.sendHandoff(nextRoute.nodeId, target, task, context, retriesLeft - 1, onStream)
             .then(resolve)
             .catch(reject);
           return;
@@ -125,6 +134,11 @@ export class HandoffManager {
 
     pending.accumulated += frame.payload.delta;
 
+    // Notify stream listener
+    if (pending.onStream && frame.payload.delta) {
+      pending.onStream(frame.payload.delta);
+    }
+
     // Reset timeout — the remote agent is still working
     clearTimeout(pending.timer);
     pending.timer = this.createTimeout(
@@ -136,6 +150,7 @@ export class HandoffManager {
       pending.retriesLeft,
       pending.resolve,
       pending.reject,
+      pending.onStream,
     );
   }
 

package/src/index.ts

@@ -39,7 +39,7 @@ const plugin = {
     const config = parseConfig(api.pluginConfig);
 
     // Background service: manages mesh connections, WS listener, heartbeat
-    api.registerService(createClusterService(config, api.config));
+    api.registerService(createClusterService(config, api.config, api.runtime.version));
 
     // Model providers: register per-node providers so models are accessed as nodeId/modelId
     const baseUrl = `http://127.0.0.1:${config.proxyPort}/v1`;
@@ -50,12 +50,21 @@ const plugin = {
     // We must patch BOTH api.config (cfgAtStart) AND the runtimeConfigSnapshot
     // (returned by loadConfig()) because activateSecretsRuntimeSnapshot clones the
     // config before plugins load, so api.config and the snapshot are separate objects.
+    // Determine per-node API type from proxyModels (all models in a group share the same api)
+    const nodeApiType: Record<string, string> = {};
+    for (const m of config.proxyModels) {
+      if (m.api && !nodeApiType[m.nodeId]) {
+        nodeApiType[m.nodeId] = m.api;
+      }
+    }
+
     const patchProviders = (cfg: Record<string, unknown>) => {
       const models = ((cfg).models ??= {}) as Record<string, unknown>;
       const providers = (models.providers ??= {}) as Record<string, unknown>;
       for (const [nodeId, nodeModels] of Object.entries(modelsByNode)) {
         if (!providers[nodeId]) {
-          providers[nodeId] = { baseUrl, apiKey: "sk-clawmatrix-proxy", api: "openai-completions", models: nodeModels };
+          const api = nodeApiType[nodeId] ?? "openai-completions";
+          providers[nodeId] = { baseUrl, apiKey: "sk-clawmatrix-proxy", api, models: nodeModels };
         }
       }
     };
@@ -63,7 +72,8 @@ const plugin = {
     patchProviders(api.config as Record<string, unknown>);
 
     // Also patch the runtime config snapshot (loadConfig returns it by reference).
-    // api.runtime.config.loadConfig() returns runtimeConfigSnapshot directly.
+    // activateSecretsRuntimeSnapshot clones the config, so api.config and the
+    // snapshot returned by loadConfig() are separate objects — patch both.
     try {
       const snapshot = api.runtime.config.loadConfig();
       if (snapshot && snapshot !== api.config) {
@@ -199,7 +209,7 @@ const plugin = {
           "This ensures the user always knows when operations leave the local node.",
         );
 
-        return { prependContext: lines.join("\n") };
+        return { prependSystemContext: lines.join("\n") };
       } catch {
         return;
       }