clawmatrix 0.1.11 → 0.1.13

package/BOOTSTRAP.md

@@ -92,15 +92,16 @@ openclaw clawmatrix status
   "tags": ["office", "gpu"],
   "toolProxy": {
     "enabled": true,
-    "allow": ["exec", "read", "write", "edit", "web_search"],
-    "deny": ["browser", "sessions_spawn"]
+    "allow": ["*"],
+    "deny": []
   }
 }
 ```
 
 注意事项：
-- `models` 里填这台机器上 OpenClaw 已经配置好的模型（必须本地能用才行）
-- **必须开启 OpenClaw 的 chatCompletions HTTP 端点**，否则模型代理无法工作（见下方「前置配置」）
+- `models` 里的 `provider` 必须与 OpenClaw `models.providers` 中的 key 一致，ClawMatrix 会自动读取对应的 `baseUrl` 和 `apiKey`
+- 如果需要覆盖（比如用不同的 API 地址），可以显式设置 `baseUrl` 和 `apiKey`
+- ClawMatrix 直接调模型 API，不经过 OpenClaw Gateway 的 agent 系统
 - `toolProxy.enabled: true` 才会接受远程工具调用
 - `toolProxy.deny` 优先于 `allow`，建议禁用高风险工具
 
@@ -154,13 +155,13 @@ openclaw clawmatrix status
 | `listenPort` | number | `19000` | 入站 WebSocket 端口 |
 | `peers` | array | `[]` | 要连接的 peer：`{ nodeId, url }` |
 | `agents` | array | `[]` | 本节点提供的 Agent：`{ id, description, tags }` |
-| `models` | array | `[]` | 本节点共享给集群的模型：`{ id, provider, description? }` |
+| `models` | array | `[]` | 本节点共享给集群的模型：`{ id, provider }`（自动读取 OpenClaw provider 的 baseUrl/apiKey，可选覆盖）|
 | `proxyModels` | array | `[]` | 从集群消费的远程模型：`{ id, nodeId?, description? }` |
 | `tags` | array | `[]` | 自由标签，用于能力路由 |
 | `proxyPort` | number | `19001` | 本地模型代理 HTTP 端口 |
 | `handoffTimeout` | number | `600000` | Handoff 超时（毫秒，默认 10 分钟） |
 | `toolProxy.enabled` | boolean | `false` | 允许远程工具执行 |
-| `toolProxy.allow` | array | `[]` | 允许的工具名（`[]` 或 `["*"]` = 全部允许） |
+| `toolProxy.allow` | array | `[]` | 允许的工具名，`["*"]` 或 `[]` 表示全部。`exec`/`read`/`write`/`edit` 本地执行，其余走 Gateway |
 | `toolProxy.deny` | array | `[]` | 禁止的工具名（优先于 allow） |
 | `toolProxy.maxOutputBytes` | number | `1048576` | 单次响应最大字节数 |
 
@@ -181,26 +182,6 @@ openclaw clawmatrix status
 `target` 参数支持 Agent ID（如 `"coder"`）或标签查询（如 `"tags:coding"`）。
 `node` 参数支持 nodeId（如 `"office-01"`）或标签查询（如 `"tags:gpu"`）。
 
-## 前置配置：开启 chatCompletions 端点
-
-**所有共享模型的节点都必须配置此项**。ClawMatrix 的模型代理通过 OpenClaw Gateway 的 `/v1/chat/completions` HTTP 端点转发请求，该端点默认关闭。
-
-在 `openclaw.json` 的 `gateway` 字段下添加：
-
-```json
-{
-  "gateway": {
-    "http": {
-      "endpoints": {
-        "chatCompletions": { "enabled": true }
-      }
-    }
-  }
-}
-```
-
-如果不开启，模型代理请求会返回 404 错误。
-
 ## 前置配置：注册集群模型到 OpenClaw
 
 消费远程模型的节点需要在 `models.providers` 中注册，否则 `/models` 命令看不到集群模型。
@@ -249,7 +230,7 @@ openclaw clawmatrix status
 
 **模型代理不工作**：
 - 确认远程节点的 `models` 中声明了该模型
-- 确认该模型在远程节点上本地可用（OpenClaw 已配置对应 provider）
+- 确认该模型的 `provider` 与 OpenClaw `models.providers` 中的 key 一致（ClawMatrix 会自动读取 baseUrl 和 apiKey）
 - 确认本节点使用 `clawmatrix/<模型ID>` 格式引用模型
 - 如果用了 `proxyModels.nodeId`，确认该节点在线
 

package/README.md

@@ -61,7 +61,7 @@ openclaw plugins install clawmatrix
     { "id": "claude-sonnet", "provider": "anthropic" },
     { "id": "deepseek-coder", "provider": "ollama" }
   ],
-  "toolProxy": { "enabled": true, "allow": ["exec", "read", "write", "edit"] }
+  "toolProxy": { "enabled": true, "allow": ["*"] }
 }
 ```
 
