Models in OpenCode: ids, pinning and per-agent routing

Introduction

OpenCode itself is free and open source; the model is the only recurring cost. It talks to 75+ providers directly, plus local servers, and the curated gateway is OpenCode Console. This page is about using a model inside OpenCode: which tier to pick, how ids are written, where to pin a default, how to give each agent its own model, and how to keep the bill visible. The models themselves — families, pricing, context — are on AI models.

Three tiers, one default

Three models cover 95 percent of daily work. Default to the free one, escalate to the cheap one, finish hard tasks with the top one. Prices move — verify current rates before budgeting:

Free OpenCode model — your main workhorse. Console always carries a few free models. Which one is current, its fallbacks and the one-line check before pinning an id are on Free OpenCode model. Free ids rotate: the former default, Muse Spark 1.3 Free, left the catalog in October 2026, and every config that pinned it stopped resolving. Its paid twin is described on Muse Spark 1.3.

Free-tier privacy: a contributor tier trades the price for permission to use prompts and completions to train future models. Never send secrets, customer data, or private code to a free model whose terms you have not read. Most other free models claim zero-retention during the free period, but some may still use data for improvement — check the Console privacy notes first, and switch to a paid model or a local model for sensitive work.

GPT 6 Luna — the cheapest smart paid model. Luna is the small member of the GPT 6 family (Astra, Sol, Luna). At roughly ten cents per 1M input tokens it is cheaper than most Flash, Nano and Mini models, yet good enough as an agent: it follows tools, keeps context, and survives long refactors. Use it when the free model is rate-limited or gone, for overnight runs, and for CI jobs where you count every cent. The bigger sibling opencode/gpt-6-sol at about $2.00 / $10.00 is the middle step before the flagship models.

Claude Opus 5.5 — the top model for hard work. Opus 5.5 is the current top of the Claude line on Console, above Sonnet 5.5 at about $2.00 / $10.00 and Haiku 5.5 at about $0.10 / $0.50. It wins on large refactors, tricky debugging, API design, and careful security review. It is roughly 40 times more expensive than Luna on input, so do not burn it on questions a free model answers well. Typical split: the free model does 80 percent of steps, Luna does routine paid work, Opus 5.5 does the last 10 percent that decides quality. Newer revisions such as Sonnet 5.x or Opus 5.x follow the same rule — pick the newest Opus for max quality, newest Sonnet for quality per dollar.

Other orientation prices from OpenCode Console, per 1M tokens in+out. Rates move — re-check as in Verify prices before budgeting:

Free ids rotate. The live list, the fallback order and the check are on Free OpenCode model; when a free id disappears, take the next one from there or fall back to local Ollama.

Model ids and variants

A model id is provider/model, with an optional #variant for reasoning effort or speed. Console models use opencode/<model-id>; your own provider keys keep that provider in front and are billed by it:

Custom variants and aliases are defined in config, so a short name can carry a model, an effort level and provider settings. The live list of ids, including the free ones, comes from the models endpoint or from the shell:

curl https://opencode.ai/inference/v1/models

opencode models

Search the JSON output for your id before pinning it. In the TUI the same check is /models.

Per-agent routing

One model for everything is the expensive default. Give each role its own model, cheapest first:

The session default stays cheap; only the reviewer pays for the top tier, in opencode.jsonc at the project root:

vi opencode.jsonc

{ "$schema": "https://opencode.ai/config.json", "model": "opencode/gpt-6-luna", "agents": { "reviewer": { "description": "Final correctness and security pass", "mode": "subagent", "model": "opencode/claude-opus-5-5" } } }

The full three-role layout, with skills gated per agent, is on Three models, one project. The agent files themselves — frontmatter, permissions, four complete examples — are on OpenCode agents.

Switching models

• Inside the TUI: /models opens the picker without losing context, F2 cycles recent models, Ctrl+X then M opens the same list.
• From the shell: opencode models lists ids, opencode run --model <id> "prompt" pins one for a single non-interactive run.
• Per project: the model key in opencode.jsonc, with a nearer file overriding a farther one.
• Per agent: the model key inside an agent definition, as above.

Stay in one session and escalate only when the role changes: context accumulates, and the next model inherits the work instead of re-reading the repo. For a hard feature, switch to Plan mode first, iterate on the plan, then switch back to Build — do not let a strong model edit on the first prompt.

Cost control

• Free first: set the free model as default, do everything with it, escalate only on failure. This alone cuts most bills by an order of magnitude.
• Limits: set monthly workspace and per-member limits in Console, and enable auto-reload deliberately, not by default.
• Visibility: review opencode stats --cost --models weekly, per model and with token details. Session-title generation uses cheap models and shows up in history separately.
• Tier thresholds: Luna above 272K tokens, Sonnet above 200K and Haiku above 100K cost more per token. Long sessions cross the line silently — enable compaction with a keep.tokens budget and commit mid-way.
• Scope the top tier: Opus reviews diffs, not whole repos. Cap the reviewer at a few steps, deny shell so it cannot wander, and keep the session default on Luna.

Other providers and local models

Console is one route, not the only one. Your own Anthropic, OpenAI or Google keys are billed by that provider; OpenRouter holds 300+ models behind one key through an OpenAI-compatible provider entry. Local models need no key at all: with ollama serve running, OpenCode discovers them at the default address, and the same works for LM Studio and vLLM. See Ollama: local models the easy way and Qwen: download, install, fine-tune and use.

Troubleshooting

• No models listed: you skipped connect — run /connect or opencode auth login opencode. For Ollama confirm ollama serve and ollama list.
• Free model gone or rate-limited: free ids rotate — take the next live id from the fallback order, switch the default to opencode/gpt-6-luna, or fall back to local Ollama.
• Model not found after a config edit: check the id against the live list, then run opencode reload. Catalog, credentials and config are location-scoped, so a model available in one project may be missing in another.
• Unexpected charges: set monthly and per-member limits in Console, review opencode stats --cost --models, and move routine steps from the top tier to Luna.

Official sources:

• opencode.ai/v2/docs
• opencode.ai/docs/console/models (ids, endpoints, pricing, privacy)
• opencode.ai/inference/v1/models (live id list)

Article author: Arthur Isaev