PR #73257: fix(config): guard legacy agentRuntime regression

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

Description (problem / solution / changelog)

Summary

Describe the problem and fix in 2–5 bullets:

• Problem: users upgrading to 2026.4.24 reported Config invalid on agents.defaults.agentRuntime, which could block CLI workflows including the suggested doctor --fix recovery path.
• Why it matters: config-schema regressions on startup paths can turn minor upgrades into CLI outages and break operational recovery.
• What changed: added targeted regression tests to lock two guarantees — agents.defaults.agentRuntime is accepted by schema validation, and config guard allowlisted commands (including doctor fix) do not hard-exit on invalid snapshots while still surfacing diagnostics.
• What did NOT change (scope boundary): no runtime config parser behavior was changed in this PR; this is guardrail coverage only.

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

Root Cause (if applicable)

• Root cause: a prior release path reportedly rejected a legacy/expected config key during startup validation, and that class of regression can evade detection when coverage does not assert both schema acceptance and allowlisted command behavior.
• Missing detection / guardrail: no focused regression tests were locking agents.defaults.agentRuntime acceptance + doctor fix allowlist behavior in the config guard test path.
• Contributing context (if known): repeated regressions in neighboring config keys show this startup validation surface is high-impact and needs explicit test locks.

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/zod-schema.agent-defaults.test.ts
  • src/cli/program/config-guard.test.ts
• Scenario the test should lock in:
  • schema accepts agents.defaults.agentRuntime values
  • invalid snapshot mentioning Unrecognized key: "agentRuntime" does not hard-exit allowlisted commands, including doctor fix, while still printing diagnostics.
• Why this is the smallest reliable guardrail: both checks run in fast unit suites and directly cover the two failure surfaces (schema acceptance and startup guard behavior) without introducing broader integration harness cost.
• Existing test that already covers this (if any): existing config-guard allowlist tests partially covered non-exit behavior; this PR adds the agentRuntime-specific assertion.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

None (test-only guardrail additions).

Diagram (if applicable)

N/A

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:

Repro + Verification

Environment

• OS: Linux (dev harness)
• Runtime/container: local Node + pnpm worktree
• Model/provider: N/A
• Integration/channel (if any): N/A
• Relevant config (redacted): synthetic invalid snapshot in test (agents.defaults → Unrecognized key: "agentRuntime")

Steps

1. Run pnpm test -- src/config/zod-schema.agent-defaults.test.ts src/cli/program/config-guard.test.ts
2. Run pnpm check:changed
3. Confirm both pass with updated assertions.

Expected

• Schema test accepts agents.defaults.agentRuntime.
• Config-guard allowlist test verifies doctor fix does not hard-exit and still emits key diagnostics.

Actual

• Both expectations pass.

Evidence

Attach at least one:

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

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios:
  • targeted tests pass for schema + config guard paths
  • pnpm check:changed passes after updates
• Edge cases checked:
  • allowlisted command path includes explicit doctor fix check for non-exit
• What you did not verify:
  • full cross-version upgrade flow on affected macOS host
  • packaged npm global install reproduction end-to-end

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.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps:

Risks and Mitigations

• Risk: this PR is test-only; if runtime behavior regresses in a new path, these tests may not catch every variant.
  • Mitigation: tests target the two highest-signal contracts for this incident class (schema acceptance + config-guard allowlist behavior), and can be extended if new repro details emerge.

Changed files

• src/cli/program/config-guard.test.ts (modified, +11/-3)
• src/config/zod-schema.agent-defaults.test.ts (modified, +11/-0)