clawmatrix 0.1.17 → 0.1.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/BOOTSTRAP.md +123 -121
  2. package/README.md +76 -71
  3. package/openclaw.plugin.json +1 -67
  4. package/package.json +5 -3
  5. package/src/cluster-service.ts +58 -0
  6. package/src/config.ts +14 -2
  7. package/src/index.ts +10 -14
  8. package/src/knowledge-sync.ts +426 -0
  9. package/src/types.ts +10 -1
package/BOOTSTRAP.md CHANGED
@@ -1,89 +1,91 @@
1
- # ClawMatrix — OpenClaw 集群插件安装指南
1
+ [中文](BOOTSTRAP_zh.md) | English
2
2
 
3
- > 本文档供 OpenClaw Agent 参考，用于帮助用户安装和配置 ClawMatrix 插件。
3
+ # ClawMatrix -- OpenClaw Cluster Plugin Installation Guide
4
4
 
5
- ## 这个插件是什么
5
+ > This document is intended as a reference for the OpenClaw Agent to help users install and configure the ClawMatrix plugin.
6
6
 
7
- ClawMatrix 让多个 OpenClaw Gateway 组成去中心化 mesh 网络。安装后，节点之间可以：
7
+ ## What Is This Plugin
8
8
 
9
- - **共享模型**：家庭节点借用内网/云端节点的 LLM（如 Claude、DeepSeek）
10
- - **委托任务**：将复杂任务 handoff 给远程 Agent（如有代码仓库访问权限的内网 Agent）
11
- - **远程工具调用**：在远程节点执行命令、读写文件，无需委托整个任务
12
- - **自动发现和故障转移**：gossip 协议自动发现节点，宕机时自动路由到备份
9
+ ClawMatrix connects multiple OpenClaw Gateways into a decentralized mesh network. Once installed, nodes can:
13
10
 
14
- ## 安装步骤
11
+ - **Share models**: Home nodes can borrow LLMs (e.g., Claude, DeepSeek) from intranet/cloud nodes
12
+ - **Delegate tasks**: Handoff complex tasks to remote Agents (e.g., an intranet Agent with code repository access)
13
+ - **Remote tool invocation**: Execute commands, read/write files on remote nodes without delegating the entire task
14
+ - **Auto-discovery and failover**: Gossip protocol auto-discovers nodes; requests are automatically routed to backups when a node goes down
15
15
 
16
- ### 第 1 步：安装插件
16
+ ## Installation Steps
17
+
18
+ ### Step 1: Install the Plugin
17
19
 
18
20
  ```bash
19
21
  openclaw plugins install clawmatrix
20
22
  ```
21
23
 
22
- ### 第 2 步：配置
24
+ ### Step 2: Configure
23
25
 
24
- 编辑 `openclaw.json`，在 `plugins.entries.clawmatrix` 中添加配置。**所有要组网的节点必须使用相同的 `secret`**。
26
+ Edit `openclaw.json` and add the configuration under `plugins.entries.clawmatrix`. **All nodes in the mesh must use the same `secret`**.
25
27
 
26
- 用户需要告知你：
27
- 1. **这个节点的角色**：公网服务器？内网办公机？家庭电脑？
28
- 2. **是否需要接受入站连接**（公网节点通常需要，内网/家庭节点不需要）
29
- 3. **要连接的 peer**（通常是公网节点的 WebSocket 地址）
30
- 4. **本节点提供什么**：有哪些 Agent？有哪些可共享的模型？
31
- 5. **是否允许远程工具执行**（toolProxy）
28
+ The user needs to tell you:
29
+ 1. **The role of this node**: Public cloud server? Intranet office machine? Home computer?
30
+ 2. **Whether it needs to accept inbound connections** (public nodes usually do; intranet/home nodes do not)
31
+ 3. **Peers to connect to** (typically the WebSocket address of a public node)
32
+ 4. **What this node provides**: Which Agents? Which models to share?
33
+ 5. **Whether to allow remote tool execution** (toolProxy)
32
34
 
33
- ### 第 3 步：重启 Gateway
35
+ ### Step 3: Restart the Gateway
34
36
 
35
37
  ```bash
36
38
  openclaw gateway restart
37
39
  ```
38
40
 
39
- ### 第 4 步：验证
41
+ ### Step 4: Verify
40
42
 
41
43
  ```bash
42
44
  openclaw clawmatrix status
43
45
  ```
44
46
 
45
- ## 配置模板
47
+ ## Configuration Templates
46
48
 
