PR #70811: fix(plugins): defer undefined config validation in snapshot loads (Fixes #70658)

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

Description (problem / solution / changelog)

Summary

• Problem: non-activating plugin loads were validating entry?.config even when that preflight or CLI path had not materialized plugin config yet, which produced false-positive invalid config errors for otherwise healthy plugins.
• Why it matters: the error shows up in gateway.err.log and on CLI subcommands, which makes real plugin failures harder to spot and sends users debugging valid config.
• What changed: non-activating loads now skip schema validation when plugin config is still undefined, while real activation paths and non-activating loads with explicit config still validate as before. Added focused regression coverage for manifest-only snapshot loads and CLI metadata capture.
• What did NOT change (scope boundary): this does not relax validation for real plugin activation, change plugin config schemas, or alter plugin runtime behavior once config is actually present.

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 #70658
• Related #64946
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: the plugin loader always ran validatePluginConfig before checking whether the current load was a real activation or a metadata/preflight path. In those non-activating paths, some plugins can be discovered before plugins.entries.<id>.config exists, so AJV validated undefined as {} and reported missing required root fields.
• Missing detection / guardrail: there was no branch that treated undefined config as "not materialized yet" for snapshot and CLI metadata loads.
• Contributing context (if known): the same validator is reused across activation, snapshot, and CLI metadata paths, so the false positive only showed up when a non-activating path reached a strict plugin schema first.

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/plugins/loader.test.ts, src/plugins/loader.cli-metadata.test.ts
• Scenario the test should lock in: non-activating snapshot and CLI metadata loads should not fail plugin discovery when a strict config schema exists but plugin config is still undefined.
• Why this is the smallest reliable guardrail: the regression happens entirely inside loader branching, so focused loader tests exercise the real decision point without needing gateway or CLI end-to-end setup.
• Existing test that already covers this (if any): passes validated plugin config into non-activating CLI metadata loads already covers the explicit-config side of this branch.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

CLI preflight and metadata paths stop emitting false invalid config errors for plugins whose real runtime config is valid but has not been materialized in that path yet.

Diagram (if applicable)

Before:
[snapshot or CLI metadata load] -> [config is undefined] -> [AJV validates {}] -> [false invalid config error]

After:
[snapshot or CLI metadata load] -> [config is undefined] -> [defer validation] -> [plugin metadata loads cleanly]

Security Impact (required)

• New permissions/capabilities? (Yes/No) No
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) No
• Command/tool execution surface changed? (Yes/No) No
• Data access scope changed? (Yes/No) No
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: macOS
• Runtime/container: Node.js repo test runner
• Model/provider: N/A
• Integration/channel (if any): external plugins with strict top-level configSchema.required
• Relevant config (redacted): plugin allowed and discoverable, but non-activating load path does not provide plugins.entries.<id>.config

Steps

1. Install or discover a plugin whose manifest has a strict top-level required config field.
2. Trigger a non-activating plugin load path such as CLI metadata capture or a manifest-only snapshot while the plugin config for that path is still undefined.
3. Observe loader behavior before and after this change.

Expected

• Non-activating loads should defer validation until real config exists and should not emit a false invalid config error.

Actual

• Before this change, the loader validated undefined as an empty object and reported missing required properties.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

• Verified scenarios: ran node scripts/run-vitest.mjs run --config test/vitest/vitest.unit.config.ts src/plugins/loader.test.ts src/plugins/loader.cli-metadata.test.ts and confirmed the focused loader tests pass with the new regression coverage.
• Edge cases checked: explicit-config non-activating validation is still covered by the existing CLI metadata test; real activation still keeps validation because the guard only skips undefined config on non-activating loads.
• What you did not verify: I did not reproduce against a live external plugin package or run the full plugin test suite.

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/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: a non-activating path could now tolerate an undefined config for a plugin that would still fail once actually activated.
  • Mitigation: real activation paths still validate, and non-activating paths continue validating whenever explicit config is present.

Changed files

• src/plugins/loader.cli-metadata.test.ts (modified, +60/-0)
• src/plugins/loader.test.ts (modified, +104/-0)
• src/plugins/loader.ts (modified, +51/-20)