Summary

OpenClaw already has the core pieces for forward-compat model support:

• models.providers.<provider>.models can inject model definitions from config
• runtime can resolve some newer models via forward-compat fallbacks
• models status can often resolve models that are not yet present in the underlying pi-ai registry

The gap is that this still behaves like a partial capability rather than a first-class system concept.

This RFC proposes that config-injected provider models should be treated as first-class forward-compat models across the whole product, not only in isolated code paths.

Why this matters

This is not just about one model.

It is a recurring class of issue whenever:

• a provider releases a new model before OpenClaw updates ship
• upstream runtime support lands on main before stable packages include it
• users need a safe local bridge instead of waiting for the next release

In practice, models.providers is already the natural escape hatch for this. The problem is that support is currently uneven across surfaces.

Recent examples

These recent issues are all symptoms of the same broader design gap:

• #37623 runtime / provider semantics around openai-codex/gpt-5.4
• #6820 and follow-up discussion about xhigh whitelist drift for newer OpenAI Codex models
• #37635 display-layer inconsistency where models list --all omitted config-injected models

Proposed design direction

If a model is defined under models.providers.<provider>.models, and OpenClaw can resolve it into a usable runtime model, then that model should be treated as a first-class forward-compat model across all relevant surfaces:

1. models status
   • should resolve it consistently
2. models list
   • especially --all, should include it consistently
3. runtime execution
   • should use the resolved provider transport semantics, not only raw registry presence
4. availability / auth heuristics
   • should degrade gracefully for config-only models
5. thinking / reasoning capability gates
   • should not silently drift behind known forward-compat models
6. docs / validation
   • should clearly describe this as a supported compatibility path, with expected limits

Non-goal

This RFC is not proposing that arbitrary fake model IDs should always be accepted without checks.

The proposal is narrower:

• if a config-injected model can be resolved into a coherent model definition using existing provider semantics and forward-compat logic, OpenClaw should handle it consistently across config, listing, status, and runtime
• if it cannot, OpenClaw should fail clearly and early

Why an RFC instead of another one-off fix

Individual fixes are already happening, and they are helpful.

But without an explicit design stance, the same pattern will keep reappearing in different layers:

• runtime works but list output lags
• list works but availability is misleading
• runtime works but capability gates lag
• stable release behavior diverges from main

Treating models.providers-injected models as an official forward-compat path would give maintainers and contributors a clearer target for future fixes.

Concrete outcome that would help users

A simple rule of thumb could become true:

If I define a model under models.providers, and OpenClaw can resolve it, then status, list, and runtime should agree about that model.

That one invariant would eliminate a lot of confusion.

Reference implementation / field notes

We built a local external workflow around this idea here:

• https://github.com/Sapientropic/openclaw-shadow-model-registry

That repository is not meant as a request to upstream the whole external toolkit verbatim. It is just evidence that this is a reusable problem class, not a one-off patch.

Question for maintainers

Would you be open to explicitly recognizing models.providers-based forward-compat injection as a supported design pattern, and then gradually aligning status, list, runtime, capability gates, and docs around that invariant?