PR #65766: fix(config): auto-heal unrecognized keys during config load to prevent gateway crash

• Repository: openclaw/openclaw
• Author: openperf
• State: closed | merged: False
• Link: https://github.com/openclaw/openclaw/pull/65766

Description (problem / solution / changelog)

fix(config): auto-heal unrecognized keys during config load to prevent gateway crash

Summary

• Problem: When an Agent (or external tool) modifies ~/.openclaw/openclaw.json directly via the filesystem and injects invalid fields into strict objects (e.g., writing vars into env.shellEnv), the gateway crashes on startup with a "Config invalid" error. This is a Beta release blocker (Issue #65721) because it requires manual intervention (openclaw doctor --fix) to recover.
• Root Cause: loadConfig and readConfigFileSnapshotInternal use OpenClawSchema.safeParse() which correctly rejects unrecognized_keys in .strict() objects. However, the failure path immediately throws or returns invalid, offering no fault tolerance for stray keys injected by agents.
• Fix: Introduced a self-healing mechanism (applyUnrecognizedKeyRecovery) in the validation failure path. If the only validation errors are unrecognized_keys, it precisely strips those keys from the raw config and re-validates. If successful, the gateway starts normally and logs an error-level diagnostic prompting the user to run openclaw doctor --fix to persist the cleanup.
• What changed:
  • src/config/validation.ts: Added tryRecoverUnrecognizedKeys and applyUnrecognizedKeyRecovery to handle the stripping and re-validation logic.
  • src/config/validation.ts: Updated stripUnrecognizedKeysFromConfig to support array index traversal and added isBlockedObjectKey protection against prototype tampering (CWE-1321).
  • src/config/io.ts: Replaced immediate failure in loadConfig and readConfigFileSnapshotInternal with calls to applyUnrecognizedKeyRecovery.
  • src/config/config.unrecognized-key-recovery.test.ts: Added comprehensive regression tests for the recovery logic, namespace restrictions, and size guards.
• What did NOT change (scope boundary):
  • The Zod schemas themselves were not relaxed; .strict() remains intact.
  • The on-disk config file is not mutated automatically; the healed config is in-memory only.
  • Non-unrecognized_keys errors (e.g., type mismatches) still cause immediate fail-closed crashes.

Reproduction

1. Start the gateway with a valid config.
2. Manually edit ~/.openclaw/openclaw.json and add "vars": { "PATH": "/usr/bin" } inside env.shellEnv.
3. Restart the gateway.
4. Before: Gateway crashes with "Config invalid".
5. After: Gateway starts successfully, logs an error about the stripped key, and ignores the invalid field.

Risk / Mitigation

• Risk: CWE-693 (Fail-open) - Auto-healing might silently strip security-relevant keys if a user downgrades to an older version where those keys are unrecognized.
• Mitigation:
  1. Added allowedTopLevelKeys: ["agents", "meta", "env"] to restrict healing to specific namespaces. Security/gateway configs will still fail-closed.
  2. Healing logs at error level to ensure visibility.
  3. Path comparison is segment-wise to prevent dot-in-key bypasses (CWE-284).
• Risk: CWE-400 (DoS) - Expensive structuredClone and re-validation on massive config files.
• Mitigation: Added rawFileSize check. Healing is skipped if the config exceeds 2 MiB.
• Risk: Silent coercion of union types (e.g., ACP bindings).
• Mitigation: Removed invalid_union traversal entirely. The core issue (env.shellEnv.vars) does not involve unions, so we strictly avoid union-aware recovery to prevent unintended structural changes.

Change Type (select all)

• Bug fix

Scope (select all touched areas)

• Gateway
• Config
• Validation

Changed files

• src/config/config.unrecognized-key-recovery.test.ts (added, +197/-0)
• src/config/io.ts (modified, +31/-2)
• src/config/validation.ts (modified, +279/-0)