@@ -77,19 +77,7 @@ openclaw plugins install clawmatrix
 }
 ```
 
-**重要**：共享模型的节点必须开启 chatCompletions 端点：
-
-```json
-{
-  "gateway": {
-    "http": {
-      "endpoints": {
-        "chatCompletions": { "enabled": true }
-      }
-    }
-  }
-}
-```
+**重要**：共享模型的节点只需在 `models` 中声明 `{ id, provider }`，ClawMatrix 会自动从 OpenClaw 的 `models.providers` 读取对应的 `baseUrl` 和 `apiKey`，直接调用模型 API（不经过 OpenClaw Gateway 的 agent 系统）。
 
 消费远程模型的节点需要在 `models.providers` 中注册（以 nodeId 为 key，baseUrl 指向 `http://127.0.0.1:19001`），详见 [BOOTSTRAP.md](BOOTSTRAP.md)。
 
@@ -129,14 +117,14 @@ openclaw clawmatrix status
 | `listenPort` | number | `19000` | 入站 WS 端口 |
 | `peers` | array | `[]` | 要连接的 peer：`{ nodeId, url }` |
 | `agents` | array | `[]` | 本节点 Agent：`{ id, description, tags }` |
-| `models` | array | `[]` | 共享给集群的模型：`{ id, provider }` |
+| `models` | array | `[]` | 共享给集群的模型：`{ id, provider }`（自动读取 OpenClaw provider 配置，可选 `baseUrl`/`apiKey` 覆盖）|
 | `proxyModels` | array | `[]` | 要消费的远程模型：`{ id, nodeId? }` |
 | `tags` | array | `[]` | 自由标签 |
 | `proxyPort` | number | `19001` | 本地模型代理端口 |
 | `handoffTimeout` | number | `600000` | Handoff 超时（ms） |
 | `toolProxy.enabled` | boolean | `false` | 允许远程工具执行 |
-| `toolProxy.allow` | array | `[]` | 允许的工具（`[]` = 全部） |
-| `toolProxy.deny` | array | `[]` | 禁止的工具（优先） |
+| `toolProxy.allow` | array | `[]` | 允许的工具名，`["*"]` 或 `[]` 表示全部。`exec`/`read`/`write`/`edit` 本地执行，其余走 Gateway |
+| `toolProxy.deny` | array | `[]` | 禁止的工具（优先于 allow） |
 
 ## 架构
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawmatrix",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Decentralized mesh cluster plugin for OpenClaw — inter-gateway communication, model proxy, task handoff, and tool proxy.",
   "type": "module",
   "license": "MIT",
@@ -29,10 +29,7 @@
   "scripts": {
     "test": "bun test",
     "prepublishOnly": "bun test",
-    "release": "bun scripts/release.ts",
-    "release:minor": "bun scripts/release.ts minor",
-    "release:major": "bun scripts/release.ts major",
-    "release:dry": "bun scripts/release.ts --dry-run"
+    "release": "bunx bumpp"
   },
   "dependencies": {
     "ws": "^8.19.0",

package/src/auth.ts

@@ -22,17 +22,21 @@ export async function computeHmac(
   return Buffer.from(sig).toString("hex");
 }
 
+/** Constant-time string comparison. */
+export function timingSafeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return diff === 0;
+}
+
 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;
+  return timingSafeEqual(expected, sig);
 }

package/src/cluster-service.ts

@@ -11,6 +11,7 @@ import { PeerManager } from "./peer-manager.ts";
 import { HandoffManager } from "./handoff.ts";
 import { ModelProxy } from "./model-proxy.ts";
 import { ToolProxy, type GatewayInfo } from "./tool-proxy.ts";
