openclaw - 💡(How to fix) Fix Resolve model aliases before thinking/capability validation in explicit agent runs

Summary

Explicit agent runs should resolve model aliases before validating thinking/capability support.

Currently, an alias can resolve correctly for the eventual run, but --thinking validation may still treat the alias text as a literal model name under the default provider. This makes a valid configured alias look invalid and can cause OpenClaw to reject supported thinking levels.

Related preset/config UX issue: #83805

Reproduction

Given a model alias configured roughly like this:

{
  "agents": {
    "defaults": {
      "models": {
        "codex/gpt-5.5": {
          "alias": "code",
          "params": {
            "thinking": "xhigh"
          },
          "agentRuntime": {
            "id": "codex"
          }
        }
      }
    }
  }
}

Run an explicit agent command using the alias and a thinking level supported by the target model/runtime:

openclaw agent \
  --agent main \
  --model code \
  --thinking xhigh \
  --message "Reply exactly: OK" \
  --json

Current behavior

The command can fail during validation before the alias is treated as its configured target. A representative error is:

Thinking level "xhigh" is not supported for openai/code. Use one of: off, minimal, low, medium, high.

That indicates the validation path interpreted the alias as openai/code, rather than first resolving code -> codex/gpt-5.5 and validating against the resolved provider/model.

This is especially confusing because other parts of model selection may later resolve the alias correctly for execution. The operator can see a configured alias and intend one model/runtime, while validation uses a different provider/model interpretation.

Expected behavior

OpenClaw should resolve explicit model aliases before any capability or thinking-level validation.

For the example above:

• --model code should resolve to codex/gpt-5.5
• --thinking xhigh should be validated against codex/gpt-5.5
• the effective run metadata/UI should show the resolved provider/model/runtime
• validation errors should mention the resolved target, or clearly explain that the alias was not found

Why this matters

A common recommended setup is:

• fast/default runtime for ordinary chat and operations
• explicit Codex runtime/model aliases for coding, PR, repository, and long-running engineering tasks

In that setup, aliases such as code or codex are the user-facing control surface. If alias resolution and capability validation disagree, the configuration feels unreliable and users cannot tell which runtime/model will actually be used.

Suggested implementation direction

The explicit agent run path should use the same alias-aware model resolution used elsewhere before validating thinking support. Conceptually:

1. Build the model alias index from config.
2. Resolve the raw --model value through that alias index.
3. Validate --thinking against the resolved provider/model.
4. Persist/report the effective resolved provider/model/runtime in run metadata.

Adjacent improvement

The config currently appears oriented around a single alias string per model entry. It would also help to support multiple aliases for the same target, for example:

"codex/gpt-5.5": {
  "alias": "code",
  "aliases": ["code-codex", "codex"],
  "params": { "thinking": "xhigh" },
  "agentRuntime": { "id": "codex" }
}

That would let operators provide ergonomic synonyms without duplicating model entries or risking one alias pointing at an older model.

Environment

Observed on OpenClaw 2026.5.18.