diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json index 58cc1db7a..371cf0bd5 100644 --- a/.openclaw-sync/source.json +++ b/.openclaw-sync/source.json @@ -1,5 +1,5 @@ { "repository": "openclaw/openclaw", - "sha": "496a5eb56f466e828e7f843a0a55dfc7fbe01199", - "syncedAt": "2026-04-27T22:32:18.241Z" + "sha": "d2320e4d4b426e16de9ca0701fb8f1bc1488a12a", + "syncedAt": "2026-04-27T22:33:48.088Z" } diff --git a/docs/concepts/model-failover.md b/docs/concepts/model-failover.md index 65074b4ec..db2bd0f8f 100644 --- a/docs/concepts/model-failover.md +++ b/docs/concepts/model-failover.md @@ -24,7 +24,7 @@ For a normal text run, OpenClaw evaluates candidates in this order: Resolve the active session model and auth-profile preference. - Build the model candidate chain from the currently selected session model, then `agents.defaults.model.fallbacks` in order, ending with the configured primary when the run started from an override. + Build the model candidate chain from the configured model or an auto-selected fallback model, then `agents.defaults.model.fallbacks` in order. Explicit user model selections are strict and do not silently fall back to a different model. Try the current provider with auth-profile rotation/cooldown rules. @@ -207,7 +207,7 @@ If all profiles for a provider fail, OpenClaw moves to the next model in `agents Overloaded and rate-limit errors are handled more aggressively than billing cooldowns. By default, OpenClaw allows one same-provider auth-profile retry, then switches to the next configured model fallback without waiting. Provider-busy signals such as `ModelNotReadyException` land in that overloaded bucket. Tune this with `auth.cooldowns.overloadedProfileRotations`, `auth.cooldowns.overloadedBackoffMs`, and `auth.cooldowns.rateLimitedProfileRotations`. -When a run starts with a model override (hooks or CLI), fallbacks still end at `agents.defaults.model.primary` after trying any configured fallbacks. +When a run starts from the configured primary or an auto-selected fallback override, OpenClaw can walk the configured fallback chain. Explicit user selections (for example `/model ollama/qwen3.5:27b`, the model picker, or one-off CLI provider/model overrides) are strict: if that provider/model is unreachable or fails before producing a reply, OpenClaw reports the failure instead of answering from an unrelated fallback. ### Candidate chain rules @@ -264,6 +264,7 @@ That means fallback retries have to coordinate with live model switching: - Only explicit user-driven model changes mark a pending live switch. That includes `/model`, `session_status(model=...)`, and `sessions.patch`. - System-driven model changes such as fallback rotation, heartbeat overrides, or compaction never mark a pending live switch on their own. +- User-driven model overrides are treated as exact selections for fallback policy, so an unreachable selected provider surfaces as a failure instead of being masked by `agents.defaults.model.fallbacks`. - Before a fallback retry starts, the reply runner persists the selected fallback override fields to the session entry. - Auto fallback overrides remain selected on subsequent turns so OpenClaw does not probe a known-bad primary on every message. `/new`, `/reset`, and `sessions.reset` clear auto-sourced overrides and return the session to the configured default. - `/status` shows the selected model and, when fallback state differs, the active fallback model and reason. diff --git a/docs/concepts/models.md b/docs/concepts/models.md index a508dce6f..0d37d7e07 100644 --- a/docs/concepts/models.md +++ b/docs/concepts/models.md @@ -156,6 +156,7 @@ You can switch models for the current session without restarting: - If the agent is idle, the next run uses the new model right away. - If a run is already active, OpenClaw marks a live switch as pending and only restarts into the new model at a clean retry point. - If tool activity or reply output has already started, the pending switch can stay queued until a later retry opportunity or the next user turn. + - A user-selected `/model` ref is strict for that session: if the selected provider/model is unreachable, the reply fails visibly instead of silently answering from `agents.defaults.model.fallbacks`. - `/model status` is the detailed view (auth candidates and, when configured, provider endpoint `baseUrl` + `api` mode). diff --git a/docs/providers/ollama.md b/docs/providers/ollama.md index 93e26b5e7..0176c7d10 100644 --- a/docs/providers/ollama.md +++ b/docs/providers/ollama.md @@ -210,6 +210,11 @@ transport, but it does not start a chat-agent turn or load MCP/tool context. If this succeeds while normal agent replies fail, troubleshoot the model's agent prompt/tool capacity next. +When you switch a conversation with `/model ollama/`, OpenClaw treats +that as an exact user selection. If the configured Ollama `baseUrl` is +unreachable, the next reply fails with the provider error instead of silently +answering from another configured fallback model. + Live-verify the local text path, native stream path, and embeddings against local Ollama with: