From cb9c927ca6cb6c079d8bad183326af91aafcbe52 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sat, 25 Apr 2026 04:18:02 +0100 Subject: [PATCH] docs: document config recovery policy --- docs/cli/config.md | 9 +++++++++ docs/gateway/configuration.md | 8 ++++++++ docs/gateway/troubleshooting.md | 3 +++ 3 files changed, 20 insertions(+) diff --git a/docs/cli/config.md b/docs/cli/config.md index 08569260377..ea9cc12831c 100644 --- a/docs/cli/config.md +++ b/docs/cli/config.md @@ -385,6 +385,15 @@ untrusted until they validate. Invalid direct edits can be restored from the last-known-good backup during startup or hot reload. See [Gateway troubleshooting](/gateway/troubleshooting#gateway-restored-last-known-good-config). +Whole-file recovery is reserved for globally broken config, such as parse +errors, root-level schema failures, legacy migration failures, or mixed plugin +and root failures. If validation fails only under `plugins.entries....`, +OpenClaw keeps the active `openclaw.json` in place and reports the plugin-local +issue instead of restoring `.last-good`. This prevents plugin schema changes or +`minHostVersion` skew from rolling back unrelated user settings such as models, +providers, auth profiles, channels, gateway exposure, tools, memory, browser, or +cron config. + ## Subcommands - `config file`: Print the active config file path (resolved from `OPENCLAW_CONFIG_PATH` or default location). The path should name a regular file, not a symlink. diff --git a/docs/gateway/configuration.md b/docs/gateway/configuration.md index 0146b9ca215..c2420168d5e 100644 --- a/docs/gateway/configuration.md +++ b/docs/gateway/configuration.md @@ -91,6 +91,10 @@ as `.clobbered.*`, restores the last-known-good copy, and logs the recovery reason. The next agent turn also receives a system-event warning so the main agent does not blindly rewrite the restored config. Promotion to last-known-good is skipped when a candidate contains redacted secret placeholders such as `***`. +When every validation issue is scoped to `plugins.entries....`, OpenClaw +does not perform whole-file recovery. It keeps the current config active and +surfaces the plugin-local failure so a plugin schema or host-version mismatch +cannot roll back unrelated user settings. ## Common tasks @@ -504,6 +508,10 @@ config writes use the same schema gate before writing; destructive clobbers such as dropping `gateway.mode` or shrinking the file by more than half are rejected and saved as `.rejected.*` for inspection. +Plugin-local validation failures are the exception: if all issues are under +`plugins.entries....`, reload keeps the current config and reports the plugin +issue instead of restoring `.last-good`. + If you see `Config auto-restored from last-known-good` or `config reload restored last-known-good config` in logs, inspect the matching `.clobbered.*` file next to `openclaw.json`, fix the rejected payload, then run diff --git a/docs/gateway/troubleshooting.md b/docs/gateway/troubleshooting.md index bc4132a3f5b..7aaf92fe18c 100644 --- a/docs/gateway/troubleshooting.md +++ b/docs/gateway/troubleshooting.md @@ -287,6 +287,9 @@ What happened: - OpenClaw preserved the rejected payload as `.clobbered.*`. - The active config was restored from the last validated last-known-good copy. - The next main-agent turn is warned not to blindly rewrite the rejected config. +- If all validation issues were under `plugins.entries....`, OpenClaw would + not restore the whole file. Plugin-local failures stay loud while unrelated + user settings remain in the active config. Inspect and repair: