# Overview

Two-system configuration toolkit for [OpenClaw](https://docs.openclaw.ai/) gateway.

## Architecture (v0.3)

Moltlazy has **two separate systems** that coexist:

```mermaid
flowchart TD
    subgraph CM["Config Module (startup)"]
        ENV["Env vars\n(secrets)"]
        FLAGS["Feature flags\n(MOLTLAZY_FEATURE_FLAGS)"]
        ENV --> PATCH["moltlazy patch"]
        FLAGS --> PATCH
        PATCH --> JSON["moltlazy.json"]
        JSON --> INCLUDE["$include injection\ninto openclaw.json"]
        INCLUDE --> GW["OpenClaw loads\nboth files on startup"]
    end

    subgraph SDK["SDK Module (running gateway)"]
        FLAGS2["Feature flags"]
        ENV2["Env vars"]
        FLAGS2 --> FP["Feature Packs\n(pure functions)"]
        ENV2 --> FP
        FP --> RPC["Ordered RPC calls\nPOST /api/v1/admin/rpc"]
        RPC --> GW2["OpenClaw Gateway\nmanages own persistence"]
    end
```

1. **Config Module** (`config/` + `index.ts` + `cli.ts`) — Generates `/home/openclaw/.openclaw/moltlazy.json` and injects `$include: "./moltlazy.json"` into `openclaw.json`. Runs once at container startup. The generated file is immutable (regenerated from scratch each startup) and secret-free.

2. **SDK Module** (`sdk/`) — Applies configuration to a **running** gateway via Admin HTTP RPC. No filesystem writes — pure typed RPC calls. Used by the Cloudflare Worker after the gateway is up.

## What's new in v0.3

| What              | Change                                                                       |
| ----------------- | ---------------------------------------------------------------------------- |
| Config approach   | Direct filesystem patching → immutable `$include`-based `moltlazy.json`      |
| Feature flags     | TOML config → JSON `MOLTLAZY_FEATURE_FLAGS` env var                          |
| Force flags       | `--force-gateway`, `--force-channels`, etc. → removed (always authoritative) |
| Patch metadata    | `moltlazy-meta.json`, `shouldPatchConfig()` → removed (idempotent)           |
| Mandatory modules | New: `tools.ts` (tool search), `logging.ts` (production logging)             |
| SDK types         | All types aligned to upstream `ProtocolSchemas` contract                     |
| TOML system       | `config/toml.ts`, `default.toml` → fully removed                             |

## Two capabilities

1. **Config Module** — `moltlazy patch` generates `moltlazy.json` and injects `$include`. Runs at startup before the gateway starts.
2. **SDK** — Typed RPC client (`createClient()`) with 7 domain modules for interacting with a running gateway via Admin HTTP RPC.

## Quick links

- [Quickstart](/llms/platform/libraries/moltlazy/quickstart/index.md) — Get running in 5 minutes
- [Concepts](/llms/platform/libraries/moltlazy/concepts/index.md) — Understand the two-system architecture
- [SDK Domain Modules](/llms/platform/libraries/moltlazy/feature-packs/index.md) — Typed RPC client domain module reference
- [Startup Flow](/llms/platform/libraries/moltlazy/orchestration/index.md) — How Config Module and SDK work together
- [Feature Flags Reference](/llms/platform/libraries/moltlazy/feature-flags-reference/index.md) — JSON feature flags format
- [Migration Guide](/llms/platform/libraries/moltlazy/migration/index.md) — Migrate from v0.2 filesystem patching

## Development

Requires [Bun](https://bun.sh).

```bash
bun install       # install deps
bun run build     # compile TypeScript → dist/
bun test          # run unit tests (vitest)
bun run typecheck # type-check without emitting
bun run lint      # lint with oxlint
```

608 tests across 33 test files.