PR #59831: fix(control-ui): use catalog names in model picker

• Repository: openclaw/openclaw
• Author: Mule-ME
• State: closed | merged: False
• Link: https://github.com/openclaw/openclaw/pull/59831

Description (problem / solution / changelog)

Summary

• Problem: the Control UI chat model picker ignores friendly name values from models.list and can restore slash-containing model ids against the wrong provider when modelProvider is already present separately.
• Why it matters: users see raw model-id · provider labels instead of readable names, and models like nvidia/moonshotai/kimi-k2.5 can jump to the wrong provider after refresh.
• What changed: the picker/default label now prefer catalog name, slash-containing model ids remain provider-qualified on restore, and duplicate friendly names are disambiguated with · provider.
• What did NOT change (scope boundary): this PR does not add full alias support from agents.defaults.models, and it does not change the backend model catalog payload.

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 # N/A
• Related #58835
• This PR fixes a bug or regression

Root Cause / Regression History (if applicable)

• Root cause: the picker built labels from raw qualified values instead of catalog display metadata, and the restore path treated slash-containing model strings as already qualified even when modelProvider was provided separately.
• Missing detection / guardrail: there was no unit coverage for friendly-name rendering, duplicate-name disambiguation, or nested slash-containing ids paired with a separate provider.
• Prior context (git blame, prior PR, issue, or refactor if known): reported in #58835 against the built-in Control UI; the gateway already exposed name in models.list, but the chat picker path did not use it.
• Why this regressed now: this appears to be longstanding UI behavior rather than a newly introduced regression.
• If unknown, what was ruled out: ruled out missing name data for the reproduced cases; the issue is in Control UI rendering and restore logic.

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:
  • ui/src/ui/chat-model-ref.test.ts
  • ui/src/ui/chat-model-select-state.test.ts
• Scenario the test should lock in:
  • picker labels use catalog name
  • slash-containing model ids stay provider-qualified when restored from session/default state
  • duplicate friendly names stay distinguishable with · provider
• Why this is the smallest reliable guardrail: the bug lives in local picker/label resolution logic and can be covered deterministically without booting the full gateway/UI stack.
• Existing test that already covers this (if any): none before this PR
• If no new test is added, why not: N/A

User-visible / Behavior Changes

• The chat model picker now shows friendly catalog names from models.list.
• The default model label uses the same display logic.
• Models with slash-containing ids keep the correct provider-qualified value after refresh.
• If two entries share the same friendly name, the picker appends · provider to keep them distinct.

Diagram (if applicable)

Before:
[user opens picker] -> [raw "model-id · provider" labels]
[user selects nvidia/moonshotai/kimi-k2.5] -> [refresh] -> [wrong provider mapping possible]

After:
[user opens picker] -> [friendly catalog name]
[user selects nvidia/moonshotai/kimi-k2.5] -> [refresh] -> [provider-qualified value preserved]

Security Impact (required)

• New permissions/capabilities? (No)
• Secrets/tokens handling changed? (No)
• New/changed network calls? (No)
• Command/tool execution surface changed? (No)
• Data access scope changed? (No)
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: macOS
• Runtime/container: local OpenClaw main, built-in Control UI
• Model/provider: nvidia/moonshotai/kimi-k2.5 and other catalog-backed models
• Integration/channel (if any): none
• Relevant config (redacted): model catalog entries with id, name, and provider

Steps

1. Start the gateway and open the built-in Control UI.
2. Open the chat model picker and inspect the displayed labels.
3. Select a slash-containing model id, then refresh or reload the session state.

Expected

• Friendly catalog names are shown in the picker.
• Provider-qualified slash-containing model ids remain stable after refresh.

Actual

• Before this change, the picker showed raw model-id · provider labels.
• Before this change, slash-containing ids could be restored against the wrong provider.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

• Verified scenarios:
  • rebuilt the Control UI and confirmed the picker shows friendly catalog names
  • confirmed the default label uses the same display logic
  • confirmed slash-containing model ids remain provider-qualified after refresh
• Edge cases checked:
  • duplicate friendly names across providers
  • nested slash-containing ids
  • fallback to raw formatting when no catalog match exists
• What you did not verify:
  • full alias support from agents.defaults.models
  • other Control UI surfaces outside the chat model picker

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? (Yes)
• Config/env changes? (No)
• Migration needed? (No)
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: duplicate friendly names could become visually ambiguous.
  • Mitigation: append · provider only when duplicate visible names exist in the catalog.