47
- 根据用户的节点角色，选择对应模板并替换占位值。
49
+ Choose the template matching the user's node role and replace the placeholder values.
48
50
 
49
- ### 公网节点（中继 + 可选 Agent）
51
+ ### Public Node (Relay + Optional Agent)
50
52
 
51
- 适用于：有公网 IP 或域名的云服务器。作为 mesh 的中继枢纽，内网和家庭节点都连它。
53
+ For: Cloud servers with a public IP or domain name. Acts as the relay hub for the mesh; intranet and home nodes connect to it.
52
54
 
53
55
  ```json
54
56
  {
55
- "nodeId": "<唯一节点名，如 cloud-01>",
56
- "secret": "<所有节点共用的密钥，至少 16 个字符>",
57
+ "nodeId": "<unique node name, e.g. cloud-01>",
58
+ "secret": "<shared secret for all nodes, at least 16 characters>",
57
59
  "listen": true,
58
60
  "listenPort": 19000,
59
61
  "peers": [],
60
62
  "agents": [
61
- { "id": "<agent名>", "description": "<agent描述>", "tags": ["<标签>"] }
63
+ { "id": "<agent name>", "description": "<agent description>", "tags": ["<tag>"] }
62
64
  ],
63
65
  "models": [],
64
66
  "tags": ["cloud"]
65
67
  }
66
68
  ```
67
69
 
68
- 注意事项：
69
- - `listenPort` 需要在防火墙/安全组中放行
70
- - 生产环境建议配置 TLS，让 peer 使用 `wss://` 连接
71
- - 如果不跑 Agent 可以把 `agents` 设为 `[]`
70
+ Notes:
71
+ - `listenPort` must be opened in your firewall / security group
72
+ - For production, configure TLS so peers connect via `wss://`
73
+ - If no Agent is running on this node, set `agents` to `[]`
72
74
 
73
- ### 内网/办公节点（有模型或代码仓库）
75
+ ### Intranet / Office Node (With Models or Code Repositories)
74
76
 
75
- 适用于：有 GPU、有 API Key、有内网资源的机器。不需要公网 IP，主动连接公网节点。
77
+ For: Machines with GPUs, API keys, or intranet resources. No public IP needed; connects outbound to the public node.
76
78
 
77
79
  ```json
78
80
  {
79
- "nodeId": "<唯一节点名，如 office-01>",
80
- "secret": "<同上>",
81
+ "nodeId": "<unique node name, e.g. office-01>",
82
+ "secret": "<same as above>",
81
83
  "listen": false,
82
84
  "peers": [
83
- { "nodeId": "<公网节点名>", "url": "wss://<公网节点地址>:19000" }
85
+ { "nodeId": "<public node name>", "url": "wss://<public node address>:19000" }
84
86
  ],
85
87
  "agents": [
86
- { "id": "coder", "description": "有代码仓库访问权限，可以读写代码和执行命令", "tags": ["coding"] }
88
+ { "id": "coder", "description": "Has code repository access; can read/write code and execute commands", "tags": ["coding"] }
87
89
  ],
88
90
  "models": [
89
91
  { "id": "claude-sonnet", "provider": "anthropic" },
@@ -98,27 +100,27 @@ openclaw clawmatrix status
98
100
  }
99
101
  ```
100
102
 
101
- 注意事项：
102
- - `models` 里的 `provider` 必须与 OpenClaw `models.providers` 中的 key 一致，ClawMatrix 会自动读取对应的 `baseUrl` 和 `apiKey`
103
- - 如果需要覆盖（比如用不同的 API 地址），可以显式设置 `baseUrl` 和 `apiKey`
104
- - ClawMatrix 直接调模型 API，不经过 OpenClaw Gateway 的 agent 系统
105
- - `toolProxy.enabled: true` 才会接受远程工具调用
106
- - `toolProxy.deny` 优先于 `allow`，建议禁用高风险工具
103
+ Notes:
104
+ - The `provider` in `models` must match a key in OpenClaw's `models.providers`; ClawMatrix automatically reads the corresponding `baseUrl` and `apiKey`
105
+ - To override (e.g., use a different API address), explicitly set `baseUrl` and `apiKey`
106
+ - ClawMatrix calls the model API directly, bypassing the OpenClaw Gateway's agent system
107
+ - `toolProxy.enabled: true` is required to accept remote tool invocations
108
+ - `toolProxy.deny` takes priority over `allow`; consider denying high-risk tools
107
109
 
108
- ### 家庭/轻量节点（借用集群资源）
110
+ ### Home / Lightweight Node (Borrowing Cluster Resources)
109
111
 
