Overview

Two-system configuration toolkit for OpenClaw gateway.

Architecture (v0.3)

Moltlazy has two separate systems that coexist:

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 — Get running in 5 minutes
• Concepts — Understand the two-system architecture
• SDK Domain Modules — Typed RPC client domain module reference
• Startup Flow — How Config Module and SDK work together
• Feature Flags Reference — JSON feature flags format
• Migration Guide — Migrate from v0.2 filesystem patching

Development

Requires Bun.

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.