+import { WebHandler } from "./web.ts";
 import type {
   AnyClusterFrame,
   HandoffRequest,
@@ -51,7 +52,7 @@ export class ClusterRuntime {
     const gatewayInfo = resolveGatewayInfo(openclawConfig);
     this.peerManager = new PeerManager(config);
     this.handoffManager = new HandoffManager(config, this.peerManager);
-    this.modelProxy = new ModelProxy(config, this.peerManager, gatewayInfo);
+    this.modelProxy = new ModelProxy(config, this.peerManager, gatewayInfo, openclawConfig);
     this.toolProxy = new ToolProxy(config, this.peerManager, gatewayInfo);
   }
 
@@ -69,6 +70,13 @@ export class ClusterRuntime {
       this.logger.info(`[clawmatrix] Peer disconnected: ${nodeId}`);
     });
 
+    // 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);
+      this.peerManager.setHttpHandler((req, res) => webHandler.handle(req, res));
+      this.logger.info(`[clawmatrix] Web dashboard enabled on listen port`);
+    }
+
     // Start subsystems
     this.peerManager.start();
     this.modelProxy.start();

package/src/config.ts

@@ -44,6 +44,8 @@ const ModelInfoSchema = z.object({
   id: z.string(),
   provider: z.string(),
   description: z.string().optional(),
+  baseUrl: z.string().optional(),
+  apiKey: z.string().optional(),
   ...ModelParamsSchema,
 });
 
@@ -66,6 +68,11 @@ const ProxyModelSchema = z.object({
   ...ModelParamsSchema,
 });
 