110
- 适用于：个人电脑、轻量设备。没有模型和特殊资源，借用集群。
112
+ For: Personal computers and lightweight devices. No local models or special resources; borrows from the cluster.
111
113
 
112
114
  ```json
113
115
  {
114
- "nodeId": "<唯一节点名，如 home-01>",
115
- "secret": "<同上>",
116
+ "nodeId": "<unique node name, e.g. home-01>",
117
+ "secret": "<same as above>",
116
118
  "listen": false,
117
119
  "peers": [
118
- { "nodeId": "<公网节点名>", "url": "wss://<公网节点地址>:19000" }
120
+ { "nodeId": "<public node name>", "url": "wss://<public node address>:19000" }
119
121
  ],
120
122
  "agents": [
121
- { "id": "assistant", "description": "个人助手", "tags": ["general"] }
123
+ { "id": "assistant", "description": "Personal assistant", "tags": ["general"] }
122
124
  ],
123
125
  "models": [],
124
126
  "proxyModels": [
@@ -129,48 +131,48 @@ openclaw clawmatrix status
129
131
  }
130
132
  ```
131
133
 
132
- 如果要用集群中的模型，还需要修改 agent 的模型配置：
134
+ To use models from the cluster, you also need to update the agent's model configuration:
133
135
 
134
136
  ```json
135
137
  {
136
138
  "agents": {
137
139
  "defaults": {
138
- "model": "clawmatrix/<模型ID>"
140
+ "model": "clawmatrix/<model ID>"
139
141
  }
140
142
  }
141
143
  }
142
144
  ```
143
145
 
144
- 注意事项：
145
- - `proxyModels` 中的 `nodeId` 可选，指定后精确路由到该节点，不指定则自动查找
146
- - `proxyModels` 中的模型 ID 必须与远程节点 `models` 中声明的 ID 一致
147
-
148
- ## 完整配置字段参考
149
-
150
- | 字段 | 类型 | 默认值 | 说明 |
151
- |------|------|--------|------|
152
- | `nodeId` | string | *必填* | 节点唯一标识 |
153
- | `secret` | string | *必填* | 集群共享密钥，最少 16 字符 |
154
- | `listen` | boolean | `false` | 是否接受入站 WebSocket 连接 |
155
- | `listenHost` | string | `"0.0.0.0"` | WebSocket 监听地址 |
156
- | `listenPort` | number | `19000` | 入站 WebSocket 端口 |
157
- | `peers` | array | `[]` | 要连接的 peer：`{ nodeId, url }` |
158
- | `agents` | array | `[]` | 本节点提供的 Agent：`{ id, description, tags }` |
159
- | `models` | array | `[]` | 本节点共享给集群的模型：`{ id, provider }`（自动读取 OpenClaw provider 的 baseUrl/apiKey，可选覆盖）|
160
- | `proxyModels` | array | `[]` | 从集群消费的远程模型：`{ id, nodeId?, description? }` |
161
- | `tags` | array | `[]` | 自由标签，用于能力路由 |
162
- | `proxyPort` | number | `19001` | 本地模型代理 HTTP 端口 |
163
- | `handoffTimeout` | number | `600000` | Handoff 超时（毫秒，默认 10 分钟） |
164
- | `toolProxy.enabled` | boolean | `false` | 允许远程工具执行 |
165
- | `toolProxy.allow` | array | `[]` | 允许的工具名，`["*"]` 或 `[]` 表示全部。`exec`/`read`/`write`/`edit` 本地执行，其余走 Gateway |
166
- | `toolProxy.deny` | array | `[]` | 禁止的工具名（优先于 allow） |
167
- | `toolProxy.maxOutputBytes` | number | `1048576` | 单次响应最大字节数 |
168
-
169
- ## 启用集群工具
170
-
171
- ClawMatrix 的 Agent 工具注册为可选工具（optional），需要在 OpenClaw 配置中显式启用。
172
-
173
- 在 `openclaw.json` 中添加：
146
+ Notes:
147
+ - `nodeId` in `proxyModels` is optional; when specified, requests are routed precisely to that node; when omitted, the cluster finds a suitable node automatically
148
+ - The model ID in `proxyModels` must match the ID declared in the remote node's `models`
149
+
150
+ ## Full Configuration Field Reference
151
+
152
+ | Field | Type | Default | Description |
153
+ |-------|------|---------|-------------|
154
+ | `nodeId` | string | *required* | Unique node identifier |
155
+ | `secret` | string | *required* | Cluster shared secret, minimum 16 characters |
156
+ | `listen` | boolean | `false` | Whether to accept inbound WebSocket connections |
157
+ | `listenHost` | string | `"0.0.0.0"` | WebSocket listen address |
158
+ | `listenPort` | number | `19000` | Inbound WebSocket port |
159
+ | `peers` | array | `[]` | Peers to connect to: `{ nodeId, url }` |
160
+ | `agents` | array | `[]` | Agents provided by this node: `{ id, description, tags }` |
161
+ | `models` | array | `[]` | Models shared with the cluster: `{ id, provider }` (automatically reads baseUrl/apiKey from the OpenClaw provider; can be overridden) |
162
+ | `proxyModels` | array | `[]` | Remote models consumed from the cluster: `{ id, nodeId?, description? }` |
163
+ | `tags` | array | `[]` | Free-form tags for capability-based routing |
164
+ | `proxyPort` | number | `19001` | Local model proxy HTTP port |
165
+ | `handoffTimeout` | number | `600000` | Handoff timeout in milliseconds (default 10 minutes) |
166
+ | `toolProxy.enabled` | boolean | `false` | Allow remote tool execution |
167
+ | `toolProxy.allow` | array | `[]` | Allowed tool names; `["*"]` or `[]` means all. `exec`/`read`/`write`/`edit` execute locally; others go through the Gateway |
168
+ | `toolProxy.deny` | array | `[]` | Denied tool names (takes priority over allow) |
169
+ | `toolProxy.maxOutputBytes` | number | `1048576` | Maximum bytes per single response |
170
+
171
+ ## Enabling Cluster Tools
172
+
173
+ ClawMatrix's Agent tools are registered as optional tools. They must be explicitly enabled in the OpenClaw configuration.
174
+
175
+ Add the following to `openclaw.json`:
174
176
 
