clawmatrix 0.1.16 → 0.1.18

package/BOOTSTRAP.md

@@ -1,89 +1,91 @@
-# ClawMatrix — OpenClaw 集群插件安装指南
+[中文](BOOTSTRAP_zh.md) | English
 
-> 本文档供 OpenClaw Agent 参考，用于帮助用户安装和配置 ClawMatrix 插件。
+# ClawMatrix -- OpenClaw Cluster Plugin Installation Guide
 
-## 这个插件是什么
+> This document is intended as a reference for the OpenClaw Agent to help users install and configure the ClawMatrix plugin.
 
-ClawMatrix 让多个 OpenClaw Gateway 组成去中心化 mesh 网络。安装后，节点之间可以：
+## What Is This Plugin
 
-- **共享模型**：家庭节点借用内网/云端节点的 LLM（如 Claude、DeepSeek）
-- **委托任务**：将复杂任务 handoff 给远程 Agent（如有代码仓库访问权限的内网 Agent）
-- **远程工具调用**：在远程节点执行命令、读写文件，无需委托整个任务
-- **自动发现和故障转移**：gossip 协议自动发现节点，宕机时自动路由到备份
+ClawMatrix connects multiple OpenClaw Gateways into a decentralized mesh network. Once installed, nodes can:
 
-## 安装步骤
+- **Share models**: Home nodes can borrow LLMs (e.g., Claude, DeepSeek) from intranet/cloud nodes
+- **Delegate tasks**: Handoff complex tasks to remote Agents (e.g., an intranet Agent with code repository access)
+- **Remote tool invocation**: Execute commands, read/write files on remote nodes without delegating the entire task
+- **Auto-discovery and failover**: Gossip protocol auto-discovers nodes; requests are automatically routed to backups when a node goes down
 
-### 第 1 步：安装插件
+## Installation Steps
+
+### Step 1: Install the Plugin
 
 ```bash
 openclaw plugins install clawmatrix
 ```
 
-### 第 2 步：配置
+### Step 2: Configure
 
-编辑 `openclaw.json`，在 `plugins.entries.clawmatrix` 中添加配置。**所有要组网的节点必须使用相同的 `secret`**。
+Edit `openclaw.json` and add the configuration under `plugins.entries.clawmatrix`. **All nodes in the mesh must use the same `secret`**.
 
-用户需要告知你：
-1. **这个节点的角色**：公网服务器？内网办公机？家庭电脑？
-2. **是否需要接受入站连接**（公网节点通常需要，内网/家庭节点不需要）
-3. **要连接的 peer**（通常是公网节点的 WebSocket 地址）
-4. **本节点提供什么**：有哪些 Agent？有哪些可共享的模型？
-5. **是否允许远程工具执行**（toolProxy）
+The user needs to tell you:
+1. **The role of this node**: Public cloud server? Intranet office machine? Home computer?
+2. **Whether it needs to accept inbound connections** (public nodes usually do; intranet/home nodes do not)
+3. **Peers to connect to** (typically the WebSocket address of a public node)
+4. **What this node provides**: Which Agents? Which models to share?
+5. **Whether to allow remote tool execution** (toolProxy)
 
-### 第 3 步：重启 Gateway
+### Step 3: Restart the Gateway
 
 ```bash
 openclaw gateway restart
 ```
 
-### 第 4 步：验证
+### Step 4: Verify
 
 ```bash
 openclaw clawmatrix status
 ```
 
-## 配置模板
+## Configuration Templates
 
-根据用户的节点角色，选择对应模板并替换占位值。
+Choose the template matching the user's node role and replace the placeholder values.
 
-### 公网节点（中继 + 可选 Agent）
+### Public Node (Relay + Optional Agent)
 
-适用于：有公网 IP 或域名的云服务器。作为 mesh 的中继枢纽，内网和家庭节点都连它。
+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.
 
 ```json
 {
-  "nodeId": "<唯一节点名，如 cloud-01>",
-  "secret": "<所有节点共用的密钥，至少 16 个字符>",
+  "nodeId": "<unique node name, e.g. cloud-01>",
+  "secret": "<shared secret for all nodes, at least 16 characters>",
   "listen": true,
   "listenPort": 19000,
   "peers": [],
   "agents": [
-    { "id": "<agent名>", "description": "<agent描述>", "tags": ["<标签>"] }
+    { "id": "<agent name>", "description": "<agent description>", "tags": ["<tag>"] }
   ],
   "models": [],
   "tags": ["cloud"]
 }
 ```
 
