PR #68685: fix(config): strip obsolete memorySearch keys before schema validation (#68664)

• Repository: openclaw/openclaw
• Author: Tmalone1250
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/68685

Description (problem / solution / changelog)

Summary

• Problem: Obsolete memorySearch keys (chunkSize, chunkOverlap, maxResults) in agents.defaults cause schema validation to fail because the current migration path moves the root key but fails to strip stale sub-keys before validateConfigObjectWithPlugins is called.
• Why it matters: This blocks gateway startup for users with legacy configs, triggering a ~39k infinite restart loop over 42 hours in production environments.
• What changed: Implemented agents.defaults.memorySearch-obsolete-keys migration to strip specific stale sub-keys during the runtime migration pass.
• What did NOT change (scope boundary): Internal logic of memory search and per-agent overrides in agents.list remain untouched.

Change Type (select all)

• Bug fix
• Refactor required for the fix

Scope (select all touched areas)

• Gateway / orchestration
• API / contracts

Linked Issue/PR

• Closes #68664
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: The memorySearch sub-keys were deprecated/removed from the Zod schema, but the migration logic only performed a move operation on the top-level memorySearch key. If the keys were already present in agents.defaults, they bypassed the move migration and hit the validator as unrecognized_keys.
• Missing detection / guardrail: Config migration unit tests lacked coverage for partial/obsolete sub-key state within already-migrated root paths.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
• Target test or file: src/commands/doctor/shared/legacy-config-migrate.test.ts
• Scenario the test should lock in: Configs with agents.defaults.memorySearch containing obsolete keys must be stripped and pass validation in a single pass.
• Why this is the smallest reliable guardrail: Direct unit testing of the migration registry ensures the transformation logic is isolated from IO/Runtime state.

User-visible / Behavior Changes

None (internal config cleanup).

Diagram (if applicable)

Before:
[Load] -> [Move Migration (moves root only)] -> [Validation (Fails on sub-keys)] -> [Crash]

After:
[Load] -> [Move + Strip Migration] -> [Validation (Pass)] -> [Gateway Ready]

Security Impact (required)

• New permissions/capabilities? (No)
• Secrets/tokens handling changed? (No)
• New/changed network calls? (No)
• Command/tool execution surface changed? (No)
• Data access scope changed? (No)

Repro + Verification

Environment

• OS: Windows 11 (PowerShell 7)
• Runtime/container: Node.js v20.x
• Model/provider: N/A (Config layer)

Steps

1. Create config.json5 with agents: { defaults: { memorySearch: { chunkSize: 800 } } }.
2. Run openclaw gateway.
3. Observe InvalidConfigError: Unrecognized keys: "chunkSize".

Expected

Gateway initializes successfully after migrating keys.

Actual

Gateway crashes with schema validation error.

Evidence

• Trace/log snippets: test_results.log (3/3 repro tests passing).

Human Verification (required)

• Verified scenarios: Baseline strip, no-op on clean config, combined move+strip.
• Edge cases checked: Partial key presence (e.g., only maxResults present).
• What you did not verify: Upstream CI/CD integration.

Compatibility / Migration

• Backward compatible? (Yes)
• Config/env changes? (Yes - automatic cleanup)
• Migration needed? (Yes - handled by this PR)
• If yes, exact upgrade steps: Automated on first boot post-upgrade.

Risks and Mitigations

• Risk: Migration could theoretically strip valid keys if MEMORY_SEARCH_OBSOLETE_KEYS overlaps with future schema.
  • Mitigation: Keys are strictly scoped to the agents.defaults.memorySearch path. test_results.log

Changed files

• src/commands/doctor/shared/legacy-config-migrate.test.ts (modified, +106/-0)
• src/commands/doctor/shared/legacy-config-migrations.runtime.agents.ts (modified, +71/-0)