PR #80257: fix: prevent config data loss during version upgrade

• Repository: openclaw/openclaw
• Author: Jerry-Xin
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/80257

Description (problem / solution / changelog)

Summary

When upgrading from v2026.5.6 to v5.7+, the update-triggered doctor --fix run can destroy user-authored config fields in openclaw.json. Users report losing channel accounts, credentials, and plugin install records after upgrade.

Root Cause

Four interacting problems in the update-triggered doctor flow:

1. stripUnknownConfigKeys() runs before migration — The new version's stricter Zod schema (via .strict()) doesn't recognize plugins.installs (moved to a state file in v5.7). The strip function at doctor-config-analysis.ts:62 deletes it as "unknown" before ensureShippedPluginInstallConfigRecordsMigratedForWrite gets a chance to migrate it.

2. Doctor gets write privileges during update — update-command.ts:1606-1619 sets both OPENCLAW_UPDATE_IN_PROGRESS=1 and UPDATE_PARENT_SUPPORTS_DOCTOR_CONFIG_WRITE=1, bypassing the legacy skip guard at doctor-health-contributions.ts:57-67.

3. allowConfigSizeDrop: true disables safety net — doctor-health-contributions.ts:598 sets this when shouldWriteConfig is true, bypassing the >50% size-reduction rejection that would otherwise catch the data loss.

4. Backup rotation window too small — CONFIG_BACKUP_COUNT = 5 in backup-rotation.ts. During upgrade, doctor/channel-persist/restart may write config multiple times, rotating the good pre-upgrade .bak files out of the 5-slot ring before the user notices.

Fix

Four defense layers, each independently sufficient to prevent the reported data loss:

Layer 1: Pre-update persistent snapshot

# src/config/backup-rotation.ts — new function
+export async function createPreUpdateConfigSnapshot(params: {
+  configPath: string;
+  writeFile: ...; readFile: ...; existsSync: ...;
+}): Promise<void>

Creates .pre-update snapshot outside the .bak rotation ring before any update writes. Survives unlimited subsequent config writes. Best-effort (failure doesn't block update).

Called from update-command.ts before doctor invocation.

Layer 2: Skip strip during update (root cause)

# src/commands/doctor-config-analysis.ts
 export function stripUnknownConfigKeys(...) {
+  if (isUpdateInProgress()) {
+    return { cfg: params.cfg, removed: [], warnings: [] };
+  }

During upgrade, the new schema legitimately doesn't know about keys awaiting migration. Normal doctor --fix still cleans up after upgrade completes.

Layer 3: Disable allowConfigSizeDrop during update

# src/flows/doctor-health-contributions.ts
-allowConfigSizeDrop: ctx.configResult.shouldWriteConfig === true,
+allowConfigSizeDrop:
+  ctx.configResult.shouldWriteConfig === true &&
+  !isUpdateDoctorRun(ctx.env ?? process.env),

Even if something else unexpectedly shrinks config during update, the write is rejected rather than silently losing data.

Layer 4: Whitelist plugins.installs from strip

# src/commands/doctor-config-analysis.ts
+const STRIP_PROTECTED_KEYS: ReadonlyMap<string, ReadonlySet<string>> = new Map([
+  ["plugins", new Set(["installs"])],
+]);

plugins.installs is managed by the install-record migration system and should never be treated as unknown, even outside of update flows.

Tests

• config.backup-rotation.test.ts: 3 new tests — snapshot creation with correct permissions, survival through rotation cycles, no-op on missing config
• doctor-config-analysis.test.ts: 4 new tests — env guard (1 and true), normal stripping preserved, plugins.installs whitelist
• doctor-health-contributions.test.ts: 2 new tests — allowConfigSizeDrop disabled during update, enabled otherwise

All 4 test suites pass (49 total tests, 0 failures):

pnpm test src/config/config.backup-rotation.test.ts        # 7 pass
pnpm test src/commands/doctor-config-analysis.test.ts       # 7 pass
pnpm test src/flows/doctor-health-contributions.test.ts     # 11 pass
pnpm test src/cli/update-cli/update-command.test.ts         # 24 pass (existing, no regression)

Fixes #80077

Changed files

• src/cli/update-cli/update-command.ts (modified, +11/-0)
• src/commands/doctor-config-analysis.test.ts (modified, +68/-1)
• src/commands/doctor-config-analysis.ts (modified, +18/-0)
• src/config/backup-rotation.ts (modified, +33/-0)
• src/config/config.backup-rotation.test.ts (modified, +86/-0)
• src/flows/doctor-health-contributions.test.ts (modified, +85/-1)
• src/flows/doctor-health-contributions.ts (modified, +8/-1)