175
177
  ```json
176
178
  {
@@ -186,12 +188,12 @@ ClawMatrix 的 Agent 工具注册为可选工具（optional），需要在 OpenC
186
188
  }
187
189
  ```
188
190
 
189
- 配置说明：
190
- - `profile: "full"` — 启用完整工具集（包括可选工具）
191
- - `sessions.visibility: "all"` — 允许跨会话访问工具（集群工具需要此设置才能在所有会话中可用）
192
- - `allow: ["clawmatrix"]` — 显式允许 ClawMatrix 插件注册的所有集群工具
191
+ Configuration details:
192
+ - `profile: "full"` -- Enables the full toolset (including optional tools)
193
+ - `sessions.visibility: "all"` -- Allows cross-session tool access (cluster tools require this setting to be available in all sessions)
194
+ - `allow: ["clawmatrix"]` -- Explicitly allows all cluster tools registered by the ClawMatrix plugin
193
195
 
194
- 也可以按 Agent 粒度启用：
196
+ You can also enable tools on a per-Agent basis:
195
197
 
196
198
  ```json
197
199
  {
@@ -212,34 +214,34 @@ ClawMatrix 的 Agent 工具注册为可选工具（optional），需要在 OpenC
212
214
  }
213
215
  ```
214
216
 
215
- > 如果不配置，Agent 的系统提示中会提到集群工具，但实际无法调用。
217
+ > If not configured, the Agent's system prompt will mention cluster tools, but they will not actually be callable.
216
218
 
217
- 启用后，本节点的 Agent 获得 7 个集群工具：
219
+ Once enabled, the node's Agent gains 7 cluster tools:
218
220
 
219
- | 工具 | 用途 | 关键参数 |
220
- |------|------|----------|
221
- | `cluster_peers` | 查看集群拓扑和连接状态 | 无 |
222
- | `cluster_handoff` | 委托任务给远程 Agent | `target`, `task`, `context?` |
223
- | `cluster_send` | 向远程 Agent 发单向消息 | `target`, `message` |
224
- | `cluster_exec` | 在远程节点执行命令 | `node`, `command`, `workdir?`, `timeout?` |
225
- | `cluster_read` | 读取远程节点文件 | `node`, `path` |
226
- | `cluster_write` | 写入远程节点文件 | `node`, `path`, `content` |
227
- | `cluster_tool` | 调用远程节点任意 OpenClaw 工具 | `node`, `tool`, `args` |
221
+ | Tool | Purpose | Key Parameters |
222
+ |------|---------|----------------|
223
+ | `cluster_peers` | View cluster topology and connection status | None |
224
+ | `cluster_handoff` | Delegate a task to a remote Agent | `target`, `task`, `context?` |
225
+ | `cluster_send` | Send a one-way message to a remote Agent | `target`, `message` |
226
+ | `cluster_exec` | Execute a command on a remote node | `node`, `command`, `workdir?`, `timeout?` |
227
+ | `cluster_read` | Read a file on a remote node | `node`, `path` |
228
+ | `cluster_write` | Write a file on a remote node | `node`, `path`, `content` |
229
+ | `cluster_tool` | Invoke any OpenClaw tool on a remote node | `node`, `tool`, `args` |
228
230
 