• Risk: the original issue also mentions alias support, which this PR does not fully implement.
  • Mitigation: scope is called out explicitly; this PR is limited to name display and provider-qualified persistence.

Changed files

• src/agents/model-catalog.ts (modified, +1/-0)
• src/agents/model-selection.test.ts (modified, +96/-1)
• src/agents/model-selection.ts (modified, +89/-14)
• src/gateway/protocol/schema/agents-models-skills.ts (modified, +1/-0)
• src/gateway/server.models-voicewake-misc.test.ts (modified, +87/-0)
• src/gateway/server.sessions.gateway-server-sessions-a.test.ts (modified, +78/-0)
• src/gateway/session-utils.test.ts (modified, +30/-0)
• src/gateway/session-utils.ts (modified, +13/-1)
• ui/src/ui/chat-model-ref.test.ts (modified, +124/-35)
• ui/src/ui/chat-model-ref.ts (modified, +130/-51)
• ui/src/ui/chat-model-select-state.test.ts (modified, +105/-2)
• ui/src/ui/chat-model-select-state.ts (modified, +14/-7)
• ui/src/ui/chat/slash-command-executor.ts (modified, +6/-3)
• ui/src/ui/controllers/agents.ts (modified, +2/-2)
• ui/src/ui/types.ts (modified, +1/-0)

PR #61382: fix(control-ui): preserve configured model metadata in picker

• Repository: openclaw/openclaw
• Author: Mule-ME
• State: closed | merged: True
• Link: https://github.com/openclaw/openclaw/pull/61382

Description (problem / solution / changelog)

Summary

• Problem: the Control UI model picker lost configured model metadata and could restore nested model refs against the wrong provider after refresh.
• Why it matters: users saw raw model-id · provider labels instead of configured aliases/names, and models like nvidia/moonshotai/kimi-k2.5 could jump to the wrong provider after refresh.
• What changed: the gateway now preserves configured model alias/name metadata in the catalog, session and live-switch normalization preserve nested provider/model refs, and the Control UI picker now prefers alias || name || raw.
• What did NOT change (scope boundary): this PR does not introduce a global label-normalization policy; mixed label styles still come from upstream/provider metadata and local config.

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 #58835
• Related #59831
• This PR fixes a bug or regression

Root Cause / Regression History (if applicable)

• Root cause: configured model metadata was dropped while building the allowed-model catalog, alias was not exposed in the catalog contract, and session override normalization did not preserve nested provider/model refs consistently across refresh paths.
• Missing detection / guardrail: there was no focused coverage for alias propagation, nested override normalization, stale-provider correction, or the /model caching path for nested ids.
• Prior context (git blame, prior PR, issue, or refactor if known): reported in #58835; an earlier UI-only attempt in #59831 improved display but still pushed too much identity repair into the frontend.
• Why this regressed now: this appears to be longstanding behavior from how model metadata and session overrides were merged rather than a recent single-point regression.
• If unknown, what was ruled out: ruled out “UI-only” root cause; the missing alias/name data and nested-ref handling both required gateway-side fixes.

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
  • src/gateway/session-utils.test.ts
  • src/agents/live-model-switch.test.ts
  • src/gateway/server.models-voicewake-misc.test.ts
  • src/gateway/server.sessions.gateway-server-sessions-a.test.ts
  • ui/src/ui/chat-model-ref.test.ts
  • ui/src/ui/chat-model-select-state.test.ts
  • ui/src/ui/chat/slash-command-executor.node.test.ts
  • ui/src/ui/controllers/agents.test.ts
• Scenario the test should lock in:
  • configured alias/name propagate into models.list
  • synthetic allowed-model entries preserve configured metadata
  • nested model refs remain provider-qualified across session/live-switch normalization
  • picker labels prefer alias || name || raw
  • /model caching preserves nested refs when catalog lookup is present or unavailable
• Why this is the smallest reliable guardrail: the bug crosses gateway contract, session normalization, and picker rendering, so it needs both narrow unit coverage and gateway seam tests.
• Existing test that already covers this (if any): none before this PR
• If no new test is added, why not: N/A

User-visible / Behavior Changes

• The Control UI model picker now shows configured aliases and friendly names when available.
• Nested refs like nvidia/moonshotai/kimi-k2.5 stay provider-qualified after refresh.
• /model updates and tools-effective resolution now use the same normalized model identity.
• The picker still reflects provider-specific naming differences from upstream/config metadata instead of rewriting them into a single global style.