-注意事项：
-- `listenPort` 需要在防火墙/安全组中放行
-- 生产环境建议配置 TLS，让 peer 使用 `wss://` 连接
-- 如果不跑 Agent 可以把 `agents` 设为 `[]`
+Notes:
+- `listenPort` must be opened in your firewall / security group
+- For production, configure TLS so peers connect via `wss://`
+- If no Agent is running on this node, set `agents` to `[]`
 
-### 内网/办公节点（有模型或代码仓库）
+### Intranet / Office Node (With Models or Code Repositories)
 
-适用于：有 GPU、有 API Key、有内网资源的机器。不需要公网 IP，主动连接公网节点。
+For: Machines with GPUs, API keys, or intranet resources. No public IP needed; connects outbound to the public node.
 
 ```json
 {
-  "nodeId": "<唯一节点名，如 office-01>",
-  "secret": "<同上>",
+  "nodeId": "<unique node name, e.g. office-01>",
+  "secret": "<same as above>",
   "listen": false,
   "peers": [
-    { "nodeId": "<公网节点名>", "url": "wss://<公网节点地址>:19000" }
+    { "nodeId": "<public node name>", "url": "wss://<public node address>:19000" }
   ],
   "agents": [
-    { "id": "coder", "description": "有代码仓库访问权限，可以读写代码和执行命令", "tags": ["coding"] }
+    { "id": "coder", "description": "Has code repository access; can read/write code and execute commands", "tags": ["coding"] }
   ],
   "models": [
     { "id": "claude-sonnet", "provider": "anthropic" },
@@ -98,27 +100,27 @@ openclaw clawmatrix status
 }
 ```
 
-注意事项：
-- `models` 里的 `provider` 必须与 OpenClaw `models.providers` 中的 key 一致，ClawMatrix 会自动读取对应的 `baseUrl` 和 `apiKey`
-- 如果需要覆盖（比如用不同的 API 地址），可以显式设置 `baseUrl` 和 `apiKey`
-- ClawMatrix 直接调模型 API，不经过 OpenClaw Gateway 的 agent 系统
-- `toolProxy.enabled: true` 才会接受远程工具调用
-- `toolProxy.deny` 优先于 `allow`，建议禁用高风险工具
+Notes:
+- The `provider` in `models` must match a key in OpenClaw's `models.providers`; ClawMatrix automatically reads the corresponding `baseUrl` and `apiKey`
+- To override (e.g., use a different API address), explicitly set `baseUrl` and `apiKey`
+- ClawMatrix calls the model API directly, bypassing the OpenClaw Gateway's agent system
+- `toolProxy.enabled: true` is required to accept remote tool invocations
+- `toolProxy.deny` takes priority over `allow`; consider denying high-risk tools
 
-### 家庭/轻量节点（借用集群资源）
+### Home / Lightweight Node (Borrowing Cluster Resources)
 
-适用于：个人电脑、轻量设备。没有模型和特殊资源，借用集群。
+For: Personal computers and lightweight devices. No local models or special resources; borrows from the cluster.
 
 ```json
 {
-  "nodeId": "<唯一节点名，如 home-01>",
-  "secret": "<同上>",
+  "nodeId": "<unique node name, e.g. home-01>",
+  "secret": "<same as above>",
   "listen": false,
   "peers": [
-    { "nodeId": "<公网节点名>", "url": "wss://<公网节点地址>:19000" }
+    { "nodeId": "<public node name>", "url": "wss://<public node address>:19000" }
   ],
   "agents": [
-    { "id": "assistant", "description": "个人助手", "tags": ["general"] }
+    { "id": "assistant", "description": "Personal assistant", "tags": ["general"] }
   ],
   "models": [],
   "proxyModels": [
@@ -129,48 +131,48 @@ openclaw clawmatrix status
 }
 ```
 