229
- `target` 参数支持 Agent ID（如 `"coder"`）或标签查询（如 `"tags:coding"`）。
230
- `node` 参数支持 nodeId（如 `"office-01"`）或标签查询（如 `"tags:gpu"`）。
231
+ The `target` parameter accepts an Agent ID (e.g., `"coder"`) or a tag query (e.g., `"tags:coding"`).
232
+ The `node` parameter accepts a nodeId (e.g., `"office-01"`) or a tag query (e.g., `"tags:gpu"`).
231
233
 
232
- ## 前置配置：注册集群模型到 OpenClaw
234
+ ## Prerequisite: Register Cluster Models in OpenClaw
233
235
 
234
- 消费远程模型的节点需要在 `models.providers` 中注册，否则 `/models` 命令看不到集群模型。
236
+ Nodes consuming remote models must register them in `models.providers`; otherwise, the `/models` command will not show cluster models.
235
237
 
236
- 以 nodeId 作为 provider key（推荐），baseUrl 指向本地模型代理端口：
238
+ Use the nodeId as the provider key (recommended), with baseUrl pointing to the local model proxy port:
237
239
 
238
240
  ```json
239
241
  {
240
242
  "models": {
241
243
  "providers": {
242
- "<远程nodeId>": {
244
+ "<remote nodeId>": {
243
245
  "baseUrl": "http://127.0.0.1:19001",
244
246
  "apiKey": "cluster-internal",
245
247
  "auth": "api-key",
@@ -261,28 +263,28 @@ ClawMatrix 的 Agent 工具注册为可选工具（optional），需要在 OpenC
261
263
  }
262
264
  ```
263
265
 
264
- 配置后使用 `/model <nodeId>/<模型ID>` 切换。
266
+ After configuration, use `/model <nodeId>/<model ID>` to switch models.
265
267
 
266
- ## 常见问题排查
268
+ ## Troubleshooting
267
269
 
268
- **节点连不上**：
269
- - 检查 `secret` 是否所有节点一致
270
- - 检查公网节点的 `listenPort` 是否在防火墙中放行
271
- - 检查 `peers` 中的 URL 格式：`wss://host:port` 或 `ws://host:port`
270
+ **Cannot connect to a node**:
271
+ - Check that `secret` is identical across all nodes
272
+ - Check that the public node's `listenPort` is open in the firewall
273
+ - Check the URL format in `peers`: `wss://host:port` or `ws://host:port`
272
274
 
273
- **远程工具调用失败**：
274
- - 确认目标节点的 `toolProxy.enabled` 为 `true`
275
- - 确认目标工具不在 `toolProxy.deny` 列表中
276
- - 如果 `toolProxy.allow` 非空，确认目标工具在列表中
275
+ **Remote tool invocation fails**:
276
+ - Confirm `toolProxy.enabled` is `true` on the target node
277
+ - Confirm the target tool is not in the `toolProxy.deny` list
278
+ - If `toolProxy.allow` is non-empty, confirm the target tool is in the list
277
279
 
278
- **模型代理不工作**：
279
- - 确认远程节点的 `models` 中声明了该模型
280
- - 确认该模型的 `provider` 与 OpenClaw `models.providers` 中的 key 一致（ClawMatrix 会自动读取 baseUrl 和 apiKey）
281
- - 确认本节点使用 `clawmatrix/<模型ID>` 格式引用模型
282
- - 如果用了 `proxyModels.nodeId`，确认该节点在线
280
+ **Model proxy not working**:
281
+ - Confirm the model is declared in the remote node's `models`
282
+ - Confirm the model's `provider` matches a key in OpenClaw's `models.providers` (ClawMatrix automatically reads baseUrl and apiKey)
283
+ - Confirm this node references the model using the `clawmatrix/<model ID>` format
284
+ - If `proxyModels.nodeId` is set, confirm that node is online
283
285
 
