Model roles

Route work by purposeCopy Anchor Link

Model roles let omp use different models for different kinds of work. You might keep a balanced model for the main session, a faster model for lightweight work, and a stronger reasoning model for difficult planning or review. Configure each role once; features that use that role pick it automatically.

You do not have to configure roles before using omp. After you sign in to a provider, omp automatically chooses usable models for unassigned built-in roles. Start with the defaults, then pin a role only when you want predictable quality, latency, cost, or provider usage.

A role chooses which model handles a kind of work; an agent also chooses how that worker behaves and what it can use. See Agents & model roles when you are deciding which layer to change.

The quickest way to make an assignment is:

1. Enter /model (or press Alt + M).
2. Open Roles.
3. Select a role, choose a model, and optionally choose its thinking level.
4. Return to Roles to see the effective assignment.

Most people only need to consider these roles:

What happens automaticallyCopy Anchor Link

With an empty modelRoles map, omp resolves roles from the models that are available and authenticated. Specialized features therefore work without a complete role map.

A few defaults are worth knowing:

• default is the main session model.
• Unassigned smol, slow, and designer roles can use the configured default model before omp looks for another suitable model.
• Unassigned tiny work follows the fast-model preference used by smol.
• An unassigned advisor seeks a separate strong reasoning model rather than inheriting default. See Advisor for the advisor workflow.

Configure rolesCopy Anchor Link

modelRoleStorage: project

Switch and verify in a running sessionCopy Anchor Link

The default cycle is smol → default → slow. omp skips roles that have no usable assignment; if only one role model is available, it reports that there is nothing to cycle to. Cycling changes the active model for the current session, not the saved role map.

Change the order in the Roles view or with cycleOrder:

cycleOrder:
  - default
  - slow
  - smol

After an assignment, reopen /model and inspect Roles to verify the model and thinking level that omp resolved. For the main session, the status line also shows the active model after switching or cycling.

All built-in rolesCopy Anchor Link

Extensions and authored agents can introduce additional role names. A custom role becomes visible in the model hub when it appears in modelRoles, cycleOrder, or modelTags; the extension or agent must actually refer to that role for work to be routed through it.

Add retry fallback modelsCopy Anchor Link

Role assignment chooses the preferred model. Retry fallback chains say where omp may move when an eligible request failure or quota condition makes that model unavailable.

The easiest setup is in /model → Roles: add fallback rows beneath a role, or choose New fallback to protect a particular model or provider. Order matters; omp tries usable entries from top to bottom.

A minimal YAML chain looks like this:

retry:
  modelFallback: true
  fallbackChains:
    default:
      - openai/gpt-5.4
      - google/gemini-3-pro
  fallbackRevertPolicy: cooldown-expiry

A default chain is also used for configured roles that do not have their own chain. Give a role its own list when it needs different cost, capability, or provider boundaries:

retry:
  fallbackChains:
    default:
      - openai/gpt-5.4
    vision:
      - google/gemini-3-pro
    "google-antigravity/*":
      - google/*
      - google-vertex/*

Fallback-chain keys and entries have stricter syntax than role values:

Use full provider-qualified selectors in fallback arrays. Every fallback also needs working credentials and a catalog entry; unavailable candidates are skipped.

Role and fallback settings referenceCopy Anchor Link

Routing settingsCopy Anchor Link

Retry fallback settingsCopy Anchor Link

See Settings for configuration precedence and Providers for credentials and provider-specific model discovery.

TroubleshootingCopy Anchor Link

RelatedCopy Anchor Link

Source: omp.sh — MIT, Stencil Labs. Initially imported on 2026-10-03; updates via automatic sync.