Bug type

Regression (worked before, now fails) — config schema rejects a key the prior release wrote.

Summary

After upgrading from an earlier 2026.4.x release to 2026.4.24 via npm, every openclaw <subcmd> invocation fails with a config-validation error before the subcommand runs. The validator rejects agents.defaults.agentRuntime, a key whose shape didn't change but apparently isn't in the 2026.4.24 schema. There's no auto-migration; openclaw doctor --fix is also blocked because the validator gates it.

This is the same class as #70407 (dreaming.storage) and #60334 (agents.list[*].allowedModels / tools.exec.allowlist) — different field, same shape: schema diff between minor releases without a migration path on a hot path that gates all CLI commands.

Steps to reproduce

1. Have a working OpenClaw 2026.4.x install (this Mac was working on 2026.4.20 → 2026.4.23 over the past month) with agents.defaults.agentRuntime written to openclaw.json. The block looks like:

   "agents": {
     "defaults": {
       "model": "anthropic/claude-opus-4-7",
       "models": { /* ... */ },
       "compaction": { "mode": "safeguard" },
       "maxConcurrent": 4,
       "subagents": { "maxConcurrent": 8 },
       "agentRuntime": { "id": "claude-cli" }
     }
   }

2. npm install -g openclaw@latest (lands on 2026.4.24).

3. Run any CLI subcommand:

   $ openclaw plugins list
   Config invalid
   File: ~/.openclaw/openclaw.json
   Problem:
     - agents.defaults: Unrecognized key: "agentRuntime"
   
   Run: openclaw doctor --fix
   

4. Run the suggested repair:

   $ openclaw doctor --fix
   Config invalid
   File: ~/.openclaw/openclaw.json
   Problem:
     - agents.defaults: Unrecognized key: "agentRuntime"
   
   Run: openclaw doctor --fix
   

   doctor --fix itself goes through the validator gate, so the suggested workaround is unreachable.

Actual behavior

• openclaw plugins list / install / inspect, openclaw gateway status / restart, openclaw config get / set, openclaw doctor --fix — all exit with code 1 before doing anything.
• The gateway daemon (already running, started under launchd before the upgrade) keeps serving — only the operator-facing CLI is broken.
• Any plugin's diagnostic that shells out to openclaw <subcmd> (doctor scripts, install-local.sh, package install hooks) returns false negatives.

Expected behavior

• Either auto-migrate / soft-strip unknown keys with a deprecation warning, OR
• Surface a clear hint in the error: "agents.defaults.agentRuntime was renamed to in 2026.4.24; run openclaw doctor --fix to migrate" — and have doctor --fix exempt itself from the validator gate so it can actually do the migration, OR
• Fail soft on legacy keys at validation time (warn-and-continue) and only hard-fail on keys that affect runtime semantics this release.

The "validator runs before every CLI subcommand, including the repair tool" path is the load-bearing problem — it makes a tiny schema diff into a total CLI outage.

Workaround

Manually edit ~/.openclaw/openclaw.json and remove the agentRuntime block from agents.defaults. After that, the CLI works again — but the operator has to know to do this, the error message doesn't say which key to remove vs. which key to migrate, and the recovery requires a JSON editor rather than the tool the error message points at.

Environment

• OS: macOS 25.3 (Darwin 25.3.0)
• Node.js: v22 (via /opt/homebrew/opt/node@22)
• OpenClaw: v2026.4.24 (installed via npm install -g openclaw@latest)
• Channel: none (this install runs gateway + a plugin, no channel adapters)

Suggested fix

Two interlocking changes:

1. Make the unknown-key gate soft. When the validator hits a legacy key in agents.defaults, emit a warning and continue — don't reject the entire config. Hard-rejecting legacy values (wrong types, invalid enums) makes sense; rejecting unknown keys on a frequently-extended namespace converts every minor schema diff into a CLI outage.
2. Lift the validator off doctor --fix. The repair tool needs to be reachable when the config is already broken. Same applies to a future openclaw config strip-unknown style command.

Related

• Breaking config change in v2026.4.21: dreaming.storage schema migration breaks CLI on upgrade #70407 — same pattern in v2026.4.21, field dreaming.storage
• [Bug]: 2026.4.2 update rejects legacy config keys and cron jobs.json may require manual backup restore #60334 — same pattern in v2026.4.2, fields agents.list[*].allowedModels / tools.exec.allowlist
• Feature: openclaw doctor --config-diff for upgrade-safe config migration #38249 — feature request for openclaw doctor --config-diff for upgrade-safe migration

Offer

Happy to send a PR if a maintainer can point at where the schema-validation gate lives. My read is loader-NucjcOgv.js is one entry-point, but a diff of the validator-call sites is what'd actually scope the fix. Won't open a PR without an ack on the direction since this touches a hot-path config invariant.