Walkthrough

Adds ownership-aware merging for openclaw.json during sandbox restore: the code can read the remote file, selectively merge backup + runtime config via mergeOpenClawRestoredConfig, and restore the merged bytes; tests verify non-resurrection and correct precedence.

Changes

OpenClaw Config Restore with Selective Merge

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• NVIDIA/NemoClaw#5101: Related work around making openclaw.json durable in state_files and snapshot test updates.

Suggested labels

integration: openclaw, area: sandbox, bug-fix, area: integrations

Suggested reviewers

• cv
• prekshivyas

Poem

🐰 A rabbit in the code-hop light,
Gently blends the old and bright,
Keeps the runtime keys intact,
Skips the channels left abstract,
Hops away — state whole and right.

❌ Failed checks (1 warning)

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

• rebuild-openclaw-e2e (high): Highest-signal existing E2E for this change: it exercises OpenClaw rebuild, sandbox state backup/restore, gateway token rotation, config hash validity, post-rebuild inference, policy survival, and credential absence in rebuild backups. The changed restore path is directly used here.
• snapshot-commands-e2e (medium): Covers the user-facing snapshot create/list/restore lifecycle. Since the PR changes restoreStateFile input construction for openclaw.json, this should run to catch regressions in real snapshot restore behavior and no-credential snapshot checks.
• credential-sanitization-e2e (high): The restore merge handles credential-bearing OpenClaw config after sanitized backups are created. This suite is the existing broad E2E guard for credential stripping, snapshot/migration credential boundaries, and sandbox runtime credential exposure.
• channels-add-remove-e2e (high): The new merge ownership rules explicitly avoid resurrecting NemoClaw-managed channel blocks and preserve current generated channel placeholders. This existing E2E exercises channel add/remove lifecycle plus rebuild-related gateway credential reuse, making it relevant to the managed-channel restore behavior.

Optional E2E

• channels-stop-start-e2e (very high): Additional confidence for managed-channel enable/disable state across telegram, discord, wechat, slack, and whatsapp. Useful because the merge code controls whether backed-up managed channels can overwrite or resurrect current channel state, but it is broader and slower than the add/remove rebuild guard.
• messaging-providers-e2e (high): Adjacent confidence for provider placeholders, OpenClaw channel config patching, and L7 proxy token rewriting after config changes. Not merge-blocking unless reviewers are specifically concerned about provider placeholder merge semantics.
• state-backup-restore-e2e (high): General backup/restore lifecycle confidence for sandbox state. It is less targeted than snapshot-commands/rebuild-openclaw for the openclaw.json selective merge, so keep it optional.
• full (medium): Clean install/onboard/live inference smoke via E2E / Branch Validation can provide broad end-to-end confidence that the branch still works from source, but it does not specifically target snapshot/rebuild restore merge behavior.

New E2E recommendations

• OpenClaw selective config restore merge (high): Existing E2Es cover rebuild, snapshot restore, credentials, and channel lifecycle, but none appear to directly assert the new ownership contract end-to-end in a live sandbox: fresh gateway/diagnostics/model/channel/plugin sections win, backup-only custom providers/plugins/mcpServers/customAgents survive, and removed managed channels are not resurrected.
  • Suggested test: Add a targeted live E2E that seeds openclaw.json with stale managed channel/provider/plugin/runtime values plus durable custom sections, performs snapshot restore or rebuild, then asserts current runtime-owned OpenClaw config wins while durable user-owned backup sections survive and sanitized secrets remain stripped.

Dispatch hint

• Workflow: .github/workflows/nightly-e2e.yaml
• jobs input: rebuild-openclaw-e2e,snapshot-commands-e2e,credential-sanitization-e2e,channels-add-remove-e2e

E2E Scenario Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required scenario E2E

• None. The PR changes OpenClaw snapshot/rebuild restore logic and non-scenario tests, but no live-supported Vitest registry scenario on trusted main exercises snapshot restore. The closest rebuild scenario, ubuntu-rebuild-openclaw, is present in the registry but is not live-supported because its lifecycle profile is not wired for live Vitest execution. Therefore no scenario E2E dispatch is recommended.

Optional scenario E2E

• None.

Relevant changed files