-如果要用集群中的模型，还需要修改 agent 的模型配置：
+To use models from the cluster, you also need to update the agent's model configuration:
 
 ```json
 {
   "agents": {
     "defaults": {
-      "model": "clawmatrix/<模型ID>"
+      "model": "clawmatrix/<model 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 }`（自动读取 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 | `[]` | 允许的工具名，`["*"]` 或 `[]` 表示全部。`exec`/`read`/`write`/`edit` 本地执行，其余走 Gateway |
-| `toolProxy.deny` | array | `[]` | 禁止的工具名（优先于 allow） |
-| `toolProxy.maxOutputBytes` | number | `1048576` | 单次响应最大字节数 |
-
-## 启用集群工具
-
-ClawMatrix 的 Agent 工具注册为可选工具（optional），需要在 OpenClaw 配置中显式启用。
-
-在 `openclaw.json` 中添加：
+Notes:
+- `nodeId` in `proxyModels` is optional; when specified, requests are routed precisely to that node; when omitted, the cluster finds a suitable node automatically
+- The model ID in `proxyModels` must match the ID declared in the remote node's `models`
+
+## Full Configuration Field Reference
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `nodeId` | string | *required* | Unique node identifier |
+| `secret` | string | *required* | Cluster shared secret, minimum 16 characters |
+| `listen` | boolean | `false` | Whether to accept inbound WebSocket connections |
+| `listenHost` | string | `"0.0.0.0"` | WebSocket listen address |
+| `listenPort` | number | `19000` | Inbound WebSocket port |
+| `peers` | array | `[]` | Peers to connect to: `{ nodeId, url }` |
+| `agents` | array | `[]` | Agents provided by this node: `{ id, description, tags }` |
+| `models` | array | `[]` | Models shared with the cluster: `{ id, provider }` (automatically reads baseUrl/apiKey from the OpenClaw provider; can be overridden) |
+| `proxyModels` | array | `[]` | Remote models consumed from the cluster: `{ id, nodeId?, description? }` |
+| `tags` | array | `[]` | Free-form tags for capability-based routing |
+| `proxyPort` | number | `19001` | Local model proxy HTTP port |
+| `handoffTimeout` | number | `600000` | Handoff timeout in milliseconds (default 10 minutes) |
+| `toolProxy.enabled` | boolean | `false` | Allow remote tool execution |
+| `toolProxy.allow` | array | `[]` | Allowed tool names; `["*"]` or `[]` means all. `exec`/`read`/`write`/`edit` execute locally; others go through the Gateway |
+| `toolProxy.deny` | array | `[]` | Denied tool names (takes priority over allow) |
+| `toolProxy.maxOutputBytes` | number | `1048576` | Maximum bytes per single response |
+
+## Enabling Cluster Tools
+
+ClawMatrix's Agent tools are registered as optional tools. They must be explicitly enabled in the OpenClaw configuration.
+
+Add the following to `openclaw.json`:
 
 ```json
 {
@@ -186,12 +188,12 @@ ClawMatrix 的 Agent 工具注册为可选工具（optional），需要在 OpenC
 }
 ```
 
-配置说明：
-- `profile: "full"` — 启用完整工具集（包括可选工具）
-- `sessions.visibility: "all"` — 允许跨会话访问工具（集群工具需要此设置才能在所有会话中可用）
-- `allow: ["clawmatrix"]` — 显式允许 ClawMatrix 插件注册的所有集群工具
+Configuration details:
+- `profile: "full"` -- Enables the full toolset (including optional tools)
+- `sessions.visibility: "all"` -- Allows cross-session tool access (cluster tools require this setting to be available in all sessions)
+- `allow: ["clawmatrix"]` -- Explicitly allows all cluster tools registered by the ClawMatrix plugin
 
-也可以按 Agent 粒度启用：
+You can also enable tools on a per-Agent basis:
 
 ```json
 {
@@ -212,34 +214,34 @@ ClawMatrix 的 Agent 工具注册为可选工具（optional），需要在 OpenC
 }
 ```
 
-> 如果不配置，Agent 的系统提示中会提到集群工具，但实际无法调用。
+> If not configured, the Agent's system prompt will mention cluster tools, but they will not actually be callable.
 
-启用后，本节点的 Agent 获得 7 个集群工具：
+Once enabled, the node's Agent gains 7 cluster tools:
 
