Description

Gateway fails to start after upgrading from v2026.3.2 to v2026.3.3 due to config schema mismatch. Keys that were valid in v2026.3.2 (autoApproveDevices, requirePairing) are rejected as invalid in v2026.3.3, causing 18+ hours of downtime.

Environment

• OpenClaw versions: 2026.3.2 → 2026.3.3
• Platform: macOS (Darwin 25.3.0)
• Gateway mode: local, bind=lan
• Affected services: Discord bot, Telegram bot, node connections

Timeline of Events

1. March 3, 22:39 - Running v2026.3.2, config normal
2. March 4, 08:11 - Auto-update to v2026.3.2, lastTouchedVersion updated
3. March 4, 23:30 - Config reload attempted, validation failure detected

   gateway.controlUi: Unrecognized keys: "autoApproveDevices", "requirePairing"
   

4. March 5, 00:00 - Gateway restart triggered (automatic/scheduled)
5. March 5, 00:00-18:40 - Gateway repeatedly fails to start (config validation error)
6. March 5, 18:40 - Manual intervention: removed invalid keys, gateway started successfully

Error Messages

From logs (/tmp/openclaw/openclaw-2026-03-05.log):

{
  "0": "  - gateway.controlUi: Unrecognized keys: \"autoApproveDevices\", \"requirePairing\"",
  "_meta": {
    "logLevelName": "ERROR",
    "date": "2026-03-04T15:00:00.666Z"
  },
  "time": "2026-03-05T00:00:00.666+09:00"
}

This error repeated continuously from 00:00 to 18:40 (18 hours 40 minutes).

Config Section Affected

{
  "gateway": {
    "controlUi": {
      "allowedOrigins": [...],
      "autoApproveDevices": true,    // ← Invalid in v2026.3.3
      "requirePairing": false         // ← Invalid in v2026.3.3
    }
  }
}

Impact

• Gateway: Unable to start for 18+ hours
• Discord bot: Offline during entire period
• Telegram bot: Offline during entire period
• Connected nodes: Unable to connect or communicate
• User experience: Complete service outage

Root Cause Analysis

1. v2026.3.2 added autoApproveDevices and requirePairing to config schema
2. v2026.3.3 removed or deprecated these keys without migration
3. Config file retained v2026.3.2 keys after update
4. Gateway startup validation rejects these keys in v2026.3.3
5. No automatic config migration or cleanup occurred

Expected Behavior

One of the following should happen during version upgrades:

1. Automatic migration: Remove deprecated keys from config
2. Graceful deprecation: Warn about invalid keys but continue startup
3. Migration script: Provide openclaw config migrate command
4. Clear documentation: Breaking changes in release notes with migration guide

Actual Behavior

• Gateway silently fails to start
• Only error is buried in logs
• No user notification or recovery guidance
• Manual intervention required to identify and fix issue

Workaround

Manually edit ~/.openclaw/openclaw.json and remove the invalid keys:

# Remove these lines from gateway.controlUi section:
"autoApproveDevices": true,
"requirePairing": false

Then restart gateway:

openclaw gateway restart

Suggested Fixes

Short-term (patch release)

1. Add config migration for v2026.3.2 → v2026.3.3 transition
2. Document breaking changes in release notes
3. Add startup warning when unknown keys are detected (instead of hard failure)

Long-term

1. Implement config schema versioning
2. Automatic migration system for config updates
3. Validate config on save (in Control UI) to prevent invalid keys from being written
4. Better error messages pointing to specific config issues and solutions
5. openclaw config validate command to check config before restart

Additional Context

• Config metadata shows lastTouchedVersion: "2026.3.2" but running v2026.3.3
• Gateway has hot-reload functionality but validation prevents it from working
• No backup config system to automatically rollback on failure
• Logs show repeated startup attempts but no clear indication of how to fix

Related

• Issue bug: existing bind=lan installs crash-loop after upgrade to v2026.2.26 (missing controlUi.allowedOrigins migration) #29385 (mentioned in logs regarding allowedOrigins seeding)

This issue caused significant downtime and could be prevented with better config migration handling. Happy to provide more details or test fixes.