• src/lib/state/openclaw-config-merge.ts
• src/lib/state/sandbox.ts

🛠️ Needs attention

• Avoid wholesale backup fallback for OpenClaw runtime-owned config (src/lib/state/sandbox.ts:949): The new ownership contract only applies when the freshly rebuilt openclaw.json can be read and both configs parse. If the current read returns null or either JSON parse/merge throws, buildStateFileRestoreInput() restores backupContents as-is. That bypasses the PR's core guarantee to preserve rebuilt gateway/proxy/diagnostics and current managed channel/provider/plugin state, and can resurrect stale sanitized channel placeholders or delete fresh runtime auth/routing state.
  • Recommendation: For OpenClaw openclaw.json, make current-read/parse failures explicit restore failures, or implement a degraded path that never clobbers runtime-owned sections. Add regression tests for current read failure, missing current file, invalid current JSON, and invalid backed-up JSON.
  • Evidence: src/lib/state/sandbox.ts:949 returns backupContents when currentContents is absent; src/lib/state/sandbox.ts:957-962 catches merge/parse errors and restores the sanitized backup as-is. The PR body clause says it preserves runtime-owned gateway and generated managed channel/provider state, but that is only true on the successful merge path.

🔎 Worth checking

• Source-of-truth review needed: OpenClaw openclaw.json selective restore merge: The advisor marked localized patch analysis as needs_followup.
  • Recommendation: Identify the invalid state, source boundary, source-fix constraint, regression test, and removal condition before merging the localized behavior.
  • Evidence: src/lib/state/openclaw-config-merge.ts exports OPENCLAW_CONFIG_RESTORE_OWNERSHIP; agents/openclaw/manifest.yaml only declares openclaw.json as a durable state file.
• Source-of-truth review needed: Fallback to sanitized backup on current-read or JSON-parse failure: The advisor marked localized patch analysis as missing.
  • Recommendation: Identify the invalid state, source boundary, source-fix constraint, regression test, and removal condition before merging the localized behavior.
  • Evidence: src/lib/state/sandbox.ts:949 returns backupContents when currentContents is absent; src/lib/state/sandbox.ts:957-962 catches all merge/parse errors and returns backupContents.
• Keep the OpenClaw config ownership contract from drifting (src/lib/state/openclaw-config-merge.ts:14): The prior embedded policy has been extracted into OPENCLAW_CONFIG_RESTORE_OWNERSHIP, which is a substantial improvement, but the contract remains a hard-coded TypeScript list rather than a manifest/schema-backed ownership declaration. Provider/plugin behavior is also still broad: every current same-key entry wins, and if current models/plugins sections are absent the backup section is restored wholesale.
  • Recommendation: Either declare key-level ownership near the OpenClaw agent manifest/schema or document why this helper is the source of truth. Add tests for absent current models.providers/plugins.entries and same-key custom provider/plugin cases, and record the condition under which this restore workaround can be removed.
  • Evidence: agents/openclaw/manifest.yaml declares openclaw.json as a durable state file but does not declare key-level ownership. src/lib/state/openclaw-config-merge.ts:14-22 declares runtimeSections, managedChannels, currentGeneratedEntryMaps, and backupDurableSections in code.
• Add negative and runtime validation for the restore merge (test/snapshot.test.ts:1445): The added tests cover the successful merge path and one managed-channel omission case, but the highest-risk restore paths are not covered: SSH current-read failure, invalid current JSON, invalid backup JSON, absent provider/plugin sections, and actual sandbox rebuild/restore runtime behavior.
  • Recommendation: Add focused unit or fake-SSH tests for the failure and edge paths, plus targeted runtime/integration validation that a rebuilt OpenClaw sandbox remains usable after restore with gateway/proxy/diagnostics, managed channel placeholders, provider routing, MCP servers, and custom agents intact.
  • Evidence: src/lib/state/openclaw-config-merge.test.ts covers the main merge matrix and omitted managed channels. test/snapshot.test.ts covers a fake SSH happy path. No changed test exercises readCurrentStateFile() returning null or buildStateFileRestoreInput() catch fallback.
