clawmatrix 0.1.6 → 0.1.11

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.6",
+  "version": "0.1.11",
   "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": {
@@ -28,7 +28,11 @@
   },
   "scripts": {
     "test": "bun test",
-    "prepublishOnly": "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"
   },
   "dependencies": {
     "ws": "^8.19.0",

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,78 +48,111 @@ 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(", ")}]`,
-      );
-      console.log("");
-
-      if (peers.length === 0) {
-        console.log("No peers connected.");
+      if (data.error) {
+        console.log(String(data.error));
         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),
-        );
+      // Style helpers
+      const bold = (s: string) => `\x1b[1m${s}\x1b[22m`;
+      const dim = (s: string) => `\x1b[2m${s}\x1b[22m`;
+      const green = (s: string) => `\x1b[32m${s}\x1b[39m`;
+      const red = (s: string) => `\x1b[31m${s}\x1b[39m`;
+      const cyan = (s: string) => `\x1b[36m${s}\x1b[39m`;
+      const yellow = (s: string) => `\x1b[33m${s}\x1b[39m`;
+      const bar = dim("│");
+      const lbl = (text: string) => dim(text.padEnd(13));
+
+      const agents = data.agents as Array<{ id: string }>;
+      const models = data.models as Array<{ id: string }>;
+      const tags = data.tags as string[];
+
+      // Local node
+      console.log();
+      console.log(`  ${cyan("◆")}  ${bold("ClawMatrix Cluster")}`);
+      console.log(`  ${bar}`);
+      console.log(`  ${bar}  ${lbl("Node")}${bold(String(data.nodeId))}`);
+      if (tags.length > 0) {
+        console.log(`  ${bar}  ${lbl("Tags")}${tags.join(dim(", "))}`);
       }
-      console.log("");
+      console.log(`  ${bar}  ${lbl("Listen")}${data.listen !== false ? `:${data.listen}` : dim("disabled")}`);
+      console.log(`  ${bar}  ${lbl("Model Proxy")}:${data.proxyPort}`);
+      console.log(`  ${bar}  ${lbl("Agents")}${agents.map((a) => a.id).join(dim(", ")) || dim("–")}`);
+      console.log(`  ${bar}  ${lbl("Models")}${models.map((m) => m.id).join(dim(", ")) || dim("–")}`);
+
+      const peers = data.peers as Array<{
+        nodeId: string;
+        agents: Array<{ id: string }>;
+        models: Array<{ id: string }>;
+        tags: string[];
+        connected: boolean;
+        latencyMs: number;
+      }>;
+
+      if (!peers || peers.length === 0) {
+        console.log(`  ${bar}`);
+        console.log(`  ${dim("◇")}  ${dim("No peers discovered")}`);
+        console.log();
+        return;
+      }
+
+      const connected = peers.filter((p) => p.connected).length;
+      const countStr = `${connected}/${peers.length} connected`;
+      const countColor = connected === peers.length ? green : connected > 0 ? yellow : red;
+
+      console.log(`  ${bar}`);
+      console.log(`  ${cyan("◆")}  ${bold("Peers")}  ${countColor(countStr)}`);
+      console.log(`  ${bar}`);
+
+      for (let i = 0; i < peers.length; i++) {
+        const peer = peers[i];
+        const dot = peer.connected ? green("●") : red("○");
+        const latency = peer.connected && peer.latencyMs > 0 ? dim(` ${peer.latencyMs}ms`) : "";
+        const status = peer.connected ? "" : red(" disconnected");
+        console.log(`  ${bar}  ${dot} ${bold(peer.nodeId)}${status}${latency}`);
+
+        if (peer.tags.length > 0) {
+          console.log(`  ${bar}    ${lbl("Tags")}${peer.tags.join(dim(", "))}`);
+        }
+        const peerAgents = peer.agents.map((a) => a.id).join(dim(", "));
+        if (peerAgents) {
+          console.log(`  ${bar}    ${lbl("Agents")}${peerAgents}`);
+        }
+        const peerModels = peer.models.map((m) => m.id).join(dim(", "));
+        if (peerModels) {
+          console.log(`  ${bar}    ${lbl("Models")}${peerModels}`);
+        }
+
+        if (i < peers.length - 1) {
+          console.log(`  ${bar}`);
+        }
+      }
+
+      console.log(`  ${bar}`);
+      console.log(`  ${dim("◇")}`);
+      console.log();
     });
 
   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("  ");
-}