Models and effort levels - Claude.ai Documentation

Claude Desktop on third-party (3P) builds the model picker in Chat, Cowork, and Code from your configuration. Your configuration decides which models the picker offers, which model and effort level each new conversation starts with, and which effort levels users can choose. You control all three with the keys under Models in the in-app configuration window. The configuration reference lists every field.

Model list and default model

inferenceModels lists the models the picker offers. Write each entry with the exact model ID your provider expects, such as us.anthropic.claude-sonnet-5 on Amazon Bedrock or claude-sonnet-5 on Google Cloud’s Agent Platform. The first entry is the default model. New Chat conversations, Cowork sessions, and Code sessions start on the default model until a user picks another model. To control whether a user’s choice carries over to later conversations and sessions, see Start every conversation on the default model. If you leave inferenceModels unset and your provider supports model discovery, Claude Desktop fills the picker from the provider’s model list at launch. The first discovered model is then the default model. Each entry is either a model ID string or an object. In an object, name holds the model ID and every other field is optional. These optional fields change how the picker shows the model:

labelOverride sets the display name for an ID the picker can’t turn into a readable name, such as a gateway routing alias or an Amazon Bedrock application inference profile ARN. Claude Desktop still sends name to your provider.
supports1m: true adds a second entry that shows the same name with 1M context window beneath it. Set it only when your deployment accepts 1M-token requests for that model. Otherwise, requests from the 1M entry fail at the provider.
prefer1m: true, with supports1m: true, shows the model as one entry. New conversations with it use the 1M context window. To do this for every entry that sets supports1m, set modelPrefer1mContext to true. When discovery fills the picker from a gateway, that key applies to every model the gateway marks as supporting 1M.
behavesAs names the Claude model behind an ID that Claude Desktop can’t identify, such as a gateway routing alias. The picker then shows that model’s Effort control. See Map an unrecognized model ID to a Claude model.

On any provider, a Chat conversation, Cowork session, or Code session on an entry without supports1m assumes a context window from the model ID:

An ID recognized as a model with a native 1M context window, such as us.anthropic.claude-opus-5: you don’t need supports1m or prefer1m. Setting them doesn’t change the assumed window. For earlier Claude Desktop versions, see Context window and compaction on the LLM gateway page. To check a model, see Extended context in the Claude Code documentation, which lists the models that run with the 1M window by default.
An ID for a model without a native 1M context window, or an unrecognized ID whose entry doesn’t set behavesAs, such as us.anthropic.claude-opus-4-6-v1 or a gateway routing alias: the assumed window is 200K tokens. If your deployment accepts 1M-token requests for the model, set supports1m on its entry.
An unrecognized ID whose entry sets behavesAs, through an LLM gateway: the assumed window is the window of the model that behavesAs names.

Effort levels

An effort level sets how much thinking Claude puts into each response. Higher levels give more thorough answers but take longer and use more tokens. Users choose the level with the Effort control in the model picker. Each model starts at Anthropic’s recommended level unless you configure otherwise. The Effort control marks the recommended level Default.

Per-model effort cap

maxEffort on an inferenceModels entry sets the highest effort level Claude Desktop offers for that model in Chat, Cowork, and Code. Set it to low, medium, high, xhigh, or max. The picker shows xhigh as Extra. The Effort control doesn’t offer levels above the cap. In Code sessions, the cap also limits Claude Code’s own effort settings, such as a CLAUDE_CODE_EFFORT_LEVEL environment variable or the /effort command. If a model’s recommended level is above its cap, the model starts at the cap. If Claude Desktop doesn’t recognize the maxEffort value, it caps the model at low.

Starting effort level for the default model

defaultModelEffort sets the effort level the default model starts at, in place of its recommended level. Other models keep their recommended level. If you set a level the default model doesn’t offer, or one above its maxEffort, the default model starts at the nearest lower level it offers. In Code, the CLAUDE_CODE_EFFORT_LEVEL environment variable or effortLevel in Claude Code’s settings takes priority. defaultModelEffort also applies when model discovery fills the picker instead of an inferenceModels list.

Map an unrecognized model ID to a Claude model

Some model IDs, such as a gateway routing alias, don’t name a specific Claude model, so the picker shows no Effort control for them. To give such an ID the controls of the Claude model behind it, set behavesAs on its inferenceModels entry to that model’s ID. In the in-app configuration window, enter that ID in the model’s Claude model behind this ID field. Requires Claude Desktop 4.29.0 or later.

{
  "inferenceModels": [
    {
      "name": "acme-claude-sonnet",
      "behavesAs": "claude-sonnet-5"
    }
  ]
}

With this entry, the picker shows acme-claude-sonnet with the controls of Claude Sonnet 5: its effort levels in Chat, Cowork, and Code, and its Thinking switch in Chat and Cowork. The model starts at Claude Sonnet 5’s recommended level, and defaultModelEffort and maxEffort still apply. Claude Desktop still sends name to your provider. Through an LLM gateway, sessions also assume Claude Sonnet 5’s context window. If the ID contains a Claude model version, set behavesAs to that same model. If the ID routes to a different model, use an ID without a version. Whatever behavesAs says, sessions treat both acme-claude-sonnet-4-6 and acme-claude-sonnet-4.6 as Claude Sonnet 4.6. Before Claude Desktop 4.16336.0, sessions treat acme-claude-sonnet-4.6 as Claude Sonnet 4 and send no effort level. Until every device runs Claude Desktop 4.16336.0 or later, write the model version with hyphens, such as acme-claude-sonnet-4-6. To check a value, go to Help > Troubleshooting > Generate Diagnostic Report, click Export to file, and open the saved .zip file:

model-selection.txt: the entry’s behavesAs line says whether the picker uses the value. (the picker offers that model's options) means it does.
managed-config.txt: behavesAs dropped: not an accepted value under Parse errors means the value isn’t a model ID. Enter a full ID such as claude-sonnet-5, not a family name such as sonnet.

Without behavesAs, users can’t change an unrecognized model’s effort level. Its conversations and sessions never run above the maxEffort on its entry. When it’s the default model, its new conversations and sessions start at defaultModelEffort, up to that cap. With only maxEffort set, they run at that cap.

Start every conversation on the default model

Set alwaysStartWithDefaultModel to true to start every new Chat conversation, Cowork session, and Code session on the default model at its starting effort level, not on the user’s last choice. When the user picks a model or effort level, it applies only for that conversation or session. If you leave alwaysStartWithDefaultModel unset, the default model and its starting effort level apply until a user picks a different model or effort level. Claude Desktop remembers that choice and starts the user’s new conversations and sessions from it. When you turn the setting on, Claude Desktop keeps the choices users saved earlier. If you later turn it off, those choices apply again. alwaysStartWithDefaultModel also applies when model discovery fills the picker instead of an inferenceModels list.

Example configuration

The following configuration offers Claude Sonnet 5 and Claude Opus 5. It makes Claude Sonnet 5 the default model at medium effort, caps both models at high effort, and starts every new conversation and session from those defaults:

{
  "inferenceModels": [
    { "name": "claude-sonnet-5", "maxEffort": "high" },
    { "name": "claude-opus-5", "maxEffort": "high" }
  ],
  "defaultModelEffort": "medium",
  "alwaysStartWithDefaultModel": true
}

With this configuration, a user who starts a new Cowork session sees Claude Sonnet 5 selected at medium effort. The Effort control offers low, medium, and high for every entry. The example is plain JSON, which is the form a bootstrap server response and the Linux managed file use. For a macOS profile or the Windows registry, encode the same values as the Value types section describes.