Migration Guide (v0.2 → v0.3)

The v0.3 release replaces direct filesystem patching of openclaw.json with an immutable $include-based approach. Moltlazy now generates /home/openclaw/.openclaw/moltlazy.json containing all mandatory config sections and injects a $include: "./moltlazy.json" directive into openclaw.json.

What changed

flowchart LR
    subgraph v02["v0.2 (filesystem patching)"]
        A["Worker"] --> B["TOML env var"]
        B --> C["moltlazy patch"]
        C --> D["Write to\nopenclaw.json"]
        D --> E["TOML changes trigger re-patch"]
    end

    subgraph v03["v0.3 ($include)"]
        F["Worker"] --> G["MOLTLAZY_FEATURE_FLAGS"]
        G --> H["moltlazy patch"]
        H --> I["Generate\nmoltlazy.json"]
        I --> J["Inject $include into\nopenclaw.json"]
        J --> K["OpenClaw natively\nmerges on startup"]
    end

What’s removed

v0.2 concept	v0.3 replacement
TOML config (moltlazy.toml)	Removed — feature flags via MOLTLAZY_FEATURE_FLAGS env var
Force flags (--force-gateway, --force-channels, --force-agents)	Removed — $include is always authoritative
init-toml CLI command	Removed
moltlazy-meta.json (patch tracking)	Removed — $include is idempotent
shouldPatchConfig() (skip/merge decision)	Removed — always generate moltlazy.json
computeConfigHash() / MOLTLAZY_TOML_ETAG	Removed — no longer needed
config/toml.ts and default.toml	Removed
Deprecated enableUnifiedBilling alias	Use unifiedBilling directly
Deprecated enableMicrosoftGraph alias	Use microsoftGraph directly

What’s new

Config Module (startup-time):

Module	Config Section	Purpose
config/tools.ts	tools.toolSearch	Mandatory: enables tool search in “tools” mode
config/logging.ts	logging	Mandatory: production logging with sensitive data redaction
config/include.ts	$include directive	Generates moltlazy.json and injects $include into openclaw.json

SDK Module (runtime RPC):

Feature packs (buildToolsCalls(), buildLoggingCalls(), etc.) are removed in v0.3. Use createClient() domain modules directly — see SDK Domain Modules.

How it works

1. Worker passes feature flags as MOLTLAZY_FEATURE_FLAGS JSON env var: {"knowledgeGraph":true,"unifiedBilling":false}
2. start-openclaw.sh runs moltlazy patch
3. moltlazy patch:
   • Reads env vars for secrets, feature flags from MOLTLAZY_FEATURE_FLAGS
   • Assembles all mandatory config sections (gateway, session, tools, logging)
   • Writes /home/openclaw/.openclaw/moltlazy.json (regenerated from scratch each startup)
   • Injects $include: "./moltlazy.json" into openclaw.json if not already present
4. OpenClaw starts, loads openclaw.json, natively merges the $include
5. User overrides in openclaw.json take precedence over moltlazy.json (sibling key merge)

Key differences

moltlazy.json is immutable

The generated moltlazy.json is regenerated from scratch on every startup. Do not edit it manually — changes will be overwritten. Use openclaw.json for any user overrides.

No more force flags

Since moltlazy.json is authoritative and regenerated each time, force flags (--force-gateway, --force-channels, etc.) are unnecessary. The $include mechanism always overwrites moltlazy-owned sections.

Channel tokens remain in openclaw.json

Channel tokens (Telegram, Discord, Slack) are still written to openclaw.json directly since they come from env vars. They are excluded from moltlazy.json to keep secrets out of the include file.

Worker env var changes

Old env var	New env var
MOLTLAZY_TOML_CONTENT	MOLTLAZY_FEATURE_FLAGS
MOLTLAZY_TOML_PATH	— (removed)
MOLTLAZY_TOML_ETAG	— (removed)
MOLTLAZY_CONFIG_PATH	New: override path for moltlazy.json output

Startup flow change

v0.2

Worker → TOML env var → container writes TOML → moltlazy reads TOML → patches openclaw.json

v0.3

Worker → MOLTLAZY_FEATURE_FLAGS → moltlazy generates moltlazy.json → injects $include into openclaw.json

The result: clean separation between moltlazy-owned config (moltlazy.json) and user-owned config (openclaw.json).