From 0074b8e4f827f5edbed0cdb1a0a43ab30cbcc1f0 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Wed, 7 Jan 2026 18:20:02 +0100 Subject: [PATCH] docs: explain clawdbot model selection --- docs/concepts/models.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/concepts/models.md b/docs/concepts/models.md index b7fba7b12..85fdd4a64 100644 --- a/docs/concepts/models.md +++ b/docs/concepts/models.md @@ -12,6 +12,23 @@ See [`docs/model-failover.md`](/concepts/model-failover) for how auth profiles r Goal: give clear model visibility + control (configured vs available), plus scan tooling that prefers tool-call + image-capable models and maintains ordered fallbacks. +## How Clawdbot models work (quick explainer) + +Clawdbot selects models in this order: +1) The configured **primary** model (`agent.model.primary`). +2) If it fails, fallbacks in `agent.model.fallbacks` (in order). +3) Auth failover happens **inside** the provider first (see [/concepts/model-failover](/concepts/model-failover)). + +Key pieces: +- `provider/model` is the canonical model id (e.g. `anthropic/claude-opus-4-5`). +- `agent.models` is the **allowlist/catalog** of models Clawdbot can use, with optional aliases. +- `agent.imageModel` is only used when the primary model **can’t** accept images. +- `models.providers` lets you add custom providers + models (written to `models.json`). +- `/model ` switches the active model for the current session; `/model list` shows what’s allowed. + +Related: +- Context limits are model-specific; long sessions may trigger compaction. See [/concepts/compaction](/concepts/compaction). + ## Model recommendations Through testing, we’ve found [Claude Opus 4.5](https://www.anthropic.com/claude/opus) is the most useful general-purpose model for anything coding-related. We suggest [GPT-5.2-Codex](https://developers.openai.com/codex/models) for coding and sub-agents. For personal assistant work, nothing comes close to Opus. If you’re going all-in on Claude, we recommend the [Claude Max $200 subscription](https://www.anthropic.com/pricing/).