PR #60922: feat(agents): derive fallbacks from configured model catalog

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

Description (problem / solution / changelog)

Summary

• Problem: OpenClaw only derives failover candidates from agents.defaults.model.fallbacks, so operators who keep multiple models in agents.defaults.models still have to duplicate that ordered list manually.
• Why it matters: if the configured primary becomes unavailable, the runtime stops at the primary unless the same catalog is copied into fallbacks, which is easy to miss and easy to drift.
• What changed: added an explicit opt-in agents.defaults.model.fallbacksFromModels: true that derives fallback candidates from agents.defaults.models in config order when explicit fallbacks are omitted.
• What did NOT change (scope boundary): this PR does not change existing fallback error classification, auth-profile rotation behavior, or the meaning of explicit fallbacks / fallbacks: [].

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

Root Cause (if applicable)

• Root cause: the fallback resolver only consulted explicit fallback arrays (fallbacksOverride or agents.defaults.model.fallbacks). agents.defaults.models remained allowlist/catalog-only, so keeping multiple configured models there did not influence failover.
• Missing detection / guardrail: there was no opt-in config path that said “use my configured model catalog as the fallback pool when I omit explicit fallbacks.”
• Contributing context (if known): operators often keep a single ordered model catalog in agents.defaults.models, so the duplication requirement was easy to miss.

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-fallback.test.ts
• Scenario the test should lock in: derive failover candidates from agents.defaults.models only when fallbacksFromModels: true, keep explicit fallbacks precedence, and keep fallbacks: [] as an intentional disable.
• Why this is the smallest reliable guardrail: the behavior is isolated to fallback candidate construction before provider execution.
• Existing test that already covers this (if any): existing runWithModelFallback unit coverage already covers explicit fallback ordering and allowlist behavior.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

• New opt-in config: agents.defaults.model.fallbacksFromModels: true
• When enabled and explicit fallbacks are omitted, OpenClaw derives fallback candidates from agents.defaults.models in config order, excluding the configured primary.
• Explicit fallbacks still win, and fallbacks: [] still disables fallback.

Diagram (if applicable)

Before:
[primary model fails] -> [check explicit fallbacks only] -> [stop if none configured]

After:
[primary model fails] -> [explicit fallbacks?]
                    -> [if none + fallbacksFromModels=true, derive from models catalog]
                    -> [try next configured model]

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:

Repro + Verification

Environment

• OS: macOS
• Runtime/container: Node 22 / pnpm workspace
• Model/provider: fallback candidate construction only (no provider-specific network dependency)
• Integration/channel (if any): N/A
• Relevant config (redacted): agents.defaults.model.primary, agents.defaults.model.fallbacksFromModels, agents.defaults.models

Steps

1. Configure a primary model plus multiple entries in agents.defaults.models.
2. Enable agents.defaults.model.fallbacksFromModels: true without setting explicit fallbacks.
3. Trigger a failover-worthy primary error.

Expected

• The next configured model from agents.defaults.models is attempted.

Actual

• Before this PR, the run stopped at the primary unless the fallback list was duplicated manually.

Evidence

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

Human Verification (required)

• Verified scenarios:
  • new unit coverage for catalog-derived fallback
  • explicit fallbacks still override catalog derivation
  • explicit fallbacks: [] still disables fallback
  • config schema + baseline regeneration
• Edge cases checked:
  • configured primary is excluded from derived catalog fallbacks
  • duplicate catalog keys are deduped before candidate construction
• What you did not verify:
  • full repository build / check green, because latest main is already red on unrelated skills/SourceInfo and provider-transport-fetch issues
  • full src/agents/model-fallback.test.ts run without unrelated unhandled plugin-registration/import noise on current main

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.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

Compatibility / Migration

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

Risks and Mitigations

• Risk: operators may assume the models catalog now always implies fallback.
  • Mitigation: the behavior is explicit opt-in (fallbacksFromModels: true) and docs clarify that explicit fallbacks still take precedence.
• Risk: derived catalog order may surprise users if they keep a broad manual allowlist.
  • Mitigation: opt-in only, preserves config order, and fallbacks: [] remains the escape hatch to disable fallback.

Validation notes

• pnpm exec vitest run src/agents/model-fallback.test.ts -t 'derives fallbacks from configured models when enabled|prefers explicit fallbacks over configured model derivation|treats explicit empty fallbacks as disabling configured model derivation'
  • 3 targeted tests passed
  • current main still emits unrelated unhandled plugin registration/import errors during this file
• pnpm exec vitest run src/config/schema.base.generated.test.ts
  • passed (2 files / 6 tests)
• pnpm build
  • fails on existing upstream errors in src/agents/provider-transport-fetch.ts, src/agents/skills/local-loader.ts, src/agents/skills/skill-contract.ts
• pnpm check
  • fails on the same existing upstream skills/SourceInfo errors

Changed files

• docs/.generated/config-baseline.sha256 (modified, +2/-2)
• docs/concepts/model-failover.md (modified, +8/-0)
• docs/concepts/models.md (modified, +2/-0)
• docs/gateway/configuration.md (modified, +1/-0)
• src/agents/model-fallback.test.ts (modified, +103/-0)
• src/agents/model-fallback.ts (modified, +32/-3)
• src/config/model-input.ts (modified, +12/-0)
• src/config/schema.base.generated.ts (modified, +23/-0)
• src/config/schema.help.ts (modified, +2/-0)
• src/config/schema.labels.ts (modified, +1/-0)
• src/config/types.agent-defaults.ts (modified, +1/-0)
• src/config/types.agents-shared.ts (modified, +5/-0)
• src/config/zod-schema.agent-model.ts (modified, +1/-0)