openclaw - 💡(How to fix) Fix [Bug]: agents.defaults.models aliases silently re-resolve target refs to openai/<alias-key> on 5.x

Summary

Hi! We hit a model-resolution issue on 5.x that took us three upgrade attempts to track down — agents.defaults.models alias entries silently re-resolve any direct use of their alias target to openai/<alias-key>. Config validates fine, and the resulting Unknown model: openai/<alias-key> error points at a model the user never configured, which made it hard to diagnose. One-line workaround works; sharing the repro in case it's worth fixing properly.

Reproduced on

• 2026.5.7, 2026.5.18, 2026.5.27 (stable). 2026.4.27 unaffected.
• Node 22.22.0, Linux x86_64.
• Custom provider nemotron-bolt (api: "openai-completions", self-hosted llama.cpp on macOS) plus built-in anthropic and two custom ollama-* providers. openclaw config validate passes on all three affected versions.

Minimal reproduction

{
  "agents": {
    "defaults": {
      "model": { "primary": "nemotron-bolt/nemotron-3-super-120b", "fallbacks": [] },
      "models": {
        "nemotron": { "alias": "nemotron-bolt/nemotron-3-super-120b" }
      }
    }
  },
  "models": {
    "providers": {
      "nemotron-bolt": {
        "baseUrl": "http://10.0.0.40:8080/v1",
        "apiKey": { "source": "env", "provider": "default", "id": "NEMOTRON_API_KEY" },
        "api": "openai-completions",
        "models": [{ "id": "nemotron-3-super-120b", "name": "Nemotron", "input": ["text"] }]
      }
    }
  }
}

Gateway startup journal on 5.27:

[gateway] agent model: openai/nemotron (thinking=medium, fast=off)
FailoverError: Unknown model: openai/nemotron
model-fallback/decision: requested=openai/nemotron candidate=openai/nemotron reason=model_not_found next=none

Expected: agent model: nemotron-bolt/nemotron-3-super-120b. The configured primary never reaches the runtime — it's re-resolved to openai/nemotron at startup.

It's general — any alias poisons its own target

Verified via an offline harness against resolveConfiguredModelRef (export v) in model-selection-shared-BuXkxoPc.js:

Looks like the resolver reverse-matches the primary to a configured alias by target, then re-resolves the alias key as a bare model name against DEFAULT_PROVIDER ("openai"). Forward use of the alias (primary: "nemotron") also does not resolve via this map on 5.x — it logs Model "nemotron" specified without provider. Falling back to "openai/nemotron" — so this schema location seems dead-for-forward-use while still actively poisoning direct uses of its targets.

Workaround

jq 'del(.agents.defaults.models)' openclaw.json > openclaw.json.new && mv openclaw.json.new openclaw.json
# restart gateway

Shipped this on our gateway and the collapse is gone — primary resolves correctly, no Unknown model errors.

Some directions you might consider

1. If agents.defaults.models[].alias is meant to be deprecated, a doctor --fix rewrite (or a validate-time warning) would help users find this.
2. If it's still supported as a forward alias, the reverse-matching probably shouldn't override a primary that's already a fully-qualified configured ref.
3. The error message could explain why a configured ref got rewritten (e.g., "matched alias 'nemotron' in agents.defaults.models"). Right now Unknown model: openai/<key> points at a model the user never configured, which is what made this hard to diagnose.

Happy to test patches — we have a stable repro and can turn things around quickly. Snapshots of failing/working configs and full journal evidence available if useful.

Thanks for OpenClaw!