• Limit further growth in the sandbox state monolith (src/lib/state/sandbox.ts:889): This PR reduced the previous embedded merge logic by extracting the ownership helper, but src/lib/state/sandbox.ts still grows by 91 lines in an already-large sandbox lifecycle module. The added read/merge/fallback orchestration is security-sensitive restore code and will be hard to maintain if more agent-specific state-file behavior accumulates here.
  • Recommendation: Consider extracting the OpenClaw state-file restore input/read orchestration into a focused module beside openclaw-config-merge.ts, leaving sandbox.ts to select strategies and report restore success/failure.
  • Evidence: Deterministic monolith signal: src/lib/state/sandbox.ts grew from 1642 to 1733 lines (+91). New helpers include buildStateFileReadCommand(), readCurrentStateFile(), shouldMergeOpenClawConfig(), and buildStateFileRestoreInput().

🌱 Nice ideas

• None.

• **Runtime validation** — restoreSandboxState preserves rebuilt gateway/proxy/diagnostics or fails explicitly when current openclaw.json cannot be read. The changed behavior affects sandbox restore lifecycle and OpenClaw runtime configuration reconciliation. Unit/fake-SSH tests cover the happy path, but negative fallback paths and real sandbox runtime behavior need validation.
• **Runtime validation** — restoreSandboxState does not resurrect managed channels when current openclaw.json read exits nonzero. The changed behavior affects sandbox restore lifecycle and OpenClaw runtime configuration reconciliation. Unit/fake-SSH tests cover the happy path, but negative fallback paths and real sandbox runtime behavior need validation.
• **Runtime validation** — restoreSandboxState handles invalid current openclaw.json without clobbering fresh runtime-owned sections. The changed behavior affects sandbox restore lifecycle and OpenClaw runtime configuration reconciliation. Unit/fake-SSH tests cover the happy path, but negative fallback paths and real sandbox runtime behavior need validation.
• **Runtime validation** — restoreSandboxState handles invalid backed-up openclaw.json as a failed file instead of writing stale config. The changed behavior affects sandbox restore lifecycle and OpenClaw runtime configuration reconciliation. Unit/fake-SSH tests cover the happy path, but negative fallback paths and real sandbox runtime behavior need validation.
• **Runtime validation** — mergeOpenClawRestoredConfig documents and tests provider/plugin behavior when current models.providers or plugins.entries are absent. The changed behavior affects sandbox restore lifecycle and OpenClaw runtime configuration reconciliation. Unit/fake-SSH tests cover the happy path, but negative fallback paths and real sandbox runtime behavior need validation.
• **Add negative and runtime validation for the restore merge** — Add focused unit or fake-SSH tests for the failure and edge paths, plus targeted runtime/integration validation that a rebuilt OpenClaw sandbox remains usable after restore with gateway/proxy/diagnostics, managed channel placeholders, provider routing, MCP servers, and custom agents intact.
• **Acceptance clause:** Selectively merge restored OpenClaw openclaw.json instead of overwriting fresh rebuild-generated config — add test evidence or identify existing coverage. shouldMergeOpenClawConfig() gates OpenClaw openclaw.json and buildStateFileRestoreInput() calls mergeOpenClawRestoredConfig() on the normal path. However, current-read absence or JSON parse/merge failure restores the sanitized backup wholesale.
• **Acceptance clause:** Preserve runtime-owned gateway and generated managed channel/provider state from the rebuilt sandbox — add test evidence or identify existing coverage. OPENCLAW_CONFIG_RESTORE_OWNERSHIP lists gateway/proxy/diagnostics as runtime sections; managed channels are skipped from backup; current provider/plugin entries win by key. Tests assert gateway, Discord placeholder, WhatsApp state, Nvidia provider, and plugin behavior. The fallback path bypasses these guarantees.

Current findings:

• Source-of-truth review needed: OpenClaw openclaw.json selective restore merge: The advisor marked localized patch analysis as needs_followup.
  • Recommendation: Identify the invalid state, source boundary, source-fix constraint, regression test, and removal condition before merging the localized behavior.
  • Evidence: src/lib/state/openclaw-config-merge.ts exports OPENCLAW_CONFIG_RESTORE_OWNERSHIP; agents/openclaw/manifest.yaml only declares openclaw.json as a durable state file.