-| 工具 | 用途 | 关键参数 |
-|------|------|----------|
-| `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` |
+| Tool | Purpose | Key Parameters |
+|------|---------|----------------|
+| `cluster_peers` | View cluster topology and connection status | None |
+| `cluster_handoff` | Delegate a task to a remote Agent | `target`, `task`, `context?` |
+| `cluster_send` | Send a one-way message to a remote Agent | `target`, `message` |
+| `cluster_exec` | Execute a command on a remote node | `node`, `command`, `workdir?`, `timeout?` |
+| `cluster_read` | Read a file on a remote node | `node`, `path` |
+| `cluster_write` | Write a file on a remote node | `node`, `path`, `content` |
+| `cluster_tool` | Invoke any OpenClaw tool on a remote node | `node`, `tool`, `args` |
 
-`target` 参数支持 Agent ID（如 `"coder"`）或标签查询（如 `"tags:coding"`）。
-`node` 参数支持 nodeId（如 `"office-01"`）或标签查询（如 `"tags:gpu"`）。
+The `target` parameter accepts an Agent ID (e.g., `"coder"`) or a tag query (e.g., `"tags:coding"`).
+The `node` parameter accepts a nodeId (e.g., `"office-01"`) or a tag query (e.g., `"tags:gpu"`).
 
-## 前置配置：注册集群模型到 OpenClaw
+## Prerequisite: Register Cluster Models in OpenClaw
 
-消费远程模型的节点需要在 `models.providers` 中注册，否则 `/models` 命令看不到集群模型。
+Nodes consuming remote models must register them in `models.providers`; otherwise, the `/models` command will not show cluster models.
 
-以 nodeId 作为 provider key（推荐），baseUrl 指向本地模型代理端口：
+Use the nodeId as the provider key (recommended), with baseUrl pointing to the local model proxy port:
 
 ```json
 {
   "models": {
     "providers": {
-      "<远程nodeId>": {
+      "<remote nodeId>": {
         "baseUrl": "http://127.0.0.1:19001",
         "apiKey": "cluster-internal",
         "auth": "api-key",
@@ -261,28 +263,28 @@ ClawMatrix 的 Agent 工具注册为可选工具（optional），需要在 OpenC
 }
 ```
 
-配置后使用 `/model <nodeId>/<模型ID>` 切换。
+After configuration, use `/model <nodeId>/<model ID>` to switch models.
 
-## 常见问题排查
+## Troubleshooting
 
-**节点连不上**：
-- 检查 `secret` 是否所有节点一致
-- 检查公网节点的 `listenPort` 是否在防火墙中放行
-- 检查 `peers` 中的 URL 格式：`wss://host:port` 或 `ws://host:port`
+**Cannot connect to a node**:
+- Check that `secret` is identical across all nodes
+- Check that the public node's `listenPort` is open in the firewall
+- Check the URL format in `peers`: `wss://host:port` or `ws://host:port`
 
-**远程工具调用失败**：
-- 确认目标节点的 `toolProxy.enabled` 为 `true`
-- 确认目标工具不在 `toolProxy.deny` 列表中
-- 如果 `toolProxy.allow` 非空，确认目标工具在列表中
+**Remote tool invocation fails**:
+- Confirm `toolProxy.enabled` is `true` on the target node
+- Confirm the target tool is not in the `toolProxy.deny` list
+- If `toolProxy.allow` is non-empty, confirm the target tool is in the list
 
-**模型代理不工作**：
-- 确认远程节点的 `models` 中声明了该模型
-- 确认该模型的 `provider` 与 OpenClaw `models.providers` 中的 key 一致（ClawMatrix 会自动读取 baseUrl 和 apiKey）
-- 确认本节点使用 `clawmatrix/<模型ID>` 格式引用模型
-- 如果用了 `proxyModels.nodeId`，确认该节点在线
+**Model proxy not working**:
+- Confirm the model is declared in the remote node's `models`
+- Confirm the model's `provider` matches a key in OpenClaw's `models.providers` (ClawMatrix automatically reads baseUrl and apiKey)
+- Confirm this node references the model using the `clawmatrix/<model ID>` format
+- If `proxyModels.nodeId` is set, confirm that node is online
 
-**查看状态**：
+**Check status**:
 ```bash
-openclaw clawmatrix status   # 表格形式
-openclaw clawmatrix peers    # JSON 格式
+openclaw clawmatrix status   # table format
+openclaw clawmatrix peers    # JSON format
 ```

