Summary

Describe the problem and fix in 2–5 bullets:

• Problem: session/user model overrides always disabled configured fallback chains.
• Why it matters: operators could configure provider fallback behavior, but a user-selected model had no fallback safety net during transient provider/model failures.
• What changed: adds opt-in userOverrideFallbackPolicy: "resilient" on agents.defaults.model and per-agent chat model config, with schema/types/help/labels/docs and fallback-resolution tests.
• What did NOT change (scope boundary): default behavior remains strict; auto-selected model overrides and configured agent primaries keep their existing fallback behavior; non-chat model config schemas remain 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 N/A
• Related N/A
• This PR fixes a bug or regression

Real behavior proof (required for external PRs)

• Behavior or issue addressed: a user/session model override can now inherit the configured fallback chain when the new policy is explicitly set to resilient, while the default strict behavior still returns no fallbacks.
• Real environment tested: local OpenClaw checkout on pop-os, Node v25.8.1, branch fix/user-override-fallback-policy.
• Exact steps or command run after this patch:

  pnpm exec tsx -e 'import { resolveEffectiveModelFallbacks } from "./src/agents/agent-scope.ts"; const cfg={agents:{defaults:{model:{primary:"openai/gpt-5.4",fallbacks:["anthropic/claude-haiku-3-5","google/gemini-2.5-flash"],userOverrideFallbackPolicy:"resilient"}},list:[{id:"linus"}]}}; console.log("user override resilient =>", JSON.stringify(resolveEffectiveModelFallbacks({cfg,agentId:"linus",hasSessionModelOverride:true,modelOverrideSource:"user"}))); const strict={agents:{defaults:{model:{primary:"openai/gpt-5.4",fallbacks:["anthropic/claude-haiku-3-5"]}},list:[{id:"linus"}]}}; console.log("user override strict =>", JSON.stringify(resolveEffectiveModelFallbacks({cfg:strict,agentId:"linus",hasSessionModelOverride:true,modelOverrideSource:"user"})));'

• Evidence after fix (screenshot, recording, terminal capture, console output, redacted runtime log, linked artifact, or copied live output):

  user override resilient => ["anthropic/claude-haiku-3-5","google/gemini-2.5-flash"]
  user override strict => []
  

• Observed result after fix: resilient user overrides receive the configured fallback list; strict user overrides receive an empty fallback list.
• What was not tested: live provider failover against real external model APIs, because that would require changing a running gateway config. The changed resolver and config schema were tested locally.
• Before evidence (optional but encouraged): covered by the existing and new regression tests: the pre-change resolver returned [] for user overrides whenever hasSessionModelOverride was true.

Root Cause (if applicable)

For bug fixes or regressions, explain why this happened, not just what changed. Otherwise write N/A. If the cause is unclear, write Unknown.

• Root cause: resolveEffectiveModelFallbacks treated every non-auto session model override as authoritative and returned an empty fallback list without a config escape hatch.
• Missing detection / guardrail: no regression coverage for user-selected models that should intentionally keep operator-configured fallback chains.
• Contributing context (if known): auto model overrides and user/session overrides were represented in the same resolver path, but operators need separate fallback policy for user choices.

Regression Test Plan (if applicable)

For bug fixes or regressions, name the smallest reliable test coverage that should catch this. Otherwise write N/A.

• 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/agent-scope.test.ts, src/config/zod-schema.agent-defaults.test.ts
• Scenario the test should lock in: user model overrides remain strict by default, can opt into resilient fallback inheritance, and per-agent policy overrides defaults.
• Why this is the smallest reliable guardrail: the behavior is selected in the config schema and resolved in the agent-scope fallback helper before provider execution.
• Existing test that already covers this (if any): N/A
• If no new test is added, why not: N/A

User-visible / Behavior Changes

Users can set userOverrideFallbackPolicy: "resilient" under agents.defaults.model or an individual agent's chat model block. The default is still strict.

Diagram (if applicable)

Before:
[user override] -> [fallbacks disabled]

After:
[user override] -> [strict policy] -> [fallbacks disabled]
[user override] -> [resilient policy] -> [configured fallbacks preserved]

Security Impact (required)

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

Repro + Verification

Environment

• OS: pop-os Linux
• Runtime/container: local Node v25.8.1 / pnpm
• Model/provider: N/A, pure config + fallback resolver change
• Integration/channel (if any): N/A
• Relevant config (redacted): agents.defaults.model.userOverrideFallbackPolicy: "resilient"

Steps

1. Configure fallback models under agents.defaults.model.fallbacks.
2. Set agents.defaults.model.userOverrideFallbackPolicy: "resilient".
3. Resolve fallbacks for a session/user model override.

Expected

• Resilient user overrides inherit configured fallback models.
• Strict/default user overrides keep fallback models disabled.

Actual

• Matches expected in the local resolver smoke and targeted tests.

Evidence

Attach at least one:

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

Verification commands run:

codex review --base origin/main
pnpm check:changed
pnpm test src/agents/agent-scope.test.ts src/config/zod-schema.agent-defaults.test.ts
pnpm config:docs:check && pnpm config:schema:check
git diff --check origin/main...HEAD

codex review --base origin/main result:

The change consistently adds the new user override fallback policy across config types, schema validation, labels/help, docs, and fallback resolution. I did not find a discrete correctness issue in the modified paths.

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: strict default, resilient defaults, per-agent policy override, explicit fallback override behavior, config schema acceptance/rejection, generated config docs/schema consistency.
• Edge cases checked: explicit empty fallback list still disables fallback inheritance; non-chat model schemas still reject the chat-only policy field.
• What you did not verify: live external provider outage failover through a running gateway.

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/No) Yes
• Config/env changes? (Yes/No) Yes, optional new config field
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps: set userOverrideFallbackPolicy: "resilient" only when user-selected models should keep configured fallback chains.

Risks and Mitigations

• Risk: operators may expect resilient behavior after adding fallbacks but forget the new policy.
  • Mitigation: docs and schema help call out the strict default and the explicit opt-in field.