From 756cb22f15a70ca79930e7ca4968678ae30e1d0c Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sat, 4 Apr 2026 14:55:44 +0100 Subject: [PATCH] docs: refresh model selection fallback refs --- docs/cli/models.md | 4 +++- docs/concepts/agent.md | 4 +++- docs/concepts/models.md | 5 ++++- docs/gateway/configuration-reference.md | 2 +- docs/help/faq.md | 2 +- 5 files changed, 12 insertions(+), 5 deletions(-) diff --git a/docs/cli/models.md b/docs/cli/models.md index 4c0fdb81248..3a8dc7f8705 100644 --- a/docs/cli/models.md +++ b/docs/cli/models.md @@ -41,7 +41,9 @@ Notes: - `models set ` accepts `provider/model` or an alias. - Model refs are parsed by splitting on the **first** `/`. If the model ID includes `/` (OpenRouter-style), include the provider prefix (example: `openrouter/moonshotai/kimi-k2`). -- If you omit the provider, OpenClaw treats the input as an alias or a model for the **default provider** (only works when there is no `/` in the model ID). +- If you omit the provider, OpenClaw resolves the input as an alias first, then + as a unique configured-provider match for that exact model id, and only then + falls back to the configured default provider with a deprecation warning. - `models status` may show `marker()` in auth output for non-secret placeholders (for example `OPENAI_API_KEY`, `secretref-managed`, `minimax-oauth`, `oauth:chutes`, `ollama-local`) instead of masking them as secrets. ### `models status` diff --git a/docs/concepts/agent.md b/docs/concepts/agent.md index bb03489c85e..b9ce7fac72d 100644 --- a/docs/concepts/agent.md +++ b/docs/concepts/agent.md @@ -111,7 +111,9 @@ Model refs in config (for example `agents.defaults.model` and `agents.defaults.m - Use `provider/model` when configuring models. - If the model ID itself contains `/` (OpenRouter-style), include the provider prefix (example: `openrouter/moonshotai/kimi-k2`). -- If you omit the provider, OpenClaw treats the input as an alias or a model for the **default provider** (only works when there is no `/` in the model ID). +- If you omit the provider, OpenClaw tries an alias first, then a unique + configured-provider match for that exact model id, and only then falls back + to the configured default provider. ## Configuration (minimal) diff --git a/docs/concepts/models.md b/docs/concepts/models.md index 178960057dd..f90fce87913 100644 --- a/docs/concepts/models.md +++ b/docs/concepts/models.md @@ -119,7 +119,10 @@ Notes: - `/model status` is the detailed view (auth candidates and, when configured, provider endpoint `baseUrl` + `api` mode). - Model refs are parsed by splitting on the **first** `/`. Use `provider/model` when typing `/model `. - If the model ID itself contains `/` (OpenRouter-style), you must include the provider prefix (example: `/model openrouter/moonshotai/kimi-k2`). -- If you omit the provider, OpenClaw treats the input as an alias or a model for the **default provider** (only works when there is no `/` in the model ID). +- If you omit the provider, OpenClaw resolves the input in this order: + 1. alias match + 2. unique configured-provider match for that exact unprefixed model id + 3. deprecated fallback to the configured default provider Full command behavior/config: [Slash commands](/tools/slash-commands). diff --git a/docs/gateway/configuration-reference.md b/docs/gateway/configuration-reference.md index f6c625b3a57..6a374a7426a 100644 --- a/docs/gateway/configuration-reference.md +++ b/docs/gateway/configuration-reference.md @@ -989,7 +989,7 @@ Time format in system prompt. Default: `auto` (OS preference). - `pdfMaxPages`: default maximum pages considered by extraction fallback mode in the `pdf` tool. - `verboseDefault`: default verbose level for agents. Values: `"off"`, `"on"`, `"full"`. Default: `"off"`. - `elevatedDefault`: default elevated-output level for agents. Values: `"off"`, `"on"`, `"ask"`, `"full"`. Default: `"on"`. -- `model.primary`: format `provider/model` (e.g. `openai/gpt-5.4`). If you omit the provider, OpenClaw assumes the configured default provider (currently `openai`; deprecated fallback behavior, so prefer explicit `provider/model`). +- `model.primary`: format `provider/model` (e.g. `openai/gpt-5.4`). If you omit the provider, OpenClaw tries an alias first, then a unique configured-provider match for that exact model id, and only then falls back to the configured default provider (deprecated compatibility behavior, so prefer explicit `provider/model`). - `models`: the configured model catalog and allowlist for `/model`. Each entry can include `alias` (shortcut) and `params` (provider-specific, for example `temperature`, `maxTokens`, `cacheRetention`, `context1m`). - `params`: global default provider parameters applied to all models. Set at `agents.defaults.params` (e.g. `{ cacheRetention: "long" }`). - `params` merge precedence (config): `agents.defaults.params` (global base) is overridden by `agents.defaults.models["provider/model"].params` (per-model), then `agents.list[].params` (matching agent id) overrides by key. See [Prompt Caching](/reference/prompt-caching) for details. diff --git a/docs/help/faq.md b/docs/help/faq.md index 2bcea687182..f21b5fa83d8 100644 --- a/docs/help/faq.md +++ b/docs/help/faq.md @@ -2107,7 +2107,7 @@ for usage/billing and raise limits as needed. agents.defaults.model.primary ``` - Models are referenced as `provider/model` (example: `openai/gpt-5.4`). If you omit the provider, OpenClaw currently assumes the configured default provider (currently `openai`) as a temporary deprecation fallback - but you should still **explicitly** set `provider/model`. + Models are referenced as `provider/model` (example: `openai/gpt-5.4`). If you omit the provider, OpenClaw first tries an alias, then a unique configured-provider match for that exact model id, and only then falls back to the configured default provider as a deprecated compatibility path. You should still **explicitly** set `provider/model`.