PR #57966: fix: improve model alias resolution robustness and error messages

• Repository: openclaw/openclaw
• Author: jinjimz
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/57966

Description (problem / solution / changelog)

• Normalize spaces and underscores to hyphens in alias key lookup
• Add provider inference fallback from configured allowlist
• Include available aliases hint in 'model not allowed' errors
• Sanitize log output for inferred provider/model values
• Add 7 new test cases covering alias normalization, cross-provider resolution, provider inference, and error message formatting

Closes #57917

Summary

• Problem: When users type /model gpt-5.4 to switch to a model configured with alias gpt-5.4 (pointing to openai-codex/gpt-5.4), the system fails with model not allowed: anthropic/gpt 5.4 because normalizeAliasKey only applied trim().toLowerCase(), causing alias lookup to fail silently and fall back to the wrong default provider.
• Why it matters: Users with valid model aliases configured cannot switch models via Control UI when their input contains minor formatting variations (spaces, underscores), and the error message provides no guidance on how to fix it.
• What changed: (1) normalizeAliasKey now normalizes spaces/underscores to hyphens. (2) resolveAllowedModelRef tries provider inference from the configured allowlist before rejecting. (3) Error messages list available aliases. (4) New log line uses sanitizeForLog().
• What did NOT change (scope boundary): No changes to parseModelRef, buildAllowedModelSet, resolveConfiguredModelRef, provider normalization, or any other model resolution paths. Alias storage format in config is unchanged.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #57917
• Related #
• This PR fixes a bug or regression

Root Cause / Regression History (if applicable)

• Root cause: normalizeAliasKey was implemented with only trim().toLowerCase(), which is insufficient for fuzzy matching user input containing spaces or underscores. When alias lookup fails, resolveModelRefFromString silently falls back to prepending defaultProvider, producing an incorrect model ref.
• Missing detection / guardrail: No test coverage for alias lookup with input variations (spaces, underscores). No fallback to provider inference from the allowlist when alias lookup misses.
• Prior context: The original normalizeAliasKey was designed for exact-match alias resolution and did not anticipate UI input variations where spaces or underscores substitute for hyphens.
• Why this regressed now: Not a regression per se — the limitation existed since alias support was added, but became user-visible as more cross-provider alias configurations were adopted.
• If unknown, what was ruled out: N/A

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/agents/model-selection.test.ts
• Scenario the test should lock in: (1) Alias lookup with spaces/underscores in input resolves to the correct cross-provider model. (2) Bare model name without alias infers the unique provider from the allowlist. (3) Error messages include available aliases.
• Why this is the smallest reliable guardrail: Unit tests on resolveAllowedModelRef and resolveModelRefFromString directly exercise the three changed code paths without requiring integration setup.
• Existing test that already covers this (if any): None — prior tests only covered exact alias matches.
• If no new test is added, why not: 7 new tests were added.

User-visible / Behavior Changes

• /model gpt 5.4, /model gpt_5.4, and /model gpt-5.4 now all resolve to the same alias target.
• When a bare model name uniquely matches a single provider in the allowlist, the correct provider is inferred automatically instead of defaulting to anthropic.
• "model not allowed" errors now show (available aliases: gpt-5.4, sonnet) to help users self-correct.

Diagram (if applicable)

Before:
[user: /model gpt-5.4] -> normalizeAliasKey("gpt-5.4") = "gpt-5.4"
  -> alias miss (key was "gpt-5.4", matches)... BUT:
[user: /model gpt 5.4] -> normalizeAliasKey("gpt 5.4") = "gpt 5.4"
  -> alias miss -> fallback to anthropic/gpt 5.4 -> "model not allowed: anthropic/gpt 5.4"

After:
[user: /model gpt 5.4] -> normalizeAliasKey("gpt 5.4") = "gpt-5.4"
  -> alias hit -> openai-codex/gpt-5.4 ✓

[user: /model gpt-5.4 (no alias configured)]
  -> alias miss -> inferUniqueProvider -> openai-codex/gpt-5.4 ✓

[user: /model nonexistent]
  -> "model not allowed: anthropic/nonexistent (available aliases: gpt-5.4, sonnet)"

## Changed files

- `src/agents/model-selection.test.ts` (modified, +414/-0)
- `src/agents/model-selection.ts` (modified, +103/-5)