Home > FAQs > How to switch models

How do I switch LLM models in OpenCues?

Q: How do I switch LLM models in OpenCues?

Two scalars in ~/.cues/OPENCUES.md control the default: llm-provider (Cerebras out of the box) and llm-model. Change them and hot-reload applies the switch in about two seconds, no restart. Under that global default sits a per-bucket routing layer, so different features can run on different models.

Two scalars in ~/.cues/OPENCUES.md control the default: llm-provider (Cerebras out of the box) and llm-model. Change them and hot-reload applies the switch in about two seconds, no restart. Under that global default sits a per-bucket routing layer, so different features can run on different models.

The buckets

Bucket	Scalars	Covers
`cues`	`cues-llm-provider`, `cues-llm-model`	Word cues and sentence cues
`blanks`	`blanks-llm-provider`, `blanks-llm-model`	Fluid blank, transform blank, fluid config, keyword blanks

Each bucket's provider defaults to inherit, falling through to the global llm-provider. A common split is a fast, cheap model for word cues (they fire often and need low latency) and a stronger model for the blanks bucket (where you asked an explicit question and quality matters most).

The precedence ladder

When several settings could apply, the resolution order is fixed, highest wins: per-source override, then per-feature override, then bucket scalar, then global llm-provider, then auto-fallback. The per-feature knobs (fluid-blank-provider and friends) are deliberately file-edit-only and kept out of the settings menus; the buckets are the level most people should stop at.

Three ways to make the change

Edit the file. ~/.cues/OPENCUES.md frontmatter; hot-reload picks it up in ~2 seconds.
The CLI. opencues config set llm-provider groq, validated against the feature registry (config list shows everything).
In-text. Type opencues settings _ in any host and cycle values with the arrow keys without leaving your text field.

Providers and models

The global provider values are cerebras, groq, openai, anthropic, gemini, openrouter, plus file-edit-only options including local ollama. llm-model is free-form; leave it unset and the runtime picks a sensible default per provider (on Cerebras that's gpt-oss-120b). Remember the key has to exist for the provider you switch to: opencues set-key <provider> <key>, then opencues check-keys to confirm.

Two guardrails worth knowing. Keeping both CEREBRAS_API_KEY and GROQ_API_KEY configured enables automatic failover between them on rate limits, with no quality shift since both serve the same gpt-oss-120b weights. And the free training-pool provider (opencode-zen) is accepted only in the blanks bucket; setting it globally is refused at startup, because cues see your prose without an explicit consent keystroke.

Going local

The ollama provider value is file-edit-only (it's hidden from the cycling menus) and runs everything against models on your own machine, defaulting to a small gemma model. It's the full-privacy option: no key, no cloud, at whatever speed your hardware gives, and with no failover peer since there's nothing wire-compatible to fall back to. The trade-offs are covered in Ollama vs cloud.