PR #75326: perf: keep models list responsive during catalog discovery

• Repository: openclaw/openclaw
• Author: steipete
• State: closed | merged: True
• Link: https://github.com/openclaw/openclaw/pull/75326

Description (problem / solution / changelog)

Summary

• Problem: models.list default/configured views wait for full gateway model catalog discovery on cold or slow provider/plugin catalog paths.
• Why it matters: slow model discovery makes common CLI/UI control-plane calls look stalled during gateway CPU/event-loop starvation incidents.
• What changed: default/configured models.list now falls back to configured/synthetic rows after a short wait, while discovery continues through the existing catalog cache path.
• What did NOT change (scope boundary): models.list --all remains exact and waits for the full discovered catalog; no provider auth, catalog schema, or model execution behavior changed.

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

• Related #72338
• Related #74404
• Related #75297
• Related #75287
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: models.list always awaited context.loadGatewayModelCatalog(), even for views that can answer from configured model rows when provider discovery is slow.
• Missing detection / guardrail: sessions.list had slow-catalog timeout coverage, but models.list did not.
• Contributing context (if known): provider plugin augmentation/runtime-deps can make model catalog discovery slow on packaged gateway installs.

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/gateway/server-methods/models.test.ts
• Scenario the test should lock in: configured view returns configured model rows after a slow-catalog timeout; view=all still waits for exact catalog data.
• Why this is the smallest reliable guardrail: it exercises the request handler directly with fake timers and a deferred catalog promise.
• Existing test that already covers this (if any): existing server model tests cover catalog contents, not slow discovery behavior.
• If no new test is added, why not: N/A.

User-visible / Behavior Changes

models list default/configured views can return configured model rows quickly while provider discovery is still slow. models list --all remains the exact wait-for-discovery command.

Diagram (if applicable)

Before:
models.list default/configured -> await full provider catalog -> delayed response

After:
models.list default/configured -> short wait -> configured/synthetic rows -> responsive control plane
models.list --all -> await full provider catalog -> exact response

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 local plus Blacksmith Linux Testbox
• Runtime/container: Node/pnpm via repo wrappers
• Model/provider: configured model fixture
• Integration/channel (if any): Gateway RPC models.list
• Relevant config (redacted): configured models.providers.openai.models fixture

Steps

1. Call models.list configured view with loadGatewayModelCatalog() deferred.
2. Advance fake timers past the short timeout.
3. Assert the handler returns configured model rows.
4. Repeat with view=all and assert it waits for the deferred catalog.

Expected

• Default/configured views stay responsive; all remains exact.

Actual

• Before this patch, all views waited on the slow catalog promise. After this patch, only all does.

Evidence

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

Human Verification (required)

• Verified scenarios: focused models handler test passed locally; combined changed gate passed on Blacksmith Testbox before PR split.
• Edge cases checked: view=all exact behavior is covered by a separate test.
• What you did not verify: live Linux npm-global Telegram repro/profile.

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: default/configured views may temporarily omit auth-backed discovered provider rows during slow discovery.
  • Mitigation: configured/synthetic rows still return, existing cache refresh continues, and --all remains available for exact discovery.

Changed files

• CHANGELOG.md (modified, +1/-0)
• docs/cli/models.md (modified, +5/-0)
• src/gateway/server-methods/models.test.ts (added, +156/-0)
• src/gateway/server-methods/models.ts (modified, +40/-1)