284
- **查看状态**：
286
+ **Check status**:
285
287
  ```bash
286
- openclaw clawmatrix status # 表格形式
287
- openclaw clawmatrix peers # JSON 格式
288
+ openclaw clawmatrix status # table format
289
+ openclaw clawmatrix peers # JSON format
288
290
  ```
package/README.md CHANGED
@@ -1,32 +1,36 @@
1
+ [中文](README_zh.md) | English
2
+
1
3
  # ClawMatrix
2
4
 
3
- 去中心化 mesh 集群插件，让多个 [OpenClaw](https://github.com/nicepkg/openclaw) Gateway 组成 peer-to-peer 网络，跨节点共享 Agent、模型和工具。
5
+ A decentralized mesh cluster plugin that connects multiple [OpenClaw](https://github.com/nicepkg/openclaw) Gateways into a peer-to-peer network, sharing Agents, models, and tools across nodes.
6
+
7
+ > **Warning**: This project is under active development and testing. APIs and protocols may change without notice. Not recommended for production use.
4
8
 
5
- ## 功能
9
+ ## Features
6
10
 
7
- **模型代理** — 家庭节点没有 API Key？通过集群使用内网节点的 LLM，就像本地模型一样。
11
+ **Model Proxy** — No API key on your home node? Use LLMs from intranet nodes through the cluster, as if they were local models.
8
12
 
9
- **任务 Handoff** — 需要内网资源？将任务委托给有仓库访问权限的远程 Agent，流式返回结果。
13
+ **Task Handoff** — Need intranet resources? Delegate tasks to remote Agents with repository access and stream results back.
10
14
 
11
- **工具代理** — 想在远程节点跑个命令或读个文件？直接调用，不用委托整个任务。
15
+ **Tool Proxy** — Want to run a command or read a file on a remote node? Call it directly without delegating the entire task.
12
16
 
13
- **自动发现 & 故障转移** — Gossip 协议自动发现节点，宕机时请求自动路由到备份。
17
+ **Auto-Discovery & Failover** — Gossip protocol automatically discovers nodes; requests are rerouted to backups when a node goes down.
14
18
 
15
- ## 快速开始
19
+ ## Quick Start
16
20
 
17
- > **推荐**：将 [BOOTSTRAP.md](BOOTSTRAP.md) 链接发给 OpenClaw Agent，它会引导你完成安装和配置。
21
+ > **Recommended**: Send the [BOOTSTRAP.md](BOOTSTRAP.md) link to your OpenClaw Agent and it will guide you through installation and configuration.
18
22
 
19
- ### 安装
23
+ ### Installation
20
24
 
21
25
  ```bash
22
26
  openclaw plugins install clawmatrix
23
27
  ```
24
28
 
25
- ### 配置
29
+ ### Configuration
26
30
 
27
- 编辑 `openclaw.json`，添加插件配置。所有节点共享同一 `secret`。
31
+ Edit `openclaw.json` to add the plugin configuration. All nodes share the same `secret`.
28
32
 
29
- **公网节点**（中继枢纽）：
33
+ **Public Node** (relay hub):
30
34
 
31
35
  ```json
32
36
  {
@@ -40,7 +44,7 @@ openclaw plugins install clawmatrix
40
44
  "listen": true,
41
45
  "listenPort": 19000,
42
46
  "agents": [
43
- { "id": "reviewer", "description": "代码审查", "tags": ["review"] }
47
+ { "id": "reviewer", "description": "Code review", "tags": ["review"] }
44
48
  ]
45
49
  }
46
50
  }
@@ -49,14 +53,14 @@ openclaw plugins install clawmatrix
49
53
  }
50
54
  ```
51
55
 
52
- **内网节点**（有模型和仓库）：
56
+ **Intranet Node** (with models and repositories):
53
57
 
54
58
  ```json
55
59
  {
56
60
  "nodeId": "office-01",
57
61
  "secret": "your-shared-secret-min-16-chars",
58
62
  "peers": [{ "nodeId": "cloud-01", "url": "wss://cloud-01.example.com:19000" }],
59
- "agents": [{ "id": "coder", "description": "代码开发", "tags": ["coding"] }],
63
+ "agents": [{ "id": "coder", "description": "Code development", "tags": ["coding"] }],
60
64
  "models": [
61
65
  { "id": "claude-sonnet", "provider": "anthropic" },
62
66
  { "id": "deepseek-coder", "provider": "ollama" }
@@ -65,99 +69,100 @@ openclaw plugins install clawmatrix
65
69
  }
66
70
  ```
67
71
 
68
- **家庭节点**（借用集群资源）：
72
+ **Home Node** (borrowing cluster resources):
69
73
 
70
74
  ```json
71
75
  {
72
76
  "nodeId": "home-01",
73
77
  "secret": "your-shared-secret-min-16-chars",
74
78
  "peers": [{ "nodeId": "cloud-01", "url": "wss://cloud-01.example.com:19000" }],
75
- "agents": [{ "id": "assistant", "description": "个人助手", "tags": ["general"] }],
79
+ "agents": [{ "id": "assistant", "description": "Personal assistant", "tags": ["general"] }],
76
80
  "proxyModels": [{ "id": "claude-sonnet", "nodeId": "office-01" }]
77
81
  }
78
82
  ```
79
83
 
80
- **重要**：共享模型的节点只需在 `models` 中声明 `{ id, provider }`，ClawMatrix 会自动从 OpenClaw 的 `models.providers` 读取对应的 `baseUrl` 和 `apiKey`，直接调用模型 API（不经过 OpenClaw Gateway 的 agent 系统）。
84
+ **Important**: Nodes sharing models only need to declare `{ id, provider }` in `models`. ClawMatrix automatically reads the corresponding `baseUrl` and `apiKey` from OpenClaw's `models.providers` and calls the model API directly (bypassing the OpenClaw Gateway's agent system).
81
85
 
82
- 消费远程模型的节点需要在 `models.providers` 中注册（以 nodeId 为 key，baseUrl 指向 `http://127.0.0.1:19001`），详见 [BOOTSTRAP.md](BOOTSTRAP.md)。
86
+ Nodes consuming remote models need to register them in `models.providers` (using the nodeId as the key, with baseUrl pointing to `http://127.0.0.1:19001`). See [BOOTSTRAP.md](BOOTSTRAP.md) for details.
83
87
 
84
- 使用集群模型：`/model <nodeId>/<模型ID>`。
88
+ To use a cluster model: `/model <nodeId>/<modelId>`.
85
89
 
86
- ### 启动
90
+ ### Start
87
91
 
88
92
  ```bash
89
93
  openclaw gateway restart
90
94
  openclaw clawmatrix status
91
95
  ```
92
96
 
93
- ## Agent 工具
94
-
95
- 安装后 Agent 自动获得以下工具：
96
-
97
- | 工具 | 说明 |
98
- |------|------|
99
- | `cluster_handoff` | 委托任务给远程 Agent，等待结果 |
100
- | `cluster_send` | 向远程 Agent 发送单向消息 |
101
- | `cluster_peers` | 查看集群拓扑和连接状态 |
102
- | `cluster_exec` | 在远程节点执行命令 |
103
- | `cluster_read` | 读取远程节点文件 |
104
- | `cluster_write` | 写入远程节点文件 |
105
- | `cluster_tool` | 调用远程节点任意 OpenClaw 工具 |
106
-
107
- 目标参数支持 nodeId（`"office-01"`）或标签查询（`"tags:coding"`）。
108
-
109
- ## 配置参考
110
-
111
- | 字段 | 类型 | 默认值 | 说明 |
112
- |------|------|--------|------|
113
- | `nodeId` | string | 必填 | 节点唯一标识 |
114
- | `secret` | string | 必填 | 集群共享密钥（>= 16 字符） |
115
- | `listen` | boolean | `false` | 接受入站 WS 连接 |
116
- | `listenHost` | string | `"0.0.0.0"` | 监听地址 |
117
- | `listenPort` | number | `19000` | 入站 WS 端口 |
118
- | `peers` | array | `[]` | 要连接的 peer：`{ nodeId, url }` |
119
- | `agents` | array | `[]` | 本节点 Agent：`{ id, description, tags }` |
120
- | `models` | array | `[]` | 共享给集群的模型：`{ id, provider }`（自动读取 OpenClaw provider 配置，可选 `baseUrl`/`apiKey` 覆盖）|
121
- | `proxyModels` | array | `[]` | 要消费的远程模型：`{ id, nodeId? }` |
122
- | `tags` | array | `[]` | 自由标签 |
123
- | `proxyPort` | number | `19001` | 本地模型代理端口 |
124
- | `handoffTimeout` | number | `600000` | Handoff 超时（ms） |
125
- | `toolProxy.enabled` | boolean | `false` | 允许远程工具执行 |
126
- | `toolProxy.allow` | array | `[]` | 允许的工具名，`["*"]` 或 `[]` 表示全部。`exec`/`read`/`write`/`edit` 本地执行，其余走 Gateway |
127
- | `toolProxy.deny` | array | `[]` | 禁止的工具（优先于 allow） |
128
-
129
- ## 架构
97
+ ## Agent Tools
98
+
99
+ After installation, the Agent automatically gains access to the following tools:
100
+
101
+ | Tool | Description |
102
+ |------|-------------|
103
+ | `cluster_handoff` | Delegate a task to a remote Agent and wait for the result |
104
+ | `cluster_send` | Send a one-way message to a remote Agent |
105
+ | `cluster_peers` | View cluster topology and connection status |
106
+ | `cluster_exec` | Execute a command on a remote node |
107
+ | `cluster_read` | Read a file on a remote node |
108
+ | `cluster_write` | Write a file on a remote node |
109
+ | `cluster_tool` | Invoke any OpenClaw tool on a remote node |
110
+
111
+ The target parameter supports nodeId (`"office-01"`) or tag queries (`"tags:coding"`).
112
+
113
+ ## Configuration Reference
114
+
115
+ | Field | Type | Default | Description |
116
+ |-------|------|---------|-------------|
117
+ | `nodeId` | string | required | Unique node identifier |
118
+ | `secret` | string | required | Cluster shared secret (>= 16 characters) |
119
+ | `listen` | boolean | `false` | Accept inbound WS connections |
120
+ | `listenHost` | string | `"0.0.0.0"` | Listen address |
121
+ | `listenPort` | number | `19000` | Inbound WS port |
122
+ | `peers` | array | `[]` | Peers to connect to: `{ nodeId, url }` |
123
+ | `agents` | array | `[]` | Local Agents: `{ id, description, tags }` |
124
+ | `models` | array | `[]` | Models shared with the cluster: `{ id, provider }` (auto-reads OpenClaw provider config; optional `baseUrl`/`apiKey` override) |
125
+ | `proxyModels` | array | `[]` | Remote models to consume: `{ id, nodeId? }` |
126
+ | `tags` | array | `[]` | Free-form tags |
127
+ | `proxyPort` | number | `19001` | Local model proxy port |
128
+ | `handoffTimeout` | number | `600000` | Handoff timeout (ms) |
129
+ | `toolProxy.enabled` | boolean | `false` | Allow remote tool execution |
130
+ | `toolProxy.allow` | array | `[]` | Allowed tool names; `["*"]` or `[]` means all. `exec`/`read`/`write`/`edit` run locally, others go through Gateway |
131
+ | `toolProxy.deny` | array | `[]` | Denied tools (takes precedence over allow) |
132
+
133
+ ## Architecture
130
134
 
131
135
  ```
132
136
  ┌──────────────────────────┐
133
- │ 公网 Gateway │
137
+ │ Public Gateway │
134
138
  │ listen: true │
135
139
  │ listenPort: 19000 │
136
140
  └──┬──────────────────┬────┘
137
141
  inbound │ │ inbound
138
142
  WS conn │ │ WS conn
139
143
  ┌──┴────┐ ┌────┴──────┐
140
- │ 家庭 │ │ 内网办公室 │
144
+ │ Home │ │ Intranet │
145
+ │ │ │ Office │
141
146
  └───────┘ └──────────┘
142
147
  ```
143
148
 
144
- - 去中心化 mesh，无 leader，无共识协议
145
- - HMAC-SHA256 challenge-response 认证
146
- - 消息中继 + TTL 防环 + ID 去重
147
- - 心跳检测 + 指数退避重连 + 自动故障转移
148
- - 生产环境建议 `wss://`（TLS）
149
+ - Decentralized mesh — no leader, no consensus protocol
150
+ - HMAC-SHA256 challenge-response authentication
151
+ - Message relay + TTL loop prevention + ID deduplication
152
+ - Heartbeat detection + exponential backoff reconnection + automatic failover
153
+ - `wss://` (TLS) recommended for production
149
154
 
150
- ## 开发
155
+ ## Development
151
156
 
152
157
  ```bash
153
- bun install # 安装依赖
154
- bun test # 运行测试
158
+ bun install # Install dependencies
159
+ bun test # Run tests
155
160
  ```
156
161
 
157
- ## 文档
162
+ ## Documentation
158
163
 
159
- - [技术规格](docs/SPEC.md) — 完整协议、消息类型、安全设计
160
- - [安装指南](BOOTSTRAP.md) — AI Agent 辅助安装配置
164
+ - [Technical Spec](docs/SPEC.md) — Full protocol, message types, and security design
165
+ - [Installation Guide](BOOTSTRAP.md) — AI Agent-assisted installation and configuration
161
166
 
162
167
  ## License
163
168