clawmatrix 0.1.5 → 0.1.8

package/BOOTSTRAP.md

@@ -0,0 +1,260 @@
+# ClawMatrix — OpenClaw 集群插件安装指南
+
+> 本文档供 OpenClaw Agent 参考，用于帮助用户安装和配置 ClawMatrix 插件。
+
+## 这个插件是什么
+
+ClawMatrix 让多个 OpenClaw Gateway 组成去中心化 mesh 网络。安装后，节点之间可以：
+
+- **共享模型**：家庭节点借用内网/云端节点的 LLM（如 Claude、DeepSeek）
+- **委托任务**：将复杂任务 handoff 给远程 Agent（如有代码仓库访问权限的内网 Agent）
+- **远程工具调用**：在远程节点执行命令、读写文件，无需委托整个任务
+- **自动发现和故障转移**：gossip 协议自动发现节点，宕机时自动路由到备份
+
+## 安装步骤
+
+### 第 1 步：安装插件
+
+```bash
+openclaw plugins install clawmatrix
+```
+
+### 第 2 步：配置
+
+编辑 `openclaw.json`，在 `plugins.entries.clawmatrix` 中添加配置。**所有要组网的节点必须使用相同的 `secret`**。
+
+用户需要告知你：
+1. **这个节点的角色**：公网服务器？内网办公机？家庭电脑？
+2. **是否需要接受入站连接**（公网节点通常需要，内网/家庭节点不需要）
+3. **要连接的 peer**（通常是公网节点的 WebSocket 地址）
+4. **本节点提供什么**：有哪些 Agent？有哪些可共享的模型？
+5. **是否允许远程工具执行**（toolProxy）
+
+### 第 3 步：重启 Gateway
+
+```bash
+openclaw gateway restart
+```
+
+### 第 4 步：验证
+
+```bash
+openclaw clawmatrix status
+```
+
+## 配置模板
+
+根据用户的节点角色，选择对应模板并替换占位值。
+
+### 公网节点（中继 + 可选 Agent）
+
+适用于：有公网 IP 或域名的云服务器。作为 mesh 的中继枢纽，内网和家庭节点都连它。
+
+```json
+{
+  "nodeId": "<唯一节点名，如 cloud-01>",
+  "secret": "<所有节点共用的密钥，至少 16 个字符>",
+  "listen": true,
+  "listenPort": 19000,
+  "peers": [],
+  "agents": [
+    { "id": "<agent名>", "description": "<agent描述>", "tags": ["<标签>"] }
+  ],
+  "models": [],
+  "tags": ["cloud"]
+}
+```
+
+注意事项：
+- `listenPort` 需要在防火墙/安全组中放行
+- 生产环境建议配置 TLS，让 peer 使用 `wss://` 连接
+- 如果不跑 Agent 可以把 `agents` 设为 `[]`
+
+### 内网/办公节点（有模型或代码仓库）
+
+适用于：有 GPU、有 API Key、有内网资源的机器。不需要公网 IP，主动连接公网节点。
+
+```json
+{
+  "nodeId": "<唯一节点名，如 office-01>",
+  "secret": "<同上>",
+  "listen": false,
+  "peers": [
+    { "nodeId": "<公网节点名>", "url": "wss://<公网节点地址>:19000" }
+  ],
+  "agents": [
+    { "id": "coder", "description": "有代码仓库访问权限，可以读写代码和执行命令", "tags": ["coding"] }
+  ],
+  "models": [
+    { "id": "claude-sonnet", "provider": "anthropic" },
+    { "id": "deepseek-coder", "provider": "ollama" }
+  ],
+  "tags": ["office", "gpu"],
+  "toolProxy": {
+    "enabled": true,
+    "allow": ["exec", "read", "write", "edit", "web_search"],
+    "deny": ["browser", "sessions_spawn"]
+  }
+}
+```
+
+注意事项：
+- `models` 里填这台机器上 OpenClaw 已经配置好的模型（必须本地能用才行）
+- **必须开启 OpenClaw 的 chatCompletions HTTP 端点**，否则模型代理无法工作（见下方「前置配置」）
+- `toolProxy.enabled: true` 才会接受远程工具调用
+- `toolProxy.deny` 优先于 `allow`，建议禁用高风险工具
+
+### 家庭/轻量节点（借用集群资源）
+
+适用于：个人电脑、轻量设备。没有模型和特殊资源，借用集群。
+
+```json
+{
+  "nodeId": "<唯一节点名，如 home-01>",
+  "secret": "<同上>",
+  "listen": false,
+  "peers": [
+    { "nodeId": "<公网节点名>", "url": "wss://<公网节点地址>:19000" }
+  ],
+  "agents": [
+    { "id": "assistant", "description": "个人助手", "tags": ["general"] }
+  ],
+  "models": [],
+  "proxyModels": [
+    { "id": "claude-sonnet", "nodeId": "office-01" }
+  ],
+  "tags": ["home"]
+}
+```
+
+如果要用集群中的模型，还需要修改 agent 的模型配置：
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model": "clawmatrix/<模型ID>"
+    }
+  }
+}
+```
+
+注意事项：
+- `proxyModels` 中的 `nodeId` 可选，指定后精确路由到该节点，不指定则自动查找
+- `proxyModels` 中的模型 ID 必须与远程节点 `models` 中声明的 ID 一致
+
+## 完整配置字段参考
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `nodeId` | string | *必填* | 节点唯一标识 |
+| `secret` | string | *必填* | 集群共享密钥，最少 16 字符 |
+| `listen` | boolean | `false` | 是否接受入站 WebSocket 连接 |
+| `listenHost` | string | `"0.0.0.0"` | WebSocket 监听地址 |
+| `listenPort` | number | `19000` | 入站 WebSocket 端口 |
+| `peers` | array | `[]` | 要连接的 peer：`{ nodeId, url }` |
+| `agents` | array | `[]` | 本节点提供的 Agent：`{ id, description, tags }` |
+| `models` | array | `[]` | 本节点共享给集群的模型：`{ id, provider, description? }` |
+| `proxyModels` | array | `[]` | 从集群消费的远程模型：`{ id, nodeId?, description? }` |
+| `tags` | array | `[]` | 自由标签，用于能力路由 |
+| `proxyPort` | number | `19001` | 本地模型代理 HTTP 端口 |
+| `handoffTimeout` | number | `600000` | Handoff 超时（毫秒，默认 10 分钟） |
+| `toolProxy.enabled` | boolean | `false` | 允许远程工具执行 |
+| `toolProxy.allow` | array | `[]` | 允许的工具名（`[]` 或 `["*"]` = 全部允许） |
+| `toolProxy.deny` | array | `[]` | 禁止的工具名（优先于 allow） |
+| `toolProxy.maxOutputBytes` | number | `1048576` | 单次响应最大字节数 |
+
+## 安装后 Agent 获得的工具
+
+安装后，本节点的 Agent 自动获得 7 个集群工具：
+
+| 工具 | 用途 | 关键参数 |
+|------|------|----------|
+| `cluster_peers` | 查看集群拓扑和连接状态 | 无 |
+| `cluster_handoff` | 委托任务给远程 Agent | `target`, `task`, `context?` |
+| `cluster_send` | 向远程 Agent 发单向消息 | `target`, `message` |
+| `cluster_exec` | 在远程节点执行命令 | `node`, `command`, `workdir?`, `timeout?` |
+| `cluster_read` | 读取远程节点文件 | `node`, `path` |
+| `cluster_write` | 写入远程节点文件 | `node`, `path`, `content` |
+| `cluster_tool` | 调用远程节点任意 OpenClaw 工具 | `node`, `tool`, `args` |
+
+`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` 命令看不到集群模型。
+
+以 nodeId 作为 provider key（推荐），baseUrl 指向本地模型代理端口：
+
+```json
+{
+  "models": {
+    "providers": {
+      "<远程nodeId>": {
+        "baseUrl": "http://127.0.0.1:19001",
+        "apiKey": "cluster-internal",
+        "auth": "api-key",
+        "api": "openai-completions",
+        "models": [
+          {
+            "id": "<模型ID>",
+            "name": "<显示名>",
+            "reasoning": false,
+            "input": ["text"],
+            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
+            "contextWindow": 200000,
+            "maxTokens": 32000
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+配置后使用 `/model <nodeId>/<模型ID>` 切换。
+
+## 常见问题排查
+
+**节点连不上**：
+- 检查 `secret` 是否所有节点一致
+- 检查公网节点的 `listenPort` 是否在防火墙中放行
+- 检查 `peers` 中的 URL 格式：`wss://host:port` 或 `ws://host:port`
+
+**远程工具调用失败**：
+- 确认目标节点的 `toolProxy.enabled` 为 `true`
+- 确认目标工具不在 `toolProxy.deny` 列表中
+- 如果 `toolProxy.allow` 非空，确认目标工具在列表中
+
+**模型代理不工作**：
+- 确认远程节点的 `models` 中声明了该模型
+- 确认该模型在远程节点上本地可用（OpenClaw 已配置对应 provider）
+- 确认本节点使用 `clawmatrix/<模型ID>` 格式引用模型
+- 如果用了 `proxyModels.nodeId`，确认该节点在线
+
+**查看状态**：
+```bash
+openclaw clawmatrix status   # 表格形式
+openclaw clawmatrix peers    # JSON 格式
+```

package/README.md

@@ -1,15 +1,176 @@
-# clawmatrix
+# ClawMatrix
 
-To install dependencies:
+去中心化 mesh 集群插件，让多个 [OpenClaw](https://github.com/nicepkg/openclaw) Gateway 组成 peer-to-peer 网络，跨节点共享 Agent、模型和工具。
+
+## 功能
+
+**模型代理** — 家庭节点没有 API Key？通过集群使用内网节点的 LLM，就像本地模型一样。
+
+**任务 Handoff** — 需要内网资源？将任务委托给有仓库访问权限的远程 Agent，流式返回结果。
+
+**工具代理** — 想在远程节点跑个命令或读个文件？直接调用，不用委托整个任务。
+
+**自动发现 & 故障转移** — Gossip 协议自动发现节点，宕机时请求自动路由到备份。
+
+## 快速开始
+
+> **推荐**：将 [BOOTSTRAP.md](BOOTSTRAP.md) 链接发给 OpenClaw Agent，它会引导你完成安装和配置。
+
+### 安装
+
+```bash
+openclaw plugins install clawmatrix
+```
+
+### 配置
+
+编辑 `openclaw.json`，添加插件配置。所有节点共享同一 `secret`。
+
+**公网节点**（中继枢纽）：
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "clawmatrix": {
+        "enabled": true,
+        "config": {
+          "nodeId": "cloud-01",
+          "secret": "your-shared-secret-min-16-chars",
+          "listen": true,
+          "listenPort": 19000,
+          "agents": [
+            { "id": "reviewer", "description": "代码审查", "tags": ["review"] }
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+**内网节点**（有模型和仓库）：
+
+```json
+{
+  "nodeId": "office-01",
+  "secret": "your-shared-secret-min-16-chars",
+  "peers": [{ "nodeId": "cloud-01", "url": "wss://cloud-01.example.com:19000" }],
+  "agents": [{ "id": "coder", "description": "代码开发", "tags": ["coding"] }],
+  "models": [
+    { "id": "claude-sonnet", "provider": "anthropic" },
+    { "id": "deepseek-coder", "provider": "ollama" }
+  ],
+  "toolProxy": { "enabled": true, "allow": ["exec", "read", "write", "edit"] }
+}
+```
+
+**家庭节点**（借用集群资源）：
+
+```json
+{
+  "nodeId": "home-01",
+  "secret": "your-shared-secret-min-16-chars",
+  "peers": [{ "nodeId": "cloud-01", "url": "wss://cloud-01.example.com:19000" }],
+  "agents": [{ "id": "assistant", "description": "个人助手", "tags": ["general"] }],
+  "proxyModels": [{ "id": "claude-sonnet", "nodeId": "office-01" }]
+}
+```
+
+**重要**：共享模型的节点必须开启 chatCompletions 端点：
+
+```json
+{
+  "gateway": {
+    "http": {
+      "endpoints": {
+        "chatCompletions": { "enabled": true }
+      }
+    }
+  }
+}
+```
+
+消费远程模型的节点需要在 `models.providers` 中注册（以 nodeId 为 key，baseUrl 指向 `http://127.0.0.1:19001`），详见 [BOOTSTRAP.md](BOOTSTRAP.md)。
+
+使用集群模型：`/model <nodeId>/<模型ID>`。
+
+### 启动
 
 ```bash
-bun install
+openclaw gateway restart
+openclaw clawmatrix status
 ```
 
-To run:
+## Agent 工具
+
+安装后 Agent 自动获得以下工具：
+
+| 工具 | 说明 |
+|------|------|
+| `cluster_handoff` | 委托任务给远程 Agent，等待结果 |
+| `cluster_send` | 向远程 Agent 发送单向消息 |
+| `cluster_peers` | 查看集群拓扑和连接状态 |
+| `cluster_exec` | 在远程节点执行命令 |
+| `cluster_read` | 读取远程节点文件 |
+| `cluster_write` | 写入远程节点文件 |
+| `cluster_tool` | 调用远程节点任意 OpenClaw 工具 |
+
+目标参数支持 nodeId（`"office-01"`）或标签查询（`"tags:coding"`）。
+
+## 配置参考
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `nodeId` | string | 必填 | 节点唯一标识 |
+| `secret` | string | 必填 | 集群共享密钥（>= 16 字符） |
+| `listen` | boolean | `false` | 接受入站 WS 连接 |
+| `listenHost` | string | `"0.0.0.0"` | 监听地址 |
+| `listenPort` | number | `19000` | 入站 WS 端口 |
+| `peers` | array | `[]` | 要连接的 peer：`{ nodeId, url }` |
+| `agents` | array | `[]` | 本节点 Agent：`{ id, description, tags }` |
+| `models` | array | `[]` | 共享给集群的模型：`{ id, provider }` |
+| `proxyModels` | array | `[]` | 要消费的远程模型：`{ id, nodeId? }` |
+| `tags` | array | `[]` | 自由标签 |
+| `proxyPort` | number | `19001` | 本地模型代理端口 |
+| `handoffTimeout` | number | `600000` | Handoff 超时（ms） |
+| `toolProxy.enabled` | boolean | `false` | 允许远程工具执行 |
+| `toolProxy.allow` | array | `[]` | 允许的工具（`[]` = 全部） |
+| `toolProxy.deny` | array | `[]` | 禁止的工具（优先） |
+
+## 架构
+
+```
+          ┌──────────────────────────┐
+          │   公网 Gateway           │
+          │   listen: true           │
+          │   listenPort: 19000      │
+          └──┬──────────────────┬────┘
+    inbound  │                  │  inbound
+    WS conn  │                  │  WS conn
+          ┌──┴────┐        ┌────┴──────┐
+          │ 家庭   │        │ 内网办公室 │
+          └───────┘        └──────────┘
+```
+
+- 去中心化 mesh，无 leader，无共识协议
+- HMAC-SHA256 challenge-response 认证
+- 消息中继 + TTL 防环 + ID 去重
+- 心跳检测 + 指数退避重连 + 自动故障转移
+- 生产环境建议 `wss://`（TLS）
+
+## 开发
 
 ```bash
-bun run index.ts
+bun install    # 安装依赖
+bun test       # 运行测试
 ```
 
-This project was created using `bun init` in bun v1.3.6. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
+## 文档
+
+- [技术规格](docs/SPEC.md) — 完整协议、消息类型、安全设计
+- [安装指南](BOOTSTRAP.md) — AI Agent 辅助安装配置
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawmatrix",
-  "version": "0.1.5",
+  "version": "0.1.8",
   "description": "Decentralized mesh cluster plugin for OpenClaw — inter-gateway communication, model proxy, task handoff, and tool proxy.",
   "type": "module",
   "license": "MIT",
@@ -18,7 +18,7 @@
     "src/",
     "!src/**/*.test.ts",
     "openclaw.plugin.json",
-    "llms.txt",
+    "BOOTSTRAP.md",
     "README.md"
   ],
   "openclaw": {

package/src/cli.ts

@@ -1,5 +1,46 @@
 import type { Command } from "commander";
-import { getClusterRuntime } from "./cluster-service.ts";
+import { spawnProcess } from "./compat.ts";
+
+async function callGateway(method: string): Promise<unknown> {
+  const proc = spawnProcess(["openclaw", "gateway", "call", method, "--json"], {
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  const stdoutChunks: Uint8Array[] = [];
+  const stderrChunks: Uint8Array[] = [];
+
+  const readStream = async (stream: ReadableStream | null, target: Uint8Array[]) => {
+    if (!stream) return;
+    const reader = stream.getReader();
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      target.push(value);
+    }
+  };
+
+  await Promise.all([
+    readStream(proc.stdout, stdoutChunks),
+    readStream(proc.stderr, stderrChunks),
+  ]);
+
+  const code = await proc.exited;
+  const stdout = Buffer.concat(stdoutChunks).toString("utf-8").trim();
+  const stderr = Buffer.concat(stderrChunks).toString("utf-8").trim();
+
+  if (code !== 0) {
+    // Extract meaningful error from stderr
+    const errLine = stderr.split("\n").find((l) => l.includes("Error:") || l.includes("error"));
+    throw new Error(errLine || stderr || "Gateway call failed (exit code " + code + ")");
+  }
+
+  if (!stdout) {
+    throw new Error("Empty response from gateway");
+  }
+
+  return JSON.parse(stdout);
+}
 
 export const registerClusterCli = ({ program }: { program: Command }) => {
   const cmd = program.command("clawmatrix").description("ClawMatrix cluster management");
@@ -7,48 +48,71 @@ export const registerClusterCli = ({ program }: { program: Command }) => {
   cmd
     .command("status")
     .description("Show cluster topology and peer status")
-    .action(() => {
-      let runtime: ReturnType<typeof getClusterRuntime>;
+    .action(async () => {
+      let data: Record<string, unknown>;
       try {
-        runtime = getClusterRuntime();
+        data = (await callGateway("clawmatrix.status")) as Record<string, unknown>;
       } catch {
-        console.log("ClawMatrix service not running.");
+        console.log("Could not reach gateway. Is it 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(", ")}]`,
-      );
+      if (data.error) {
+        console.log(String(data.error));
+        return;
+      }
+
+      const agents = data.agents as Array<{ id: string }>;
+      const models = data.models as Array<{ id: string }>;
+      const tags = data.tags as string[];
+
+      console.log("");
+      console.log("ClawMatrix Cluster");
       console.log("");
+      console.log(`  Node:        ${data.nodeId}`);
+      if (tags.length > 0) {
+        console.log(`  Tags:        ${tags.join(", ")}`);
+      }
+      console.log(`  Listen:      ${data.listen !== false ? `port ${data.listen}` : "disabled"}`);
+      console.log(`  Model proxy: port ${data.proxyPort}`);
+      console.log(`  Agents:      ${agents.map((a) => a.id).join(", ") || "-"}`);
+      console.log(`  Models:      ${models.map((m) => m.id).join(", ") || "-"}`);
+
+      const peers = data.peers as Array<{
+        nodeId: string;
+        agents: Array<{ id: string }>;
+        models: Array<{ id: string }>;
+        tags: string[];
+        connected: boolean;
+        latencyMs: number;
+      }>;
 
-      if (peers.length === 0) {
-        console.log("No peers connected.");
+      const connected = peers.filter((p) => p.connected).length;
+      console.log("");
+      if (!peers || peers.length === 0) {
+        console.log("  No peers discovered.");
+        console.log("");
         return;
       }
 
-      // Peer table
-      const header = padRow("NODE", "AGENTS", "MODELS", "STATUS", "LATENCY");
-      console.log(header);
-      console.log("-".repeat(header.length));
+      console.log(`Peers (${connected}/${peers.length} connected)`);
+      console.log("");
 
       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),
-        );
+        const status = peer.connected ? "connected" : "unreachable";
+        const latency = peer.latencyMs > 0 ? `, ${peer.latencyMs}ms` : "";
+        console.log(`  ${peer.nodeId} (${status}${latency})`);
+        if (peer.tags.length > 0) {
+          console.log(`    Tags:   ${peer.tags.join(", ")}`);
+        }
+        const peerAgents = peer.agents.map((a) => a.id).join(", ");
+        if (peerAgents) {
+          console.log(`    Agents: ${peerAgents}`);
+        }
+        const peerModels = peer.models.map((m) => m.id).join(", ");
+        if (peerModels) {
+          console.log(`    Models: ${peerModels}`);
+        }
       }
       console.log("");
     });
@@ -56,29 +120,14 @@ export const registerClusterCli = ({ program }: { program: Command }) => {
   cmd
     .command("peers")
     .description("List known peers (JSON)")
-    .action(() => {
-      let runtime: ReturnType<typeof getClusterRuntime>;
+    .action(async () => {
+      let peers: unknown;
       try {
-        runtime = getClusterRuntime();
+        peers = await callGateway("clawmatrix.peers");
       } 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

@@ -14,6 +14,7 @@ import type {
   AnyClusterFrame,
   HandoffRequest,
   HandoffResponse,
+  HandoffStreamChunk,
   ModelRequest,
   ModelResponse,
   ModelStreamChunk,
@@ -93,6 +94,9 @@ export class ClusterRuntime {
           this.logger.error(`[clawmatrix] Handoff request error: ${err}`);
         });
         break;
+      case "handoff_stream":
+        this.handoffManager.handleStream(frame as HandoffStreamChunk);
+        break;
       case "handoff_res":
         this.handoffManager.handleResponse(frame as HandoffResponse);
         break;

package/src/config.ts

@@ -63,6 +63,7 @@ export const ClawMatrixConfigSchema = z.object({
   tags: z.array(z.string()).default([]),
   proxyPort: z.number().default(19001),
   toolProxy: ToolProxyConfigSchema.optional(),
+  handoffTimeout: z.number().default(600_000),
 });
 
 export type ClawMatrixConfig = z.infer<typeof ClawMatrixConfigSchema>;

package/src/handoff.ts

@@ -4,10 +4,10 @@ import { spawnProcess } from "./compat.ts";
 import type {
   HandoffRequest,
   HandoffResponse,
-  AnyClusterFrame,
+  HandoffStreamChunk,
 } from "./types.ts";
 
-const HANDOFF_TIMEOUT = 120_000; // 2 minutes
+const DEFAULT_HANDOFF_TIMEOUT = 600_000; // 10 minutes (resets on each stream chunk)
 const MAX_RETRIES = 2;
 
 interface PendingHandoff {
@@ -18,6 +18,7 @@ interface PendingHandoff {
   retriesLeft: number;
   task: string;
   context?: string;
+  accumulated: string;
 }
 
 export class HandoffManager {
@@ -54,24 +55,9 @@ export class HandoffManager {
     const id = crypto.randomUUID();
 
     return new Promise<HandoffResponse["payload"]>((resolve, reject) => {
-      const timer = setTimeout(() => {
-        this.pending.delete(id);
-        this.peerManager.router.markFailed(id);
-
-        // Retry with failover
-        if (retriesLeft > 0) {
-          const nextRoute = this.peerManager.router.resolveAgent(target);
-          if (nextRoute && nextRoute.nodeId !== targetNodeId) {
-            this.sendHandoff(nextRoute.nodeId, target, task, context, retriesLeft - 1)
-              .then(resolve)
-              .catch(reject);
-            return;
-          }
-        }
-        reject(new Error(`Handoff to "${target}" timed out`));
-      }, HANDOFF_TIMEOUT);
+      const timer = this.createTimeout(id, targetNodeId, target, task, context, retriesLeft, resolve, reject);
 
-      this.pending.set(id, { resolve, reject, timer, target, retriesLeft, task, context });
+      this.pending.set(id, { resolve, reject, timer, target, retriesLeft, task, context, accumulated: "" });
 
       const frame: HandoffRequest = {
         type: "handoff_req",
@@ -102,6 +88,57 @@ export class HandoffManager {
     });
   }
 
+  private createTimeout(
+    id: string,
+    targetNodeId: string,
+    target: string,
+    task: string,
+    context: string | undefined,
+    retriesLeft: number,
+    resolve: (result: HandoffResponse["payload"]) => void,
+    reject: (error: Error) => void,
+  ): ReturnType<typeof setTimeout> {
+    return setTimeout(() => {
+      this.pending.delete(id);
+      this.peerManager.router.markFailed(id);
+
+      // Retry with failover
+      if (retriesLeft > 0) {
+        const nextRoute = this.peerManager.router.resolveAgent(target);
+        if (nextRoute && nextRoute.nodeId !== targetNodeId) {
+          this.sendHandoff(nextRoute.nodeId, target, task, context, retriesLeft - 1)
+            .then(resolve)
+            .catch(reject);
+          return;
+        }
+      }
+      reject(new Error(`Handoff to "${target}" timed out`));
+    }, this.config.handoffTimeout ?? DEFAULT_HANDOFF_TIMEOUT);
+  }
+
+  /** Handle incoming stream chunk — reset timeout & accumulate. */
+  handleStream(frame: HandoffStreamChunk) {
+    if (this.peerManager.router.isFailed(frame.id)) return;
+
+    const pending = this.pending.get(frame.id);
+    if (!pending) return;
+
+    pending.accumulated += frame.payload.delta;
+
+    // Reset timeout — the remote agent is still working
+    clearTimeout(pending.timer);
+    pending.timer = this.createTimeout(
+      frame.id,
+      frame.from,
+      pending.target,
+      pending.task,
+      pending.context,
+      pending.retriesLeft,
+      pending.resolve,
+      pending.reject,
+    );
+  }
+
   /** Handle incoming handoff response. */
   handleResponse(frame: HandoffResponse) {
     if (this.peerManager.router.isFailed(frame.id)) return;
@@ -111,6 +148,12 @@ export class HandoffManager {
 
     clearTimeout(pending.timer);
     this.pending.delete(frame.id);
+
+    // If the response has no result but we accumulated stream data, use that
+    if (frame.payload.success && !frame.payload.result && pending.accumulated) {
+      frame.payload.result = pending.accumulated;
+    }
+
     pending.resolve(frame.payload);
   }
 
@@ -153,7 +196,8 @@ export class HandoffManager {
         { stdout: "pipe", stderr: "pipe" },
       );
 
-      const stdout = proc.stdout ? await new Response(proc.stdout).text() : "";
+      // Stream stdout chunks back to the caller
+      const fullOutput = await this.streamStdout(proc.stdout, id, from);
       const exitCode = await proc.exited;
 
       if (exitCode !== 0) {
@@ -171,7 +215,7 @@ export class HandoffManager {
           success: true,
           nodeId: this.config.nodeId,
           agent: agent.id,
-          result: stdout.trim(),
+          result: fullOutput.trim(),
         },
       } satisfies HandoffResponse);
     } catch (err) {
@@ -191,9 +235,55 @@ export class HandoffManager {
     }
   }
 
+  /** Read stdout incrementally, sending handoff_stream chunks to the caller. */
+  private async streamStdout(
+    stdout: ReadableStream | null,
+    handoffId: string,
+    to: string,
+  ): Promise<string> {
+    if (!stdout) return "";
+
+    const reader = stdout.getReader();
+    const decoder = new TextDecoder();
+    let full = "";
+
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        const chunk = decoder.decode(value, { stream: true });
+        full += chunk;
+
+        this.peerManager.sendTo(to, {
+          type: "handoff_stream",
+          id: handoffId,
+          from: this.config.nodeId,
+          to,
+          timestamp: Date.now(),
+          payload: { delta: chunk, done: false },
+        } satisfies HandoffStreamChunk);
+      }
+    } finally {
+      reader.releaseLock();
+    }
+
+    // Send final done marker
+    this.peerManager.sendTo(to, {
+      type: "handoff_stream",
+      id: handoffId,
+      from: this.config.nodeId,
+      to,
+      timestamp: Date.now(),
+      payload: { delta: "", done: true },
+    } satisfies HandoffStreamChunk);
+
+    return full;
+  }
+
   /** Clean up on shutdown. */
   destroy() {
-    for (const [id, pending] of this.pending) {
+    for (const [, pending] of this.pending) {
       clearTimeout(pending.timer);
       pending.reject(new Error("Shutting down"));
     }

package/src/index.ts

@@ -1,4 +1,4 @@
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import type { OpenClawPluginApi, GatewayRequestHandlerOptions } from "openclaw/plugin-sdk";
 import { ClawMatrixConfigSchema, parseConfig } from "./config.ts";
 import { createClusterService, getClusterRuntime } from "./cluster-service.ts";
 import { createClusterHandoffTool } from "./tools/cluster-handoff.ts";
@@ -41,18 +41,36 @@ const plugin = {
     // Background service: manages mesh connections, WS listener, heartbeat
     api.registerService(createClusterService(config, api.config));
 
-    // Model provider: register clawmatrix as a provider pointing to local HTTP proxy
-    api.registerProvider({
-      id: "clawmatrix",
-      label: "ClawMatrix Cluster",
-      docsPath: "/plugins/clawmatrix",
-      auth: [],
-      models: {
-        baseUrl: `http://127.0.0.1:${config.proxyPort}`,
-        api: "openai-completions",
-        models: getAllClusterModels(config),
-      },
-    });
+    // Model providers: register per-node providers so models are accessed as nodeId/modelId
+    const baseUrl = `http://127.0.0.1:${config.proxyPort}/v1`;
+    const modelsByNode = groupModelsByNode(config);
+
+    // Patch openclaw config so auth resolution can find a dummy API key
+    // (resolveApiKeyForProvider checks cfg.models.providers, not plugin registry)
+    const ocModels = ((api.config as Record<string, unknown>).models ??= {}) as Record<string, unknown>;
+    const ocProviders = (ocModels.providers ??= {}) as Record<string, unknown>;
+
+    for (const [nodeId, models] of Object.entries(modelsByNode)) {
+      if (!ocProviders[nodeId]) {
+        ocProviders[nodeId] = {
+          baseUrl,
+          apiKey: "sk-clawmatrix-proxy",
+          models,
+        };
+      }
+
+      api.registerProvider({
+        id: nodeId,
+        label: `ClawMatrix: ${nodeId}`,
+        docsPath: "/plugins/clawmatrix",
+        auth: [],
+        models: {
+          baseUrl,
+          apiKey: "sk-clawmatrix-proxy",
+          models,
+        },
+      });
+    }
 
     // Agent tools
     api.registerTool(createClusterHandoffTool(), { optional: true });
@@ -63,6 +81,57 @@ const plugin = {
     api.registerTool(createClusterWriteTool(), { optional: true });
     api.registerTool(createClusterToolTool(), { optional: true });
 
+    // Gateway methods (queried by CLI via `openclaw gateway call`)
+    api.registerGatewayMethod(
+      "clawmatrix.status",
+      ({ respond }: GatewayRequestHandlerOptions) => {
+        try {
+          const runtime = getClusterRuntime();
+          const peers = runtime.peerManager.router.getAllPeers();
+          respond(true, {
+            nodeId: config.nodeId,
+            listen: config.listen ? config.listenPort : false,
+            proxyPort: config.proxyPort,
+            agents: config.agents.map((a) => ({ id: a.id, description: a.description })),
+            models: config.models.map((m) => ({ id: m.id })),
+            tags: config.tags,
+            peers: peers.map((p) => ({
+              nodeId: p.nodeId,
+              agents: p.agents,
+              models: p.models,
+              tags: p.tags,
+              connected: !!p.connection?.isOpen,
+              reachableVia: p.reachableVia,
+              latencyMs: p.latencyMs,
+            })),
+          });
+        } catch {
+          respond(false, { error: "ClawMatrix service not running" });
+        }
+      },
+    );
+
+    api.registerGatewayMethod(
+      "clawmatrix.peers",
+      ({ respond }: GatewayRequestHandlerOptions) => {
+        try {
+          const runtime = getClusterRuntime();
+          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,
+          }));
+          respond(true, peers);
+        } catch {
+          respond(true, []);
+        }
+      },
+    );
+
     // CLI subcommand
     api.registerCli(registerClusterCli, { commands: ["clawmatrix"] });
 
@@ -117,17 +186,8 @@ const plugin = {
   },
 };
 
-function getAllClusterModels(config: ReturnType<typeof parseConfig>) {
-  // 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) => ({
+function formatModel(m: { id: string; description?: string; api?: string; reasoning?: boolean; input?: string[]; cost?: { input: number; output: number; cacheRead: number; cacheWrite: number }; contextWindow?: number; maxTokens?: number }) {
+  return {
     id: m.id,
     name: m.description ?? m.id,
     api: m.api ?? ("openai-completions" as const),
@@ -136,7 +196,25 @@ function getAllClusterModels(config: ReturnType<typeof parseConfig>) {
     cost: m.cost ?? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
     contextWindow: m.contextWindow ?? 128_000,
     maxTokens: m.maxTokens ?? 4096,
-  }));
+  };
+}
+
+function groupModelsByNode(config: ReturnType<typeof parseConfig>): Record<string, ReturnType<typeof formatModel>[]> {
+  const result: Record<string, ReturnType<typeof formatModel>[]> = {};
+
+  // Local models served by this node
+  for (const m of config.models) {
+    const nodeId = config.nodeId;
+    (result[nodeId] ??= []).push(formatModel(m));
+  }
+
+  // Remote models consumed from peers (proxyModels have nodeId)
+  for (const m of config.proxyModels) {
+    const nodeId = m.nodeId;
+    (result[nodeId] ??= []).push(formatModel(m));
+  }
+
+  return result;
 }
 
 export default plugin;

package/src/model-proxy.ts

@@ -129,6 +129,17 @@ export class ModelProxy {
       };
     }
 
+    // Inject model identity so the LLM knows what it is
+    const messages = body.messages;
+    if (proxyModel?.description) {
+      const first = messages[0] as { role?: string; content?: string } | undefined;
+      if (first?.role === "system" && typeof first.content === "string") {
+        first.content = `[Model: ${proxyModel.description}]\n${first.content}`;
+      } else {
+        messages.unshift({ role: "system", content: `[Model: ${proxyModel.description}]` });
+      }
+    }
+
     const stream = body.stream ?? false;
     const requestId = crypto.randomUUID();
 
@@ -140,7 +151,7 @@ export class ModelProxy {
       timestamp: Date.now(),
       payload: {
         model: modelId,
-        messages: body.messages,
+        messages,
         temperature: body.temperature,
         maxTokens: body.max_tokens,
         stream,
@@ -427,7 +438,8 @@ export class ModelProxy {
 
             try {
               const parsed = JSON.parse(data);
-              const delta = parsed.choices?.[0]?.delta?.content ?? "";
+              const d = parsed.choices?.[0]?.delta;
+              const delta = d?.content || d?.reasoning_content || "";
               if (delta) {
                 this.peerManager.sendTo(from, {
                   type: "model_stream",
@@ -445,10 +457,11 @@ export class ModelProxy {
         }
       } else {
         const result = (await response.json()) as {
-          choices?: { message?: { content?: string } }[];
+          choices?: { message?: { content?: string; reasoning_content?: string } }[];
           usage?: { prompt_tokens: number; completion_tokens: number };
         };
-        const content = result.choices?.[0]?.message?.content ?? "";
+        const msg = result.choices?.[0]?.message;
+        const content = msg?.content || msg?.reasoning_content || "";
         const usage = result.usage;
 
         this.peerManager.sendTo(from, {

package/src/router.ts

@@ -120,6 +120,12 @@ export class Router {
       }
     }
 
+    // Fallback: if no agent ID or tag matched, try matching by nodeId
+    if (candidates.length === 0 && !isTagQuery) {
+      const byNode = this.routes.get(target);
+      if (byNode) candidates.push(byNode);
+    }
+
     if (candidates.length === 0) return undefined;
 
     // Sort: direct connections first, then by latency

package/src/types.ts

@@ -113,6 +113,15 @@ export interface HandoffRequest extends ClusterFrame {
   };
 }
 
+export interface HandoffStreamChunk extends ClusterFrame {
+  type: "handoff_stream";
+  id: string;
+  payload: {
+    delta: string;
+    done: boolean;
+  };
+}
+
 export interface HandoffResponse extends ClusterFrame {
   type: "handoff_res";
   id: string;
@@ -197,6 +206,7 @@ export type AnyClusterFrame =
   | ModelResponse
   | ModelStreamChunk
   | HandoffRequest
+  | HandoffStreamChunk
   | HandoffResponse
   | SendMessage
   | ToolProxyRequest

package/llms.txt

@@ -1,187 +0,0 @@
-# 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** — 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.
-
-## 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", "edit", "web_search"],
-    "deny": ["write", "browser", "sessions_spawn"]
-  }
-}
-```
-
-### 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 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 (tool proxy tools correspond to OpenClaw's built-in tools):
-
-### 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 (invokes OpenClaw `exec` tool).
-- `node`: Target nodeId or `"tags:<tag>"`
-- `command`: Shell command
-- `workdir`: Optional working directory
-- `timeout`: Optional timeout in seconds (default 1800)
-
-### cluster_read
-Read a file from a remote node (invokes OpenClaw `read` tool).
-- `node`: Target nodeId or `"tags:<tag>"`
-- `path`: File path
-
-### cluster_write
-Write content to a file on a remote node (invokes OpenClaw `write` tool).
-- `node`: Target nodeId or `"tags:<tag>"`
-- `path`: File path
-- `content`: File content
-
-### 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>"`
-- `tool`: OpenClaw tool name
-- `args`: Tool arguments (tool-specific)
-
-## 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