PR #61856: fix(config): restore applyDefaults:true for AJV plugin/channel schema validation

• Repository: openclaw/openclaw
• Author: SuperMarioYL
• State: closed | merged: True
• Link: https://github.com/openclaw/openclaw/pull/61856

Description (problem / solution / changelog)

Summary

• Problem: openclaw plugins install crashes with validateConfigObjectRawWithPlugins on a fresh v2026.4.5 install. AJV plugin/channel schema validation rejects configs that rely on default values for required fields when applyDefaults is false.
• Why it matters: This is a regression from v2026.4.2 → v2026.4.5 that completely blocks plugin installation on fresh systems. Any third-party plugin with a configSchema containing required-but-defaulted fields fails.
• What changed: Restored applyDefaults: true for the AJV validateJsonSchemaValue calls in validateConfigObjectWithPluginsBase (both channel and plugin schema validation paths). This was the pre-4.5 behavior.
• What did NOT change (scope boundary): The outer Zod validation's applyDefaults flag remains caller-controlled. The persistCandidate write-path mechanism (which prevents AJV-injected defaults from being written to disk) is untouched.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #61841
• Related #56772 (the original issue that motivated the persistCandidate mechanism)
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: Commits 40ffada812 and 97878b853a changed applyDefaults: true to applyDefaults: opts.applyDefaults in the AJV validateJsonSchemaValue calls for both channel and plugin config schemas. When writeConfigFile → validateConfigObjectRawWithPlugins calls validation with applyDefaults: false, AJV no longer injects schema defaults before checking required constraints. Any plugin whose configSchema has required fields with default values (e.g., the opik plugin) fails validation on a fresh install where no explicit config exists yet.
• Missing detection / guardrail: No test existed for the scenario of validating a fresh/empty plugin config entry against a schema with required-but-defaulted fields.
• Contributing context: The refactor to move legacy config migration behind doctor correctly avoided persisting AJV defaults to disk, but the validation-gating path was inadvertently tightened. The existing persistCandidate mechanism (documented at src/config/io.ts:2148-2154) already prevents AJV defaults from leaking into the persisted config, so applyDefaults: true during validation is safe.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/config/validation.channel-metadata.test.ts or a new src/config/validation.plugin-defaults.test.ts
• Scenario the test should lock in: Validate a config with an enabled plugin whose configSchema has a required field with a default value, where the plugin entry has no explicit config key (i.e., entry?.config ?? {}). Validation should pass.
• Why this is the smallest reliable guardrail: Directly exercises the AJV validation path with the exact edge case that caused the crash.
• If no new test is added, why not: The existing test infrastructure requires bundled plugin manifests to be discoverable, which fails in the current local test environment (pre-existing loadPluginManifestRegistry error unrelated to this change). A test can be added once the test environment issue is resolved.

User-visible / Behavior Changes

• openclaw plugins install no longer crashes on fresh installs (v2026.4.5 regression).
• No other behavior changes; validated configs are still not persisted with AJV-injected defaults.

Diagram (if applicable)

Before (v2026.4.5):
[fresh install] -> [plugins install] -> [validateConfigObjectRawWithPlugins(applyDefaults:false)]
  -> [AJV rejects {} for required fields] -> CRASH

After (this fix):
[fresh install] -> [plugins install] -> [validateConfigObjectRawWithPlugins(applyDefaults:false)]
  -> [AJV validates with defaults applied] -> [persistCandidate written without defaults] -> SUCCESS

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: Any (reproduced with Docker per issue)
• Runtime/container: Node 22+, fresh install
• Model/provider: N/A
• Integration/channel (if any): N/A
• Relevant config (redacted): Fresh install with no existing ~/.openclaw/config.yaml

Steps

1. Fresh install openclaw v2026.4.5 (e.g., via Docker as described in #61841)
2. Run openclaw plugins install <any-plugin-with-defaulted-required-config>
3. Observe crash at validateConfigObjectRawWithPlugins

Expected

• Plugin installs successfully

Actual

• Crashes with validation error on required fields that have schema defaults

Evidence

• Trace/log snippets (see issue #61841 for full stack trace and Dockerfile repro)
• Code analysis: git log --oneline confirms regression commits, src/config/io.ts:2148-2154 documents the persistCandidate safety mechanism

Human Verification (required)

• Verified scenarios: Code review of the regression commits (40ffada812, 97878b853a), confirmed that persistCandidate mechanism at io.ts:2148-2154 prevents AJV defaults from being persisted, verified the diff is a minimal 2-line revert to pre-regression behavior.
• Edge cases checked: Verified that the Zod outer validation applyDefaults flag is NOT affected by this change. Confirmed channel schema path has the same issue and fix.
• What you did not verify: Full Docker-based end-to-end reproduction (requires Docker environment); the local test suite has a pre-existing environment issue with loadPluginManifestRegistry.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No

Risks and Mitigations

• Risk: AJV defaults could theoretically leak into persisted config if the persistCandidate mechanism is bypassed.
  • Mitigation: persistCandidate is well-documented and tested (issue #56772). This fix restores the exact behavior from v2026.4.2, which worked correctly with persistCandidate.

Changed files

• CHANGELOG.md (modified, +2/-0)
• src/config/validation.channel-metadata.test.ts (modified, +58/-0)
• src/config/validation.ts (modified, +4/-2)