+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({
   nodeId: z.string(),
   secret: z.string().min(16, "secret must be at least 16 characters"),
@@ -80,6 +87,7 @@ export const ClawMatrixConfigSchema = z.object({
   proxyPort: z.number().default(19001),
   toolProxy: ToolProxyConfigSchema.optional(),
   handoffTimeout: z.number().default(600_000),
+  web: WebConfigSchema,
 });
 
 export type ClawMatrixConfig = z.infer<typeof ClawMatrixConfigSchema>;

package/src/index.ts

@@ -191,6 +191,12 @@ const plugin = {
           "  - 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.",
+          "",
+          "IMPORTANT: Before calling any cluster tool or using a remote model, you MUST explicitly tell the user " +
+            "which remote node you are targeting and what you are about to do. For example:",
+          '  "I\'m going to run this command on remote node «coder» ..."',
+          '  "I\'m delegating this task to agent «reviewer» on node «server-b» ..."',
+          "This ensures the user always knows when operations leave the local node.",
         );
 
         return { prependContext: lines.join("\n") };

package/src/model-proxy.ts

@@ -2,6 +2,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 { OpenClawConfig } from "openclaw/plugin-sdk";
 import type {
   ModelRequest,
   ModelResponse,
@@ -26,11 +27,45 @@ export class ModelProxy {
   private pending = new Map<string, PendingModelReq>();
   private httpServer: Server | null = null;
   private gatewayInfo: GatewayInfo;
+  private openclawConfig: OpenClawConfig;
 
-  constructor(config: ClawMatrixConfig, peerManager: PeerManager, gatewayInfo: GatewayInfo) {
+  constructor(config: ClawMatrixConfig, peerManager: PeerManager, gatewayInfo: GatewayInfo, openclawConfig: OpenClawConfig) {
     this.config = config;
     this.peerManager = peerManager;
     this.gatewayInfo = gatewayInfo;
+    this.openclawConfig = openclawConfig;
+  }
+
+  /** Resolve API endpoint for a model: explicit config > OpenClaw provider > gateway fallback */
+  private resolveModelEndpoint(model: { id: string; provider: string; baseUrl?: string; apiKey?: string }): { url: string; apiKey?: string; direct: boolean } {
+    // 1. Explicit baseUrl in ClawMatrix model config
+    if (model.baseUrl) {
+      return {
+        url: `${model.baseUrl.replace(/\/$/, "")}/chat/completions`,
+        apiKey: model.apiKey,
+        direct: true,
+      };
+    }
+
+    // 2. Read from OpenClaw's models.providers[provider]
+    const providers = (this.openclawConfig as Record<string, unknown>).models as
+      { providers?: Record<string, { baseUrl?: string; apiKey?: string }> } | undefined;
+    const providerConfig = providers?.providers?.[model.provider];
+    if (providerConfig?.baseUrl) {
+      return {
+        url: `${providerConfig.baseUrl.replace(/\/$/, "")}/chat/completions`,
+        apiKey: typeof providerConfig.apiKey === "string" ? providerConfig.apiKey : undefined,
+        direct: true,
+      };
+    }
+
+    // 3. Fallback: OpenClaw gateway (goes through agent system — not recommended)
+    const { port } = this.gatewayInfo;
+    return {
+      url: `http://127.0.0.1:${port}/v1/chat/completions`,
+      apiKey: undefined,
+      direct: false,
+    };
   }
 
   /** Start the local HTTP proxy server for OpenAI-compatible requests. */
@@ -450,7 +485,7 @@ export class ModelProxy {
     }
   }
 
-  /** Handle model_req locally: forward to OpenClaw's configured model provider. */
+  /** Handle model_req locally: call the model API directly or fall back to OpenClaw gateway. */
   async handleModelRequest(frame: ModelRequest): Promise<void> {
     const { id, from, payload } = frame;
     debug("model_req", `handling model="${payload.model}" from=${from} stream=${payload.stream}`);
@@ -469,15 +504,23 @@ export class ModelProxy {
     }
 
     try {
-      const { port, authHeader } = this.gatewayInfo;
+      const endpoint = this.resolveModelEndpoint(model);
       const headers: Record<string, string> = { "Content-Type": "application/json" };
-      if (authHeader) headers["Authorization"] = authHeader;
 
-      const response = await fetch(`http://127.0.0.1:${port}/v1/chat/completions`, {
+      if (endpoint.direct) {
+        if (endpoint.apiKey) headers["Authorization"] = `Bearer ${endpoint.apiKey}`;
+        debug("model_req", `direct API call to ${endpoint.url}`);
+      } else {
+        const { authHeader } = this.gatewayInfo;
+        if (authHeader) headers["Authorization"] = authHeader;
+        debug("model_req", `gateway fallback to ${endpoint.url} (not recommended)`);
+      }
+
+      const response = await fetch(endpoint.url, {
         method: "POST",
         headers,
         body: JSON.stringify({
-          model: `${model.provider}/${model.id}`,
+          model: endpoint.direct ? model.id : `${model.provider}/${model.id}`,
           messages: payload.messages,
           temperature: payload.temperature,
           max_tokens: payload.maxTokens,

package/src/peer-manager.ts

@@ -1,5 +1,5 @@
 import { EventEmitter } from "node:events";
-import { createServer, type IncomingMessage, type Server } from "node:http";
+import { createServer, type IncomingMessage, type ServerResponse, type Server } from "node:http";
 import { WebSocketServer, WebSocket as WsWebSocket } from "ws";
 import type { ClawMatrixConfig, PeerConfig } from "./config.ts";
 import { Connection } from "./connection.ts";
@@ -95,12 +95,20 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
     this.router.destroy();
   }
 
+  /** Set an HTTP request handler for non-WebSocket requests (e.g. web dashboard). */
+  private httpRequestHandler: ((req: IncomingMessage, res: ServerResponse) => boolean) | null = null;
+
+  setHttpHandler(handler: (req: IncomingMessage, res: ServerResponse) => boolean) {
+    this.httpRequestHandler = handler;
+  }
+
   // ── Inbound WS server (node:http + ws) ──────────────────────────
   private startListening() {
     const port = this.config.listenPort;
     const hostname = this.config.listenHost;
 
-    this.httpServer = createServer((_req, res) => {
+    this.httpServer = createServer((req, res) => {
+      if (this.httpRequestHandler && this.httpRequestHandler(req, res)) return;
       res.writeHead(426, { "Content-Type": "text/plain" });
       res.end("WebSocket upgrade required");
     });
@@ -270,7 +278,9 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
     // 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;
+    // Skip dedup for streaming frame types — they share one id across many chunks
+    const isStreamFrame = frame.type === "model_stream" || frame.type === "handoff_stream";
+    if (frame.id && !isStreamFrame && this.router.isDuplicate(frame.id)) return;
 
     if (frame.type === "peer_sync") {
       this.handlePeerSync(frame as PeerSync, from);