[FEATURE]: custom model aliases

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
---

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.

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.

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

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"
  },

ahh okay thx for clarifying

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
---

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.

To stay organized issues are automatically closed after 90 days of no activity. If the issue is still relevant please open a new one.

Hi. I'm not sure if or when this will be added to OpenCode itself. So for the meantime I wrote a custom plugin. 🙂
https://gist.github.com/krystofrezac/7f16ba252279f889eb750a866b257a1d

@krystofrezac

I also took a stab at implementing a plugin for my own desired alias functionality: https://github.com/mattaschmann/opencode-model-alias

@krystofrezac I took inspiration from your gist.

@mattaschmann

Following up on this thread since the two plugin solutions posted earlier are no longer maintained: @mattaschmann's opencode-model-alias was unpublished from npm in June, and @krystofrezac's gist hasn't been updated since April.

I've forked and substantially hardened Matt's plugin — it's now published as @renaudcerrato/opencode-model-alias (MIT, 182 tests / 100% coverage). It covers the exact workflow requested here: define aliases like cheap/smart in ~/.config/opencode/model-aliases.json, reference them in any agent/command model field, and remap per machine without touching shared configs. It also adds model variants and alias chains (stable role names layered on machine-specific mappings).

Setup is just a config entry — opencode installs npm plugins automatically:

{ "plugin": ["@renaudcerrato/opencode-model-alias@1.1.2"] }

If native support ever lands (the closed PR #11352 was a step in that direction), the plugin becomes unnecessary — until then this fills the gap.

Navigation Menu

Repository navigation

[FEATURE]: custom model aliases #3439

Feature hasn't been suggested before.

Describe the enhancement you want to request

Example

How it is now — per-provider model aliases

How it could be — global model aliases

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[FEATURE]: custom model aliases #3439

Description

Feature hasn't been suggested before.

Describe the enhancement you want to request

Activity

github-actions commented on Oct 25, 2025

3dfactor commented on Oct 25, 2025

rekram1-node commented on Oct 25, 2025

gimbo commented on Oct 25, 2025

Example

How it is now — per-provider model aliases

How it could be — global model aliases

rekram1-node commented on Oct 26, 2025

withakay commented on Jan 24, 2026

pakerfeldt commented on Jan 30, 2026

github-actions commented on Apr 1, 2026

krystofrezac commented on Apr 1, 2026

mattaschmann commented on Apr 8, 2026

renaudcerrato commented on Sep 1, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions