openclaw - 💡(How to fix) Fix [Bug]: config accepts plugin/runtime/model edits that leave agent model refs unresolvable [1 comments, 2 participants]

Summary

OpenClaw 2026.5.18 accepts persisted config edits that can leave an agent with unresolvable or internally inconsistent model routing, without a config-save warning, reload warning, or doctor lint.

The concrete failure shape observed was an edit that simultaneously:

• changed agents.list[*].model.primary / fallbacks / heartbeat.model toward openai-codex/* model identifiers,
• changed runtime declarations for the original openai/* model keys to agentRuntime.id = "pi", and
• disabled/removed the codex plugin path in the same config edit.

Those edits are individually plausible, but jointly contradictory: the active model references and the runtime declarations no longer describe the same model keys, and plugin availability may no longer match model-resolution expectations. The gateway accepted the saved config silently. The next run/reload can fail later as a no-candidate / unresolvable-model problem instead of being caught at the point of config persistence or reload.

Expected behavior

OpenClaw should validate model references, runtime declarations, and plugin availability together before accepting or reloading a config.

At minimum, openclaw doctor should warn when:

1. agents.list[*].model.primary, fallbacks, heartbeat.model, or subagent model refs point at a model namespace/path that cannot be resolved with the currently enabled providers/plugins.
2. A config edit disables/removes a plugin while agent model refs still depend on that plugin/provider path.
3. agents.list[*].models[<modelId>].agentRuntime declarations exist only for model keys that are not referenced by the agent's model.primary, fallbacks, heartbeat model, or subagent model refs.
4. The inverse is true: referenced model IDs have no matching runtime policy declaration when the surrounding config appears to rely on explicit runtime selection.

Actual behavior

The config save/reload path accepted a contradictory edit without a visible validation warning. The broken state was only discovered by later runtime degradation / manual inspection.

Minimal synthetic reproduction

1. Run OpenClaw 2026.5.18 with an agent using normal OpenAI model refs, for example:

{
  "model": {
    "primary": "openai/gpt-5.5",
    "fallbacks": ["openai/gpt-5.3-codex"]
  },
  "heartbeat": {
    "model": "openai/gpt-5.4-mini"
  },
  "models": {
    "openai/gpt-5.5": {
      "agentRuntime": { "id": "codex" }
    },
    "openai/gpt-5.3-codex": {
      "agentRuntime": { "id": "codex" }
    }
  }
}

1. Apply a config edit that simultaneously:

• changes the primary/fallback/heartbeat model refs to openai-codex/*,
• changes the runtime declarations on the old openai/* keys to pi, and
• disables/removes the codex plugin path.

Example shape:

 "model": {
-  "primary": "openai/gpt-5.5",
-  "fallbacks": ["openai/gpt-5.3-codex"]
+  "primary": "openai-codex/gpt-5.5",
+  "fallbacks": ["openai-codex/gpt-5.3-codex"]
 },
 "heartbeat": {
-  "model": "openai/gpt-5.4-mini"
+  "model": "openai-codex/gpt-5.4-mini"
 },
 "models": {
   "openai/gpt-5.5": {
-    "agentRuntime": { "id": "codex" }
+    "agentRuntime": { "id": "pi" }
   },
   "openai/gpt-5.3-codex": {
-    "agentRuntime": { "id": "codex" }
+    "agentRuntime": { "id": "pi" }
   }
 }

And, in the same config edit:

 "plugins": {
   "allow": [
     "acpx",
     "anthropic",
-    "codex",
     "browser"
   ],
   "entries": {
+    "codex": {
+      "enabled": false
+    }
   }
 }

1. Save/reload/restart the gateway.

2. Observe that the config is accepted without a clear validation error, despite the agent's active model refs, runtime policy keys, and plugin availability being inconsistent.

Why this matters

This creates a silent path from a single bad config edit to a degraded or non-bootable normal lane. The bad edit may be made by a human, an agent, a migration, or a repair script. The current failure appears later, at model-resolution/runtime-dispatch time, where it is harder to diagnose and may look like a provider outage, session corruption, or runtime failure.

Suggested fix directions

Any of these would materially improve safety:

1. Config-save validation hook

   On every persisted openclaw.json write, check all model references under agent config (model.primary, fallbacks, heartbeat.model, subagent defaults, etc.) against the currently enabled providers/plugins and runtime policy declarations. Refuse the save or emit a structured warning if references are unresolvable or internally inconsistent.

2. openclaw doctor lint

   Add doctor checks for:

   • model refs whose namespace/provider path cannot resolve with the current enabled plugin/provider set,
   • disabled/removed plugins that still have active model refs elsewhere in config,
   • dead agentRuntime declarations attached to model keys no longer referenced by the agent,
   • referenced model IDs missing expected runtime declarations when the config uses explicit runtime routing.

3. Bootstrap/reload validation

   On gateway boot or hot reload, emit a hard warning like:

   [config] agent <id> primary model unresolvable: <model-id>

   Ideally surface this through status / doctor / configured admin notifications rather than letting the next embedded run fail with a generic no-candidate/provider-resolution error.

Notes

• This report intentionally uses a synthetic reproduction and redacted local context.
• Model identifiers such as openai/gpt-5.5, openai-codex/gpt-5.5, openai/gpt-5.3-codex, and openai-codex/gpt-5.3-codex are included because they are the relevant public config surface.
• The root problem is the missing cross-section validation, not the specific local edit that triggered it.