Problem

After upgrading OpenClaw across minor versions, community-recommended config patterns silently become invalid — they don't crash the gateway, but they don't work either. The user has no way to know which config keys from a previous version are still supported, which are renamed, and which are removed.

Real-world example

I upgraded from 2026.2.25 → 2026.3.2. Based on GitHub issues and community discussions, I applied these "recommended" optimizations:

"compaction": { "mode": "aggressive", "threshold": 0.70, "targetTokens": 30000 },
"session": { "reset": { "idleMinutes": 120 }, "maintenance": { "mode": "enforce", "maxEntries": 800 } }

Result:

• compaction.mode only accepts default or safeguard in 2026.3.2 — aggressive was silently ignored
• compaction.threshold and targetTokens are not recognized fields — silently ignored
• The entire agents.defaults.session block is not in the schema — silently ignored
• heartbeat.every: "0m" — flagged as invalid duration at runtime but accepted in the JSON file

The config file was valid JSON, openclaw config validate passed (it only checks JSON syntax + known keys), but the intended optimizations were never applied. The system ran with default compaction while I believed it was running aggressive compaction — leading to continued context bloat that I spent hours debugging.

Why config validate isn't enough

config validate confirms the file is parseable and known keys have valid types. It does not:

• Warn about keys that exist in the file but aren't in the current schema
• Show what changed between the version that last touched the config and the current version
• Suggest migration paths for deprecated or renamed keys

Proposal

Add a --config-diff flag to openclaw doctor:

openclaw doctor --config-diff

Output:

Config Schema Diff: 2026.2.25 → 2026.3.2
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

⚠️  Unrecognized keys (3 found):
  agents.defaults.compaction.threshold    — not in 2026.3.2 schema
  agents.defaults.compaction.targetTokens — not in 2026.3.2 schema
  agents.defaults.session                 — not in 2026.3.2 schema (entire block)

⚠️  Invalid enum values (1 found):
  agents.defaults.compaction.mode = "aggressive"
    Valid values: "default", "safeguard"

ℹ️  New keys available in 2026.3.2 (not in your config):
  agents.defaults.bootstrapMaxChars       — limits per-file workspace injection (recommended)
  agents.defaults.bootstrapTotalMaxChars  — limits total workspace injection

💡 Migration suggestions:
  • compaction.mode "aggressive" → use "safeguard" (aggressive not yet implemented, see #7477)
  • session management → use cron-based session reset instead (see docs)

Run `openclaw doctor --config-diff --fix` to auto-apply safe migrations.

Why this matters for the community:

1. Config advice drifts faster than docs. GitHub issues, Reddit posts, and Discord tips reference config keys from specific versions. Users copy-paste these without knowing they may not apply to their version. This is the fix: add @lid format support and allowFrom wildcard handling #1 source of "my optimization didn't work" confusion.

2. Upgrades are silent. Unlike npm (which shows breaking changes) or Docker (which warns about deprecated flags), OpenClaw upgrades don't surface config incompatibilities. The gateway starts fine, the config looks fine, but the behavior isn't what the user intended.

3. Complements Feature Request: Configuration Validation on Startup #32906. Issue Feature Request: Configuration Validation on Startup #32906 proposes startup validation. This proposal goes further by providing actionable migration guidance — not just "this key is bad" but "here's what to use instead and why."

4. Reduces support burden. A significant portion of "my agent is slow / expensive / broken after upgrade" reports likely stem from stale config. A self-service migration tool would prevent these.

Implementation sketch

• Store schema snapshots per version in schemas/ (already partially exists for config validate)
• doctor --config-diff compares meta.lastTouchedVersion schema against current version schema
• Diff output categorized: removed keys, renamed keys, new keys, changed enum values
• --fix flag applies safe auto-migrations (enum corrections, key renames) with backup

Environment

• OpenClaw 2026.3.2, macOS
• Upgraded from 2026.2.25 (config last valid at that version)