openclaw - 💡(How to fix) Fix openclaw update silently reverts user-customised agents.defaults.model and plugins.entries blocks to dist defaults

Summary

openclaw update silently overwrites user-configured agents.defaults.model and plugins.entries.* blocks, reverting them to dist-shipped defaults. Manual migrations are silently undone. There is no warning during the update, no diff displayed, and no opt-in/opt-out flag — the user only discovers the revert later when their runtime starts failing.

Repro (this user has hit it twice in 11 days)

1. Migrate agents.defaults.model from API-key lane to OAuth lane, e.g.:

   {
     "agents": {
       "defaults": {
         "model": {
           "primary": "openai-codex/gpt-5.5",
           "fallbacks": ["openai-codex/gpt-5.4", "claude-cli/claude-sonnet-4-6", "openai-codex/gpt-5.4-mini"]
         }
       }
     }
   }

2. Run openclaw update to take a later dist version (in this case 2026.5.7 → 2026.5.19).
3. Inspect openclaw.json post-update. The migrated values are gone; the file contains the dist's default API-key lane references (openai/gpt-5.5, openai/gpt-5.4, etc.) again.

Additionally:

• Newly-introduced plugins (e.g. lossless-claw in 2026.5.19) ship config defaults pointing at openai/... model strings, so any new plugin block also has to be re-migrated.
• Per-agent overrides in agents.list[*].model.primary are likewise rewritten.

Observed sequence on this install

• 2026-05-10: Migrated all openai/* references to openai-codex/*. Removed all API keys. Verified end-to-end: smoke test "OAuth working" via main agent.
• ~2026-05-13 to ~2026-05-19: openclaw update runs took the install to 2026.5.19.
• 2026-05-21: First message in days landed in a routine cron path → FailoverError: No API key found for provider "openai-codex" with requestedProvider: "openai" (the API-key lane, not the OAuth lane). Inspection showed all migrated values reverted.

Why this is a real problem (not just a hygiene gripe)

The user has explicitly removed their API keys to enforce an OAuth-only architecture. After update, the runtime then routes to providers that have no auth at all — every cron, heartbeat, and chat invocation that goes through the front door fails until the user manually re-migrates. The user only discovers it via Slack/WhatsApp failure messages, sometimes hours or days after the revert.

In essence: an apparently safe openclaw update introduces silent regressions to authentication paths.

Workaround in use

A self-healing config overlay file (~/.openclaw/workspace/config/oauth-lane-overlay.json5) is re-applied daily via the Daily Maintenance cron using openclaw config patch --file <overlay>. Since config patch is idempotent, this restores the migration within 24h of any revert. But it shouldn't be necessary.

Suggested fix

Three options, in increasing degree of intervention:

1. Preserve user-customised model blocks. If agents.defaults.model.primary or agents.defaults.model.fallbacks differs from the dist's default before the update, do not overwrite it during update. Detect "user-customised" by comparing pre-update file content to what the prior dist version's default would have been.

2. Display the diff during update. Run a dry-run config-rewrite, show the user a coloured diff of what would change, ask for confirmation before applying.

3. Add a --preserve-config flag (or its inverse, --reset-config) so the user can opt in/out of the dist-defaults-rewrite behaviour. Default to preserve.

Option 1 is the right long-term answer. Option 2 is a good interim safeguard. Option 3 is the minimum-viable escape hatch.

Environment

• Affected: 2026.5.7 → 2026.5.12 → 2026.5.19 update path on macOS
• Auth flavour: OpenAI Codex OAuth (ChatGPT subscription) + Claude-CLI OAuth (Claude subscription)
• LaunchAgent: ai.openclaw.gateway with KeepAlive=true

Related

• Prior upstream filings from this install: paperclipai/paperclip#5561, openclaw/openclaw#77458, openclaw/openclaw#82358
• Pair-bug for the same install: separately-filed lightContext: true excludes exec from main-agent isolated cron sessions even with toolsAllow: ['exec'] set explicitly.