package/README.md

@@ -1,32 +1,36 @@
+[中文](README_zh.md) | English
+
 # ClawMatrix
 
-去中心化 mesh 集群插件，让多个 [OpenClaw](https://github.com/nicepkg/openclaw) Gateway 组成 peer-to-peer 网络，跨节点共享 Agent、模型和工具。
+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.
+
+> **Warning**: This project is under active development and testing. APIs and protocols may change without notice. Not recommended for production use.
 
-## 功能
+## Features
 
-**模型代理** — 家庭节点没有 API Key？通过集群使用内网节点的 LLM，就像本地模型一样。
+**Model Proxy** — No API key on your home node? Use LLMs from intranet nodes through the cluster, as if they were local models.
 
-**任务 Handoff** — 需要内网资源？将任务委托给有仓库访问权限的远程 Agent，流式返回结果。
+**Task Handoff** — Need intranet resources? Delegate tasks to remote Agents with repository access and stream results back.
 
-**工具代理** — 想在远程节点跑个命令或读个文件？直接调用，不用委托整个任务。
+**Tool Proxy** — Want to run a command or read a file on a remote node? Call it directly without delegating the entire task.
 
-**自动发现 & 故障转移** — Gossip 协议自动发现节点，宕机时请求自动路由到备份。
+**Auto-Discovery & Failover** — Gossip protocol automatically discovers nodes; requests are rerouted to backups when a node goes down.
 
-## 快速开始
+## Quick Start
 
-> **推荐**：将 [BOOTSTRAP.md](BOOTSTRAP.md) 链接发给 OpenClaw Agent，它会引导你完成安装和配置。
+> **Recommended**: Send the [BOOTSTRAP.md](BOOTSTRAP.md) link to your OpenClaw Agent and it will guide you through installation and configuration.
 
-### 安装
+### Installation
 
 ```bash
 openclaw plugins install clawmatrix
 ```
 
-### 配置
+### Configuration
 
-编辑 `openclaw.json`，添加插件配置。所有节点共享同一 `secret`。
+Edit `openclaw.json` to add the plugin configuration. All nodes share the same `secret`.
 
-**公网节点**（中继枢纽）：
+**Public Node** (relay hub):
 
 ```json
 {
@@ -40,7 +44,7 @@ openclaw plugins install clawmatrix
           "listen": true,
           "listenPort": 19000,
           "agents": [
-            { "id": "reviewer", "description": "代码审查", "tags": ["review"] }
+            { "id": "reviewer", "description": "Code review", "tags": ["review"] }
           ]
         }
       }
@@ -49,14 +53,14 @@ openclaw plugins install clawmatrix
 }
 ```
 
-**内网节点**（有模型和仓库）：
+**Intranet Node** (with models and repositories):
 
 ```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"] }],
+  "agents": [{ "id": "coder", "description": "Code development", "tags": ["coding"] }],
   "models": [
     { "id": "claude-sonnet", "provider": "anthropic" },
     { "id": "deepseek-coder", "provider": "ollama" }
@@ -65,99 +69,100 @@ openclaw plugins install clawmatrix
 }
 ```
 
-**家庭节点**（借用集群资源）：
+**Home Node** (borrowing cluster resources):
 
 ```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"] }],
+  "agents": [{ "id": "assistant", "description": "Personal assistant", "tags": ["general"] }],
   "proxyModels": [{ "id": "claude-sonnet", "nodeId": "office-01" }]
 }
 ```
 
-**重要**：共享模型的节点只需在 `models` 中声明 `{ id, provider }`，ClawMatrix 会自动从 OpenClaw 的 `models.providers` 读取对应的 `baseUrl` 和 `apiKey`，直接调用模型 API（不经过 OpenClaw Gateway 的 agent 系统）。
+**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).
 
-消费远程模型的节点需要在 `models.providers` 中注册（以 nodeId 为 key，baseUrl 指向 `http://127.0.0.1:19001`），详见 [BOOTSTRAP.md](BOOTSTRAP.md)。
+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.
 
-使用集群模型：`/model <nodeId>/<模型ID>`。
+To use a cluster model: `/model <nodeId>/<modelId>`.
 
