English documentation · runtime 7.24.4 · SDK 2.6.7. Content is maintained with runtime development; see each guide's scope and review date.

Multi-Model Routing Best Practices

Status: Active Scope: public, current-state Last reviewed: 2026-09-13 Owner: ax-code runtime

This guide captures the recommended way to run ax-code with a premium reasoning model and cheaper same-provider aux models.

Core principle

Use the expensive model for reasoning-dense work, and cheap models for mechanical or read-only work. The real savings come from context filtering: the premium model only sees distilled context prepared by cheaper models or subagents.

Recommended layer split

Pin provider/model IDs that are connected. Disabled first-party plan IDs (alibaba-token-plan, deepseek, zai-coding-plan, minimax-coding-plan) still resolve by SKU, but each call first tries the disabled provider and warns. Qwen 3.8 Max is a valid explicit choice, not the product or example default; without config.model, implicit default walks connected catalogs in this order: deepseek-flash, glm-5.3-flash, qwen3.8-flash, MiniMax-M3, grok-4.6, claude-sonnet-5, gpt-6, gemini-3.8-flash, qwen3.8-27b.

Config template

See ax-code.json.example at the repo root for a concrete DeepSeek Flash default with Pro on reasoning agents.

Codex CLI auxiliary models

Codex model availability depends on the account’s sign-in method and client, not only the catalog’s text or tool capabilities. AX Code therefore does not infer a codex-cli small model from names or family metadata. Without an explicit small_model or compaction-agent model, compaction uses the session model.

If you configure an auxiliary model, verify it works with the same Codex login. An explicit Codex rejection that a model is unsupported with a ChatGPT account allows compaction to try the session model once, skipping other small models. The rejected attempt remains in session history. Other authentication, billing, validation, cancellation, and context-overflow failures retain their existing handling; the local-provider privacy guard still applies.

For an affected older installation, remove an incompatible small_model or agent.compaction.model override and explicitly pin agent.compaction.model to a model already verified with that Codex account. Changing only the visible session model does not override a separately pinned compaction model.

Task-type auto-routing rules

Do not auto-route all low-value tasks to a cheap model. Split them by failure cost:

• Safe to auto-route (read-only or human-reviewable):
  • repository exploration, grep/search triage, file classification
  • code summarization, log summarization, code explanation
  • preparing context for the premium model
  • documentation
• Opt-in only (mechanically verifiable but can hide behavior changes):
  • boilerplate, lint fixes
• Never auto-route by default (silent errors are expensive):
  • unit tests
  • rename/refactor
  • simple SQL
  • API wrapper
  • simple CRUD

The last group should stay on the session model unless the user explicitly pins a cheaper model.

Operating manual

1. Start non-trivial tasks in plan mode so the advisor validates the design before the worker writes code.
2. If the worker loops or fails verification twice, switch to debug with the failing signal.
3. Use council for independent diagnosis when two fixes are plausible, not to finish the task.
4. Reserve manual model switches for rare reasoning-heavy turns; switch back afterward.

Known ax-code limitations

• Provider.getSmallModel() returns undefined for providers whose catalog neither tags a tier-bearing family nor matches the hardcoded priority lists; aux calls then fall back to the session model (logged as “no small model for provider”).
• There is no mid-run escalation from a stuck worker to a stronger model.