[FEATURE]: custom model aliases

[3dfactor]

Feature hasn't been suggested before.

• I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

I'd like to be able to have short aliases for models, like smart, thinking, image, cheap, free, local or any custom word I choose, so that I could exchange the models behind their meaning globally without having to edit all my custom agents and commands.
This would allow to configure all agents to use one of the aliases and then change the alias meaning either in global or in local config depending on the current situation (like tokens running out in one service).

I imagine it could be optional config branch.

"model_alias":{
  "cheap":"zai-coding-plan/glm-4.5-air",
  "image":"meta/llama-3.2-11b-vision-instruct"
}

Then inside agents and commands I could just use these as model names.

---
description: Reviews the changes and creates a commit
mode: subagent
model: cheap
temperature: 0.2
tools:
  write: false
  edit: false
  bash: true
---

[github-actions]

This issue might be a duplicate of existing issues. Please check:

• Feature request: aliases for models #3010: This closed issue requested aliases for models with the same underlying concept - creating short aliases for models to allow easier configuration switching and management across agents and commands.

Feel free to ignore if none of these address your specific case.

[3dfactor]

The mentioned issue and the current settings only allow configuring the name inside providers. My request is to have a centralized location to point aliases to model names for ease of access and ability to quickly modify.

[rekram1-node]

What is the benefit aside from a shorter name? Currently you can already define model aliases as you noted

[gimbo]

What is the benefit aside from a shorter name? Currently you can already define model aliases as you noted

It's about being able to change things in only one place; any model alias I can define currently is tied to a particular provider, which means the provider name is part of the "alias", which means it isn't much use as an indirection layer.

Example

How it is now — per-provider model aliases

Suppose I decide to use openai/gpt-5-mini as my "cheap" model. With the current model alias machinery, the provider name must be included anywhere I refer to the alias outside the provider definition (e.g. in an agent definition).

So e.g. I might have this:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openai": {
      "models": {
        "cheap": {
          "id": "gpt-5-mini"
        }
      }
    }
  },
  "agent": {
    "build": {
      "model": "openai/cheap"
    },
    "plan": {
      "model": "openai/cheap"
    }
  }
}

In fact, let's say I've got a whole bunch of agents — lots more than the two shown here — and I want many of them to use my chosen "cheap" model. So I pepper "model": "openai/cheap" across my agent definitions...

OK, so that works, kind of — the problem is: what happens when I decide to try Haiku 3 as my "cheap" model?

It's possible but ugly: I create a cheap alias under the anthropic provider, and then I have to find all those openai/cheap lines and change them to anthropic/cheap — possibly across multiple projects. That's tedious and error-prone, and discourages such experimentation.

How it could be — global model aliases

With true global aliases, swapping my cheap model from GPT-5 Mini to Haiku 3 requires a change in exactly one place. E.g. from this:

  "global_aliases": {
    "cheap": "openai/gpt-5-mini"
  },

to this:

  "global_aliases": {
    "cheap": "anthropic/claude-3-haiku-20240307"
  },

[rekram1-node]

ahh okay thx for clarifying

[withakay]

This would be really nice to have IMO, currently it is pretty tedious to update agents and commands to use new models, especially if you want to change provider.

A nice extension to this idea would be to be able group aliases to models and opencode could then pick a model at random/roundrobin that matches the requested alias.

You could for example have access to zen, GitHub and OpenAI subs, so 3 different places to access GPT-5.2. A group system could allow for all 3 providers to be used and even mix up different models from those providers. for example

"global_aliases": {
  "cheap": [
    "openai/gpt-5-mini", 
    "github-copilot/gpt-5-mini", 
    "opencode/gtp-5-mini", 
    "github-copilot/grok-code-fast-1"
  ]
},

then in your agent front matter you just reference 'cheap' and get any one of the above models

---
description: 
  Fast, Cheap agent for short, quick, general purpose tasks
mode: subagent
model: alias/cheap
---

[pakerfeldt]

I'd like to add another perspective from our experience adopting OpenCode in a company setting.

As we're rolling out OpenCode internally, we've started sharing agent definitions in our repository. One challenge we've run into is that different team members are on different LLM subscriptions, which makes it hard to align on a single set of concrete models in those shared agents.

What I imagine as a good solution is the ability to reference model aliases in shared agent configs, and then let each developer define how those aliases resolve in their own global OpenCode configuration. That would allow us to keep agent definitions stable and shared, while still giving individuals flexibility over which actual models they use.

For example:

Shared (repo) agent config

// acmerepo/.opencode/agent/react-developer.md
---
name: react-developer
description: ...
model: acme/advanced-reasoning
...

Per-user global OpenCode config:

// ~/.config/opencode/opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "model_aliases": {
    "acme/advanced-reasoning": "zen/claude-opus-4-5",
    "acme/fast": "..."
  }
}

This kind of indirection would make shared agents much easier to maintain across teams with heterogeneous model access.