# 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

```mermaid
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](/llms/platform/libraries/moltlazy/feature-packs/index.md).

## 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`).