• Source-of-truth review needed: Fallback to sanitized backup on current-read or JSON-parse failure: The advisor marked localized patch analysis as missing.
  • Recommendation: Identify the invalid state, source boundary, source-fix constraint, regression test, and removal condition before merging the localized behavior.
  • Evidence: src/lib/state/sandbox.ts:949 returns backupContents when currentContents is absent; src/lib/state/sandbox.ts:957-962 catches all merge/parse errors and returns backupContents.
• Avoid wholesale backup fallback for OpenClaw runtime-owned config (src/lib/state/sandbox.ts:949): The new ownership contract only applies when the freshly rebuilt openclaw.json can be read and both configs parse. If the current read returns null or either JSON parse/merge throws, buildStateFileRestoreInput() restores backupContents as-is. That bypasses the PR's core guarantee to preserve rebuilt gateway/proxy/diagnostics and current managed channel/provider/plugin state, and can resurrect stale sanitized channel placeholders or delete fresh runtime auth/routing state.
  • Recommendation: For OpenClaw openclaw.json, make current-read/parse failures explicit restore failures, or implement a degraded path that never clobbers runtime-owned sections. Add regression tests for current read failure, missing current file, invalid current JSON, and invalid backed-up JSON.
  • Evidence: src/lib/state/sandbox.ts:949 returns backupContents when currentContents is absent; src/lib/state/sandbox.ts:957-962 catches merge/parse errors and restores the sanitized backup as-is. The PR body clause says it preserves runtime-owned gateway and generated managed channel/provider state, but that is only true on the successful merge path.
• Keep the OpenClaw config ownership contract from drifting (src/lib/state/openclaw-config-merge.ts:14): The prior embedded policy has been extracted into OPENCLAW_CONFIG_RESTORE_OWNERSHIP, which is a substantial improvement, but the contract remains a hard-coded TypeScript list rather than a manifest/schema-backed ownership declaration. Provider/plugin behavior is also still broad: every current same-key entry wins, and if current models/plugins sections are absent the backup section is restored wholesale.
  • Recommendation: Either declare key-level ownership near the OpenClaw agent manifest/schema or document why this helper is the source of truth. Add tests for absent current models.providers/plugins.entries and same-key custom provider/plugin cases, and record the condition under which this restore workaround can be removed.
  • Evidence: agents/openclaw/manifest.yaml declares openclaw.json as a durable state file but does not declare key-level ownership. src/lib/state/openclaw-config-merge.ts:14-22 declares runtimeSections, managedChannels, currentGeneratedEntryMaps, and backupDurableSections in code.
• Add negative and runtime validation for the restore merge (test/snapshot.test.ts:1445): The added tests cover the successful merge path and one managed-channel omission case, but the highest-risk restore paths are not covered: SSH current-read failure, invalid current JSON, invalid backup JSON, absent provider/plugin sections, and actual sandbox rebuild/restore runtime behavior.
  • Recommendation: Add focused unit or fake-SSH tests for the failure and edge paths, plus targeted runtime/integration validation that a rebuilt OpenClaw sandbox remains usable after restore with gateway/proxy/diagnostics, managed channel placeholders, provider routing, MCP servers, and custom agents intact.
  • Evidence: src/lib/state/openclaw-config-merge.test.ts covers the main merge matrix and omitted managed channels. test/snapshot.test.ts covers a fake SSH happy path. No changed test exercises readCurrentStateFile() returning null or buildStateFileRestoreInput() catch fallback.
• Limit further growth in the sandbox state monolith (src/lib/state/sandbox.ts:889): This PR reduced the previous embedded merge logic by extracting the ownership helper, but src/lib/state/sandbox.ts still grows by 91 lines in an already-large sandbox lifecycle module. The added read/merge/fallback orchestration is security-sensitive restore code and will be hard to maintain if more agent-specific state-file behavior accumulates here.
  • Recommendation: Consider extracting the OpenClaw state-file restore input/read orchestration into a focused module beside openclaw-config-merge.ts, leaving sandbox.ts to select strategies and report restore success/failure.
  • Evidence: Deterministic monolith signal: src/lib/state/sandbox.ts grew from 1642 to 1733 lines (+91). New helpers include buildStateFileReadCommand(), readCurrentStateFile(), shouldMergeOpenClawConfig(), and buildStateFileRestoreInput().