minions-openclaw

A production-quality monorepo for managing OpenClaw Gateway instances using minions-sdk for structured data management.

Overview

minions-openclaw provides a TypeScript SDK, Python SDK, and CLI for:

• Registering and managing multiple OpenClaw Gateway instances
• Capturing point-in-time configuration snapshots
• Decomposing openclaw.json configs into a structured minion tree
• Monitoring live gateway state (agents, channels, model providers)
• Diffing configuration across time or between instances

Features

• 🔗 Multi-instance management — Register and manage a fleet of OpenClaw Gateway instances
• 📸 Snapshot capture — Capture live state snapshots for audit and comparison
• 🔄 Config decomposition — Parse openclaw.json into structured minions with typed schemas
• 📊 Diff & history — Compare snapshots over time to track configuration drift
• 🔐 Device authentication — RSA-based device challenge/response authentication
• 🌐 WebSocket client — Full protocol implementation of the OpenClaw Gateway WS API
• 🐍 Python SDK — Equivalent Python library for use in scripts and automation
• 📖 Documentation — Astro Starlight docs site

Installation

CLI (global)

npm install -g @minions-openclaw/cli

TypeScript SDK

npm install @minions-openclaw/sdk

Python SDK

pip install minions-openclaw

Quick Start

Register a gateway instance

openclaw-manager register my-gateway --url ws://192.168.1.100:8080 --token mytoken

List registered instances

openclaw-manager list

Ping an instance

openclaw-manager ping <instanceId>

Capture a snapshot

openclaw-manager snapshot <instanceId>

View snapshot history

openclaw-manager history <instanceId>

CLI Command Reference

openclaw-manager [command] [options]

Commands:
  register <name>         Register a new OpenClaw Gateway instance
    --url <url>           Gateway WebSocket URL (required)
    --token <token>       Auth token (optional)

  ping <instanceId>       Ping an instance and record latency

  snapshot <instanceId>   Capture a live snapshot of gateway state

  list                    List all registered instances

  history <instanceId>    Show snapshot history for an instance

  agents <instanceId>     List agents on a gateway
  channels <instanceId>   List channels on a gateway
  models <instanceId>     List model providers on a gateway

  config show <instanceId>              Show latest config
  config diff <id1> <id2>               Diff two snapshots
  config export <instanceId>            Export config as JSON
  config import <instanceId> --file <path>  Import config from file

TypeScript SDK Usage

import { MinionsOpenClaw } from '@minions-openclaw/sdk';

const minions = new MinionsOpenClaw();

// Register an instance
const instance = await minions.openclaw.instances.register('my-gateway', 'ws://localhost:8080', 'token');

// Connect and fetch live state
const client = minions.openclaw.createGatewayClient(instance.fields['url'] as string, 'token');
await client.openConnection();
const presence = await client.fetchPresence();
await client.close();

// Capture a snapshot
const snapshot = await minions.openclaw.snapshots.captureSnapshot(instance.id, presence);

// Decompose a config file
const config = await minions.openclaw.config.loadFromFile('./openclaw.json');
const { minions: newMinions, relations } = minions.openclaw.config.decompose(config, instance.id);

Python SDK Usage

from minions_openclaw import MinionsOpenClaw
import asyncio

minions = MinionsOpenClaw()

# Register an instance
instance = minions.openclaw.instances.register('my-gateway', 'ws://localhost:8080', 'token')

# Async: connect and fetch state
async def capture():
    client = minions.openclaw.create_gateway_client(instance.fields['url'], token='token')
    await client.open_connection()
    presence = await client.fetch_presence()
    await client.close()

    snapshot = minions.openclaw.snapshots.capture_snapshot(instance.id, presence)
    print(f'Snapshot: {snapshot.id}')

asyncio.run(capture())

Architecture

minions-openclaw/
├── packages/
│   ├── core/          # TypeScript library (@minions-openclaw/sdk)
│   │   ├── src/
│   │   │   ├── types.ts           # MinionType definitions for all OpenClaw entities
│   │   │   ├── InstanceManager.ts # CRUD for gateway instances
│   │   │   ├── GatewayClient.ts   # WebSocket client (challenge/response auth)
│   │   │   ├── SnapshotManager.ts # Snapshot capture & diff
│   │   │   ├── ConfigDecomposer.ts# openclaw.json → minion tree
│   │   │   └── index.ts           # Public exports
│   │   └── test/                  # Jest tests
│   ├── cli/           # CLI tool (@minions-openclaw/cli)
│   │   └── src/commands/          # Commander.js commands
│   └── python/        # Python SDK (minions-openclaw)
│       ├── minions_openclaw/
│       └── tests/
├── apps/
│   └── docs/          # Astro Starlight documentation
├── examples/
│   ├── typescript/    # TypeScript usage examples
│   └── python/        # Python usage examples
└── spec/
    └── v0.1.md        # Technical specification

Data Storage

Instances and snapshots are persisted to ~/.openclaw-manager/data.json using the minions-sdk structured object format.

Connection Protocol

The GatewayClient implements the OpenClaw WebSocket protocol:

1. Server sends connect.challenge with nonce + timestamp
2. Client signs challenge with RSA private key (or sends empty signature)
3. Server responds with hello-ok (or hello-error)
4. Client can then call methods via { type: "call", id, method, params }

Development Setup

# Clone the repo
git clone https://github.com/minions-openclaw/minions-openclaw.git
cd minions-openclaw

# Install all JS dependencies (workspaces)
npm install

# Build TypeScript packages
npm run build

# Run TypeScript tests
npm run test -w packages/core

# Python setup
cd packages/python
pip install -e ".[dev]"
pytest tests/ -v

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feat/my-feature)
3. Make your changes and add tests
4. Run the test suite (npm test && cd packages/python && pytest)
5. Commit your changes (git commit -m 'feat: add my feature')
6. Push and open a Pull Request

License

MIT — see LICENSE for details.