openclaw-mcp 1.2.0 → 1.3.0

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 (7) hide show
  1. package/README.md +1 -0
  2. package/dist/index.js +296 -45
  3. package/docs/CNAME +1 -0
  4. package/docs/assets/og-image.png +0 -0
  5. package/docs/configuration.md +63 -20
  6. package/docs/index.html +653 -0
  7. package/package.json +1 -1
package/docs/configuration.md CHANGED
@@ -6,27 +6,67 @@ All configuration can be done via environment variables. Copy `.env.example` to
6
6
 
7
7
  ### OpenClaw Connection
8
8
 
9
- | Variable | Description | Default |
10
- |----------|-------------|---------|
11
- | `OPENCLAW_URL` | OpenClaw gateway URL | `http://127.0.0.1:18789` |
12
- | `OPENCLAW_GATEWAY_TOKEN` | Bearer token for gateway authentication | (none) |
13
- | `OPENCLAW_TIMEOUT_MS` | Request timeout in milliseconds | `120000` (2 min) |
9
+ | Variable | Description | Default |
10
+ | ------------------------ | --------------------------------------- | ------------------------ |
11
+ | `OPENCLAW_URL` | OpenClaw gateway URL | `http://127.0.0.1:18789` |
12
+ | `OPENCLAW_GATEWAY_TOKEN` | Bearer token for gateway authentication | (none) |
13
+ | `OPENCLAW_TIMEOUT_MS` | Request timeout in milliseconds | `120000` (2 min) |
14
+
15
+ ### Multi-Instance Mode
16
+
17
+ Orchestrate multiple OpenClaw gateways from a single MCP server. Set `OPENCLAW_INSTANCES` as a JSON array — when present, it takes precedence over `OPENCLAW_URL` / `OPENCLAW_GATEWAY_TOKEN`.
18
+
19
+ | Variable | Description | Default |
20
+ | -------------------- | ------------------------------ | ----------------------------- |
21
+ | `OPENCLAW_INSTANCES` | JSON array of instance configs | (none — single-instance mode) |
22
+
23
+ **Example:**
24
+
25
+ ```bash
26
+ OPENCLAW_INSTANCES='[
27
+ {"name": "prod", "url": "http://prod:18789", "token": "tok1", "default": true},
28
+ {"name": "staging", "url": "http://staging:18789", "token": "tok2"},
29
+ {"name": "dev", "url": "http://dev:18789", "token": "tok3"}
30
+ ]'
31
+ ```
32
+
33
+ Each instance object supports:
34
+
35
+ | Field | Type | Required | Description |
36
+ | --------- | ------- | -------- | ------------------------------------------------------------------------ |
37
+ | `name` | string | Yes | Unique instance name (1-64 chars, alphanumeric/dashes/underscores) |
38
+ | `url` | string | Yes | OpenClaw gateway URL (http or https only) |
39
+ | `token` | string | No | Bearer token for gateway authentication |
40
+ | `timeout` | number | No | Request timeout in ms (inherits global `OPENCLAW_TIMEOUT_MS` if omitted) |
41
+ | `default` | boolean | No | Mark as the default instance (first instance is default if none marked) |
42
+
43
+ **Using instances in tools:**
44
+
45
+ All gateway-facing tools (`openclaw_chat`, `openclaw_status`, `openclaw_chat_async`) accept an optional `instance` parameter. When omitted, the default instance is used.
46
+
47
+ ```
48
+ openclaw_chat message="Hello" instance="staging"
49
+ openclaw_instances # list all available instances
50
+ ```
51
+
52
+ **Backward compatibility:** When `OPENCLAW_INSTANCES` is not set, the server creates a single `"default"` instance from `OPENCLAW_URL` + `OPENCLAW_GATEWAY_TOKEN`. Existing deployments work without any configuration change.
14
53
 
15
54
  ### Server Settings (SSE transport)
16
55
 
17
- | Variable | Description | Default |
18
- |----------|-------------|---------|
19
- | `PORT` | SSE server port | `3000` |
20
- | `HOST` | SSE server host | `0.0.0.0` |
21
- | `DEBUG` | Enable debug logging | `false` |
56
+ | Variable | Description | Default |
57
+ | -------- | -------------------- | --------- |
58
+ | `PORT` | SSE server port | `3000` |
59
+ | `HOST` | SSE server host | `0.0.0.0` |
60
+ | `DEBUG` | Enable debug logging | `false` |
22
61
 
23
62
  ### CORS Configuration
24
63
 
25
- | Variable | Description | Default |
26
- |----------|-------------|---------|
27
- | `CORS_ORIGINS` | Allowed origins (comma-separated) | `*` |
64
+ | Variable | Description | Default |
65
+ | -------------- | --------------------------------- | ------- |
66
+ | `CORS_ORIGINS` | Allowed origins (comma-separated) | `*` |
28
67
 
29
68
  **CORS_ORIGINS examples:**
69
+
30
70
  - `*` — Allow all origins (not recommended for production)
31
71
  - `none` — Disable CORS entirely
32
72
  - `https://claude.ai` — Single origin
@@ -37,24 +77,27 @@ All configuration can be done via environment variables. Copy `.env.example` to
37
77
 
38
78
  The server uses the MCP SDK's built-in OAuth 2.1 server with authorization code + PKCE flow. This is what Claude.ai requires for custom MCP connectors.
39
79
 
40
- | Variable | Description | Required |
41
- |----------|-------------|----------|
42
- | `AUTH_ENABLED` | Enable OAuth authentication (`true`/`false`) | Yes for production |
43
- | `MCP_CLIENT_ID` | OAuth client ID (e.g., `openclaw`) | When auth enabled |
44
- | `MCP_CLIENT_SECRET` | OAuth client secret | When auth enabled |
45
- | `MCP_ISSUER_URL` | OAuth issuer URL override (e.g., `https://mcp.example.com`) | When behind HTTPS proxy |
46
- | `MCP_REDIRECT_URIS` | Allowed redirect URIs (comma-separated) | Recommended for production |
80
+ | Variable | Description | Required |
81
+ | ------------------- | ----------------------------------------------------------- | -------------------------- |
82
+ | `AUTH_ENABLED` | Enable OAuth authentication (`true`/`false`) | Yes for production |
83
+ | `MCP_CLIENT_ID` | OAuth client ID (e.g., `openclaw`) | When auth enabled |
84
+ | `MCP_CLIENT_SECRET` | OAuth client secret | When auth enabled |
85
+ | `MCP_ISSUER_URL` | OAuth issuer URL override (e.g., `https://mcp.example.com`) | When behind HTTPS proxy |
86
+ | `MCP_REDIRECT_URIS` | Allowed redirect URIs (comma-separated) | Recommended for production |
47
87
 
48
88
  **Client ID validation rules:**
89
+
49
90
  - 3–64 characters
50
91
  - Alphanumeric, dashes, underscores only
51
92
  - Must start with a letter or digit
52
93
 
53
94
  **Client Secret requirements:**
95
+
54
96
  - Minimum 32 characters
55
97
  - Generate a secure one: `openssl rand -hex 32`
56
98
 
57
99
  When auth is enabled, the server exposes these OAuth 2.1 endpoints:
100
+
58
101
  - `GET /.well-known/oauth-authorization-server` — OAuth server metadata
59
102
  - `GET /.well-known/oauth-protected-resource/mcp` — Protected resource metadata
60
103
  - `GET /authorize` — Authorization endpoint (auto-approves for pre-configured client)