From c44367f1e55a38feb64e553e0ddb4c746ff0bd74 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Mon, 25 May 2026 08:20:36 +0100 Subject: [PATCH] docs: clarify config migration policy --- AGENTS.md | 2 +- VISION.md | 9 +++++++++ 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index e15ee240d994..ea1a8928aeaa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -56,7 +56,7 @@ Skills own workflows; root owns hard policy and routing. - Internal bundled plugins ship in core dist; bundled-only facade loader ok only for them. - External official plugins own package/deps and are excluded from core dist; core uses registry-aware `facade-runtime` or generic contracts. - Externalizing a bundled plugin: update package excludes, official catalogs, docs, tests, and prove core runtime paths resolve installed plugin roots before root-dep removal. -- Legacy config repair belongs in `openclaw doctor --fix`, not startup/load-time core migrations. Runtime paths use canonical contracts. +- Runtime reads canonical config only. No silent compat for old/malformed config keys. If a config change invalidates existing files, add a matching `openclaw doctor --fix` migration. Core/auth config repairs live in core doctor; plugin-owned config repairs live in that plugin's doctor contract (`legacyConfigRules` / `normalizeCompatibilityConfig`). - Fix shape: default to clean bounded refactor, not smallest patch. Move ownership to right boundary; delete stale abstractions, duplicate policy, dead branches, wrappers, fallback stacks. - Lean code is a goal. No internal shims, aliases, legacy names, broad fallbacks, or defensive branches just to reduce diff or handle unrealistic edge cases. - Handle real production states, shipped upgrade paths, security boundaries, and dependency contracts. Public/hostile/observed malformed input gets care; hypothetical malformed input does not. diff --git a/VISION.md b/VISION.md index 2d310a54c065..61ebf6b8dbca 100644 --- a/VISION.md +++ b/VISION.md @@ -38,6 +38,15 @@ Contribution rules: - Do not open large batches of tiny PRs at once; each PR has review cost. - For very small related fixes, grouping into one focused PR is encouraged. +Configuration compatibility: + +OpenClaw runtime code reads the current configuration schema only. +We do not keep long-lived aliases or compatibility branches that silently accept old, renamed, or malformed config keys. + +When a config change makes existing user config invalid, the same change needs a doctor migration. +`openclaw doctor --fix` should detect the old shape, explain it, back it up when needed, and rewrite it to the canonical format. +Core-owned config and auth state are repaired in core doctor code; plugin-owned config is repaired by that plugin's doctor contract. + ## Security Security in OpenClaw is a deliberate tradeoff: strong defaults without killing capability.