clawmatrix 0.1.6 → 0.1.11

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