🐛 Bug: Config Migration Order Causes Service Failure on Schema Changes

📋 Summary

OpenClaw's configuration validation fails before legacy migrations can run, causing service crashes when configuration schema changes between versions. The service attempted to restart 39,231 times over 42 hours before manual intervention.

🚨 Impact

• Service downtime: 42 hours (17/04/2026 00:00 - 18/04/2026 18:07)
• Failed restarts: 39,231 attempts
• CPU waste: ~3.5 seconds per failed attempt
• User impact: Complete service unavailability

🔍 Root Cause Analysis

The Problem:
When OpenClaw's configuration schema changes (e.g., removing deprecated keys from memorySearch), the current flow is:

// CURRENT (BROKEN) FLOW:
1. Validate config → ❌ ERROR: "Unrecognized keys: chunkSize, chunkOverlap, maxResults"
2. Apply migrations → 🚫 NEVER EXECUTES (validation fails first)
3. Service crashes → 🔄 Restart loop begins

The Code:
OpenClaw DOES have a migration system (applyLegacyMigrations in io-CHHRUM9X.js), but it's called AFTER validation in config-guard-BVU7K-aq.js.

Specific Migration That Should Have Run:
There's a migration for memorySearch in io-CHHRUM9X.js, but it doesn't remove obsolete keys (chunkSize, chunkOverlap, maxResults) from the legacy object before validation.

📊 Evidence from Production

Error Logs:

Config invalid
File: ~/.openclaw/openclaw.json
Problem:
  - agents.defaults.memorySearch: Unrecognized keys: "chunkSize", "chunkOverlap", "maxResults"
Run: openclaw doctor --fix

Configuration Before/After:

// Before (obsolete):
"memorySearch": {
  "enabled": true,
  "chunkSize": 800,        // ❌ No longer recognized
  "chunkOverlap": 100,     // ❌ No longer recognized  
  "maxResults": 5          // ❌ No longer recognized
}

// After (`openclaw doctor --fix`):
"memorySearch": {
  "enabled": true          // ✅ Only valid key remains
}

🛠️ Proposed Solution

1. Fix the Order (Primary Solution):
Change the validation flow to apply migrations BEFORE validation in config-guard-BVU7K-aq.js.

2. Enhance Migration Logic (Secondary):
Update the memorySearch migration to also remove obsolete keys.

3. Automatic Migration on Update:
Add migration execution to the openclaw update command.

🚀 Implementation Steps

1. Priority: High - Fix validation order in config-guard-BVU7K-aq.js
2. Priority: Medium - Add cleanup migrations for common obsolete keys
3. Priority: Low - Add migration logging for debugging
4. Priority: Low - Integrate doctor --fix into update process

🔧 Workaround for Users

Until fixed, users must manually run after updates:

openclaw doctor --fix
systemctl --user restart openclaw-gateway

🎯 Related Files

• /usr/lib/node_modules/openclaw/dist/config-guard-BVU7K-aq.js - Validation logic
• /usr/lib/node_modules/openclaw/dist/io-CHHRUM9X.js - Migration logic
• /usr/lib/node_modules/openclaw/dist/legacy.shared-i8CHhuVb.js - Migration utilities

📈 Severity Assessment

• Impact: Critical (service completely unavailable)
• Frequency: High (affects all users with config changes)
• Fix complexity: Low (simple order change)
• Risk of fix: Low (migrations already exist, just order change)