openclaw-mcp 1.2.1 → 1.3.1

package/README.md

@@ -4,6 +4,7 @@
 [![CI](https://github.com/freema/openclaw-mcp/workflows/CI/badge.svg)](https://github.com/freema/openclaw-mcp/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![GHCR](https://img.shields.io/badge/GHCR-ghcr.io%2Ffreema%2Fopenclaw--mcp-blue?logo=github)](https://github.com/freema/openclaw-mcp/pkgs/container/openclaw-mcp)
+[![Website](https://img.shields.io/badge/Website-openclaw--mcp.cloud-e24b4a)](https://openclaw-mcp.cloud)
 
 <a href="https://glama.ai/mcp/servers/@freema/openclaw-mcp">
   <img width="380" height="200" src="https://glama.ai/mcp/servers/@freema/openclaw-mcp/badge" />
@@ -46,6 +47,7 @@ services:
     environment:
       - OPENCLAW_URL=http://host.docker.internal:18789
       - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
+      - OPENCLAW_MODEL=openclaw
       - AUTH_ENABLED=true
       - MCP_CLIENT_ID=openclaw
       - MCP_CLIENT_SECRET=${MCP_CLIENT_SECRET}
@@ -87,6 +89,7 @@ Add to your Claude Desktop config:
       "env": {
         "OPENCLAW_URL": "http://127.0.0.1:18789",
         "OPENCLAW_GATEWAY_TOKEN": "your-gateway-token",
+        "OPENCLAW_MODEL": "openclaw",
         "OPENCLAW_TIMEOUT_MS": "300000"
       }
     }
@@ -140,6 +143,7 @@ See [Installation Guide](docs/installation.md) for details.
 |------|-------------|
 | `openclaw_chat` | Send messages to OpenClaw and get responses |
 | `openclaw_status` | Check OpenClaw gateway health |
+| `openclaw_instances` | List all configured OpenClaw instances |
 
 ### Async Tools (for long-running operations)
 
@@ -150,6 +154,80 @@ See [Installation Guide](docs/installation.md) for details.
 | `openclaw_task_list` | List all tasks with filtering |
 | `openclaw_task_cancel` | Cancel a pending task |
 
+## Multi-Instance Mode
+
+Orchestrate multiple OpenClaw gateways from a single MCP server. One bridge, many claws — route requests to prod, staging, dev, or whatever you name them (lobster-supreme and the-claw-abides are perfectly valid names).
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│                        Claude.ai / Claude Desktop                    │
+│                              (MCP Client)                            │
+└──────────────────────┬───────────────────────────────────────────────┘
+                       │
+                       ▼
+┌──────────────────────────────────────────────────────────────────────┐
+│                     OpenClaw MCP Bridge Server                        │
+│                                                                      │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐               │
+│  │  Instance     │  │  Instance     │  │  Instance     │              │
+│  │  Registry     │  │  Resolver     │  │  Validator    │              │
+│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘               │
+│         │                 │                  │                        │
+│  ┌──────┴─────────────────┴──────────────────┴───────┐               │
+│  │              Per-Instance OpenClaw Clients          │              │
+│  │     (separate auth, timeout, URL per instance)     │              │
+│  └────────┬──────────────┬──────────────┬────────────┘               │
+└───────────┼──────────────┼──────────────┼────────────────────────────┘
+            │              │              │
+            ▼              ▼              ▼
+   ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
+   │  🦞 prod     │ │  🦞 staging  │ │  🦞 dev      │
+   │  (default)   │ │              │ │              │
+   │  :18789      │ │  :18789      │ │  :18789      │
+   │  OpenClaw GW │ │  OpenClaw GW │ │  OpenClaw GW │
+   └──────────────┘ └──────────────┘ └──────────────┘
+```
+
+### Setup
+
+```bash
+OPENCLAW_INSTANCES='[
+  {"name": "prod", "url": "http://prod:18789", "token": "tok1", "default": true},
+  {"name": "staging", "url": "http://staging:18789", "token": "tok2"},
+  {"name": "dev", "url": "http://dev:18789", "token": "tok3"}
+]'
+```
+
+### Usage
+
+All tools accept an optional `instance` parameter to target a specific gateway:
+
+```
+# Chat with staging instance
+openclaw_chat message="Deploy status?" instance="staging"
+
+# Check health of prod
+openclaw_status instance="prod"
+
+# List all configured instances
+openclaw_instances
+
+# Async task targeting dev
+openclaw_chat_async message="Run tests" instance="dev"
+```
+
+When `instance` is omitted, the default instance is used. Each instance has its own auth token, timeout, and URL — fully isolated.
+
+### Key Features
+
+- **Zero-migration upgrade** — existing single-instance deployments work without any config change
+- **Per-instance isolation** — separate auth tokens, timeouts, and URLs
+- **Dynamic routing** — Claude picks the right instance per request
+- **Task tracking** — async tasks remember which instance they target
+- **Security** — tokens are never exposed via `openclaw_instances`
+
+See [Configuration — Multi-Instance Mode](docs/configuration.md#multi-instance-mode) for the full reference.
+
 ## Documentation
 
 - [Installation](docs/installation.md) — Setup for Claude Desktop & Claude.ai