Diagram (if applicable)

Before:
[config alias/name] -> [allowed-model catalog drops metadata] -> [UI falls back to raw "model-id · provider"]
[nested model ref + refresh] -> [stale/partial normalization] -> [wrong provider mapping]

After:
[config alias/name] -> [gateway catalog preserves metadata] -> [UI picker shows alias/name]
[nested model ref + refresh] -> [gateway/session normalization preserves provider-qualified ref] -> [stable picker/default state]

Security Impact (required)

• New permissions/capabilities? (No)
• Secrets/tokens handling changed? (No)
• New/changed network calls? (No)
• Command/tool execution surface changed? (No)
• Data access scope changed? (No)
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: macOS
• Runtime/container: local OpenClaw main, built-in Control UI
• Model/provider: nvidia/moonshotai/kimi-k2.5 and other catalog-backed models
• Integration/channel (if any): none
• Relevant config (redacted): provider model entries with configured name plus agents.defaults.models aliases

Steps

1. Start the gateway and open the built-in Control UI.
2. Open the chat model picker and inspect the displayed labels.
3. Select a nested model ref such as nvidia/moonshotai/kimi-k2.5.
4. Refresh or reload the session state.

Expected

• The picker shows configured alias/name instead of raw model-id · provider.
• The selected nested ref stays on the same provider after refresh.

Actual

• Before this change, aliases/names were ignored and the picker showed raw labels.
• Before this change, nested refs could be cached/restored under the wrong provider.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Before: raw provider/model labels in the picker. <img width="1728" height="1117" alt="Screenshot 2026-04-05 at 19 31 43" src="https://github.com/user-attachments/assets/c5bd920b-c9da-4988-a635-79145f1c0822" />

After: friendly alias/name labels from the catalog. <img width="1728" height="1117" alt="Screenshot 2026-04-05 at 16 07 14" src="https://github.com/user-attachments/assets/82688649-9e2e-4131-8a20-5c7f4753bda8" />

Human Verification (required)

• Verified scenarios:
  • rebuilt the Control UI and confirmed the picker shows configured aliases/names
  • confirmed nested model refs stay provider-qualified after refresh
  • confirmed /model and tools-effective paths use the normalized ref
• Edge cases checked:
  • stale provider on plain ids with a unique catalog match
  • nested slash-containing ids with and without catalog availability
  • duplicate friendly names across providers
• What you did not verify:
  • a global label-normalization policy across all provider metadata styles
  • unrelated Control UI surfaces outside model selection / tools-effective model resolution

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? (Yes)
• Config/env changes? (No)
• Migration needed? (No)
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: provider catalogs/config can still contain visually inconsistent naming styles.
  • Mitigation: preserve configured/upstream metadata exactly; avoid introducing a subjective UI rewrite policy in this bug fix.
• Risk: nested ref handling spans gateway and UI paths, so regressions could reappear in less common flows.
  • Mitigation: added coverage for gateway normalization, /model, tools-effective resolution, and picker rendering.

Changed files

• CHANGELOG.md (modified, +1/-0)
• src/agents/live-model-switch.test.ts (modified, +99/-0)
• src/agents/live-model-switch.ts (modified, +11/-4)
• src/agents/model-catalog.ts (modified, +1/-0)
• src/agents/model-selection.test.ts (modified, +94/-3)
• src/agents/model-selection.ts (modified, +111/-48)
• src/gateway/protocol/schema/agents-models-skills.ts (modified, +1/-0)
• src/gateway/server.models-voicewake-misc.test.ts (modified, +87/-0)
• src/gateway/server.sessions.gateway-server-sessions-a.test.ts (modified, +78/-0)
• src/gateway/session-utils.test.ts (modified, +30/-0)
• src/gateway/session-utils.ts (modified, +8/-2)
• ui/src/ui/chat-model-ref.test.ts (modified, +160/-56)
• ui/src/ui/chat-model-ref.ts (modified, +192/-81)
• ui/src/ui/chat-model-select-state.test.ts (modified, +122/-2)
• ui/src/ui/chat-model-select-state.ts (modified, +14/-7)
• ui/src/ui/chat/slash-command-executor.node.test.ts (modified, +24/-0)
• ui/src/ui/chat/slash-command-executor.ts (modified, +22/-6)
• ui/src/ui/controllers/agents.test.ts (modified, +60/-0)
• ui/src/ui/controllers/agents.ts (modified, +2/-2)
• ui/src/ui/types.ts (modified, +1/-0)