-### 启动
+### Start
 
 ```bash
 openclaw gateway restart
 openclaw clawmatrix status
 ```
 
-## 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 }`（自动读取 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 | `[]` | 允许的工具名，`["*"]` 或 `[]` 表示全部。`exec`/`read`/`write`/`edit` 本地执行，其余走 Gateway |
-| `toolProxy.deny` | array | `[]` | 禁止的工具（优先于 allow） |
-
-## 架构
+## Agent Tools
+
+After installation, the Agent automatically gains access to the following tools:
+
+| Tool | Description |
+|------|-------------|
+| `cluster_handoff` | Delegate a task to a remote Agent and wait for the result |
+| `cluster_send` | Send a one-way message to a remote Agent |
+| `cluster_peers` | View cluster topology and connection status |
+| `cluster_exec` | Execute a command on a remote node |
+| `cluster_read` | Read a file on a remote node |
+| `cluster_write` | Write a file on a remote node |
+| `cluster_tool` | Invoke any OpenClaw tool on a remote node |
+
+The target parameter supports nodeId (`"office-01"`) or tag queries (`"tags:coding"`).
+
+## Configuration Reference
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `nodeId` | string | required | Unique node identifier |
+| `secret` | string | required | Cluster shared secret (>= 16 characters) |
+| `listen` | boolean | `false` | Accept inbound WS connections |
+| `listenHost` | string | `"0.0.0.0"` | Listen address |
+| `listenPort` | number | `19000` | Inbound WS port |
+| `peers` | array | `[]` | Peers to connect to: `{ nodeId, url }` |
+| `agents` | array | `[]` | Local Agents: `{ id, description, tags }` |
+| `models` | array | `[]` | Models shared with the cluster: `{ id, provider }` (auto-reads OpenClaw provider config; optional `baseUrl`/`apiKey` override) |
+| `proxyModels` | array | `[]` | Remote models to consume: `{ id, nodeId? }` |
+| `tags` | array | `[]` | Free-form tags |
+| `proxyPort` | number | `19001` | Local model proxy port |
+| `handoffTimeout` | number | `600000` | Handoff timeout (ms) |
+| `toolProxy.enabled` | boolean | `false` | Allow remote tool execution |
+| `toolProxy.allow` | array | `[]` | Allowed tool names; `["*"]` or `[]` means all. `exec`/`read`/`write`/`edit` run locally, others go through Gateway |
+| `toolProxy.deny` | array | `[]` | Denied tools (takes precedence over allow) |
+
+## Architecture
 
 ```
           ┌──────────────────────────┐
-          │   公网 Gateway           │
+          │   Public Gateway         │
           │   listen: true           │
           │   listenPort: 19000      │
           └──┬──────────────────┬────┘
     inbound  │                  │  inbound
     WS conn  │                  │  WS conn
           ┌──┴────┐        ┌────┴──────┐
-          │ 家庭   │        │ 内网办公室 │
+          │ Home   │        │ Intranet  │
+          │        │        │ Office    │
           └───────┘        └──────────┘
 ```
 
-- 去中心化 mesh，无 leader，无共识协议
-- HMAC-SHA256 challenge-response 认证
-- 消息中继 + TTL 防环 + ID 去重
-- 心跳检测 + 指数退避重连 + 自动故障转移
-- 生产环境建议 `wss://`（TLS）
+- Decentralized mesh — no leader, no consensus protocol
+- HMAC-SHA256 challenge-response authentication
+- Message relay + TTL loop prevention + ID deduplication
+- Heartbeat detection + exponential backoff reconnection + automatic failover
+- `wss://` (TLS) recommended for production
 
-## 开发
+## Development
 
 ```bash
-bun install    # 安装依赖
-bun test       # 运行测试
+bun install    # Install dependencies
+bun test       # Run tests
 ```
 
-## 文档
+## Documentation
 
-- [技术规格](docs/SPEC.md) — 完整协议、消息类型、安全设计
-- [安装指南](BOOTSTRAP.md) — AI Agent 辅助安装配置
+- [Technical Spec](docs/SPEC.md) — Full protocol, message types, and security design
+- [Installation Guide](BOOTSTRAP.md) — AI Agent-assisted installation and configuration
 
 ## License