> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Configuração de modelo
> Saiba mais sobre a configuração do modelo Claude Code, incluindo aliases de modelo como `opusplan`
Modelos disponíveis
Para a configuração `model` no Claude Code, você pode configurar:
* Um **alias de modelo**
* Um **nome de modelo**
* API Anthropic: Um **[nome de modelo](https://platform.claude.com/docs/pt/about-claude/models/overview)** completo
* Bedrock: um ARN de perfil de inferência
* Foundry: um nome de implantação
* Vertex: um nome de versão
`ANTHROPIC_BASE_URL` altera para onde as solicitações são enviadas, não qual modelo as responde. Para rotear Claude através de um gateway LLM, consulte [gateways LLM](/pt/llm-gateway).
Aliases de modelo
Os aliases de modelo fornecem uma maneira conveniente de selecionar configurações de modelo sem precisar lembrar dos números exatos da versão:
| Alias de modelo | Comportamento |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`default`** | Valor especial que limpa qualquer substituição de modelo e reverte para o modelo recomendado para seu tipo de conta. Não é em si um alias de modelo |
| **`best`** | Usa Fable 5 onde sua organização tem acesso a ele, caso contrário o modelo Opus mais recente |
| **`fable`** | Usa Claude Fable 5 para suas tarefas mais difíceis e de longa duração |
| **`sonnet`** | Usa o modelo Sonnet mais recente para tarefas de codificação diária |
| **`opus`** | Usa o modelo Opus mais recente para tarefas de raciocínio complexo |
| **`haiku`** | Usa o modelo Haiku rápido e eficiente para tarefas simples |
| **`sonnet[1m]`** | Usa Sonnet com uma [janela de contexto de 1 milhão de tokens](https://platform.claude.com/docs/pt/build-with-claude/context-windows#1m-token-context-window) para sessões longas. Sem efeito quando `sonnet` já se resolve para Sonnet 5 com sua janela 1M nativa; atrás de um [gateway LLM](/pt/llm-gateway), seleciona a janela 1M para Sonnet 5 |
| **`opus[1m]`** | Usa Opus com uma [janela de contexto de 1 milhão de tokens](https://platform.claude.com/docs/pt/build-with-claude/context-windows#1m-token-context-window) para sessões longas |
| **`opusplan`** | Modo especial que usa `opus` durante Plan Mode, depois muda para `sonnet` para execução |
Na API Anthropic, `opus` se resolve para Opus 4.8 e `sonnet` se resolve para Sonnet 5. Na [Claude Platform on AWS](/pt/claude-platform-on-aws), `opus` se resolve para Opus 4.7 e `sonnet` se resolve para Sonnet 4.6. No Bedrock, Vertex e Foundry, `opus` se resolve para Opus 4.6 e `sonnet` se resolve para Sonnet 4.5; modelos mais recentes estão disponíveis nesses provedores selecionando o nome completo do modelo explicitamente ou definindo `ANTHROPIC_DEFAULT_OPUS_MODEL` ou `ANTHROPIC_DEFAULT_SONNET_MODEL`.
Os aliases apontam para a versão recomendada para seu provedor e são atualizados ao longo do tempo. Para fixar uma versão específica, use o nome completo do modelo, por exemplo `claude-opus-4-8`, ou defina a variável de ambiente correspondente como `ANTHROPIC_DEFAULT_OPUS_MODEL`.
Sonnet 5 requer Claude Code v2.1.197 ou posterior. Opus 4.8 requer v2.1.154 ou posterior. Execute `claude update` para atualizar.
Trabalhar com Fable 5
[Claude Fable 5](https://platform.claude.com/docs/pt/about-claude/models/introducing-claude-fable-5-and-claude-mythos-5) é o modelo mais capaz no Claude Code, adequado para tarefas maiores que uma única sessão. Ele sustenta sessões autônomas longas, investiga antes de agir e verifica seu trabalho com mais frequência do que modelos menores.
Fable 5 não é o modelo padrão. Selecione-o com `/model fable`. Solicitações que seus classificadores de segurança sinalizam, mais frequentemente em domínios de cibersegurança e biologia, acionam [fallback automático de modelo](#automatic-model-fallback).
Para aproveitar ao máximo o Fable 5:
* **Descreva o resultado, não as etapas**: entregue-lhe o resultado que você deseja e deixe-o planejar o caminho. Para mantê-lo funcionando até que esse resultado se mantenha, [defina uma meta](/pt/goal).
* **Entregue-lhe problemas ambíguos**: investigações de causa raiz, depuração de interrupções e decisões de arquitetura são onde a investigação e verificação extras compensam.
* **Pule os lembretes de verificação**: ele verifica seu próprio trabalho com menos solicitação, portanto lembretes para testar ou verificar geralmente são desnecessários.
* **Dimensione tarefas maiores**: dê-lhe trabalho que você normalmente dividiria em pedaços. Ele mantém sessões longas sem perder o fio.
Fable 5 requer Claude Code v2.1.170 ou posterior. Versões mais antigas não mostram Fable 5 no seletor de modelo e não podem selecioná-lo. Execute `claude update` para atualizar. Fable 5 não está disponível sob [retenção zero de dados](/pt/zero-data-retention), onde o seletor `/model` o omite ou o mostra desabilitado.
Configurando seu modelo
Você pode configurar seu modelo de várias maneiras, listadas em ordem de prioridade:
1. **Durante a sessão**: use `/model ` para alternar imediatamente, ou execute `/model` sem argumentos para abrir o seletor. O seletor pede confirmação quando a conversa tem saída anterior, pois a próxima resposta relê o histórico completo sem contexto em cache
2. **Na inicialização**: inicie com `claude --model `
3. **Variável de ambiente**: defina `ANTHROPIC_MODEL=`
4. **Configurações**: configure permanentemente em seu arquivo de configurações usando o campo `model`
A partir da v2.1.153, `/model` salva sua escolha como padrão para novas sessões escrevendo o campo `model` em suas configurações de usuário. No seletor:
* `Enter`: alternar modelo e salvar como seu padrão
* `s`: alternar modelo apenas para esta sessão
Digitar `/model ` diretamente se comporta como `Enter`. As configurações de projeto e gerenciadas ainda têm precedência e são reaplicadas no próximo lançamento.
Na v2.1.144 até v2.1.152, `/model` se aplicava apenas à sessão atual e `d` no seletor salvava um padrão.
O sinalizador `--model` e a variável de ambiente `ANTHROPIC_MODEL` se aplicam apenas à sessão que você inicia com eles. Para executar modelos diferentes em terminais diferentes ao mesmo tempo, inicie cada um com seu próprio sinalizador `--model` em vez de alternar com `/model`.
As sessões retomadas iniciadas com `claude --resume`, `--continue` ou o seletor `/resume` mantêm o modelo que estavam usando quando a transcrição foi salva, independentemente da configuração `model` atual. Se esse modelo foi descontinuado ou é excluído por [`availableModels`](#restrict-model-selection), a sessão cai para a ordem de precedência normal. Isso evita que a escolha `/model` de outra sessão altere o modelo ao retomar.
Um modelo que você escolhe para o novo lançamento com `--model` ou `ANTHROPIC_MODEL` ainda tem precedência sobre o modelo restaurado. {/* min-version: 2.1.195 */}A partir da v2.1.195, também tem uma variável da família [`ANTHROPIC_DEFAULT_OPUS_MODEL`](#environment-variables).
Quando o modelo ativo na inicialização vem das configurações do projeto ou gerenciadas em vez de sua própria seleção, o cabeçalho de inicialização mostra qual arquivo de configurações o definiu. Execute `/model` para substituir; a configuração do projeto ou gerenciada reaplicada no próximo lançamento.
Quando o modelo solicitado tem uma data de aposentadoria programada ou é automaticamente remapeado para uma versão mais recente, Claude Code mostra um aviso que nomeia o modelo solicitado. As sessões interativas o mostram como um aviso de inicialização. A partir da v2.1.182, o mesmo aviso é escrito em stderr no [modo não interativo](/pt/headless) ao usar o formato de saída de texto padrão. A verificação também cobre um `model` definido no [frontmatter de subagentos](/pt/sub-agents). O aviso stderr é suprimido para `--output-format json` e `stream-json`; leia o modelo real do campo `modelUsage` da [mensagem de resultado](/pt/headless#get-structured-output) em vez disso.
Exemplo de uso:
```bash theme={null}
# Iniciar com Opus
claude --model opus
# Alternar para Sonnet durante a sessão
/model sonnet
```
Exemplo de arquivo de configurações:
```json theme={null}
{
"permissions": {
...
},
"model": "opus"
}
```
Restringir seleção de modelo
Os administradores corporativos podem usar `availableModels` em [configurações gerenciadas ou de política](/pt/settings#settings-files) para restringir quais modelos os usuários podem selecionar. As entradas correspondem a uma família de modelo como `sonnet`, um prefixo de versão como `claude-sonnet-4-5`, ou um ID de modelo completo como `claude-sonnet-4-5-20250929`.
Quando `availableModels` é definido, a lista de permissões se aplica em todos os lugares onde um usuário pode especificar um modelo:
* **Modelo de sessão principal**: `/model`, o sinalizador `--model`, a variável de ambiente `ANTHROPIC_MODEL`, a configuração `model` e o modelo restaurado ao [retomar uma sessão](#setting-your-model)
* **Resolução de alias**: {/* min-version: 2.1.176 */}as variáveis de ambiente `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL` e `ANTHROPIC_DEFAULT_FABLE_MODEL` não podem redirecionar um alias permitido para um modelo fora da lista
* **Modo rápido**: {/* min-version: 2.1.176 */}`/fast` recusa alternar quando isso implicaria mudar implicitamente para um modelo Opus fora da lista, com a mensagem "não está nos modelos permitidos da sua organização"
* **Modelos de subagente**: o campo `model` em [subagente](/pt/sub-agents#choose-a-model) frontmatter, o parâmetro `model` da ferramenta Agent, o seletor de modelo em `/agents` e `CLAUDE_CODE_SUBAGENT_MODEL`
* **Modelo de skill e comando**: o frontmatter `model` em [skills e comandos](/pt/skills)
* **Modelo de advisor**: a configuração [`advisorModel`](/pt/advisor) configurada e o sinalizador `--advisor`
* **Modelo de agente de fundo**: o modelo selecionado no [seletor de dispatch](/pt/agent-view)
Alternar para um modelo bloqueado com `/model` é rejeitado com um erro, enquanto um sinalizador `--model` bloqueado, valor `ANTHROPIC_MODEL` ou configuração `model` é substituído na inicialização com um aviso nomeando tanto o modelo solicitado quanto o substituído, e a sessão é iniciada no modelo padrão. Uma substituição de subagente, skill ou comando bloqueada volta para o modelo herdado ou padrão em vez de falhar na solicitação; uma configuração `advisorModel` bloqueada desativa o advisor para a sessão, enquanto um sinalizador `--advisor` bloqueado sai com um erro no lançamento. Os modelos excluídos são ocultados do seletor `/model`.
As mudanças automáticas de modelo são verificadas da mesma forma: elementos de uma [cadeia de modelo de fallback](#fallback-model-chains) fora da lista de permissões são descartados, uma atualização de modo de plano como [`opusplan`](#opusplan-model-setting) para um modelo excluído é ignorada para que o planejamento continue no modelo da sessão, e um [fallback automático de modelo](#automatic-model-fallback) cujo alvo é excluído não é executado, portanto a solicitação sinalizada termina com uma recusa. Habilitar [modo rápido](/pt/fast-mode) é recusado quando o modelo em que a sessão seria executada depois está fora da lista de permissões.
```json theme={null}
{
"availableModels": ["sonnet", "haiku"]
}
```
Cobertura de superfície
Cada superfície impõe a lista de permissões que recebe. Qual mecanismo de entrega alcança cada superfície difere:
| Mecanismo de entrega | CLI e IDE | Sessões locais do Desktop | Sessões web, mobile e cloud | Agent SDK e não-interativo | Cowork |
| :------------------------------------------------------------------------------------------------- | :-------- | :------------------------ | :-------------------------- | :------------------------- | :---------------------- |
| [Configurações gerenciadas pelo servidor](/pt/server-managed-settings) do console de administração | Imposto | Imposto | Imposto | Imposto | Não entregue |
| [Arquivos de configurações gerenciadas ou MDM](/pt/settings#settings-files) | Imposto | Imposto | Não entregue | Imposto | Imposto onde implantado |
* Sessões em nuvem, em [Claude Code na web](/pt/claude-code-on-the-web) ou no aplicativo Desktop, são executadas em VMs gerenciadas pela Anthropic: as configurações implantadas no seu dispositivo não as alcançam, portanto entregue a lista de permissões através de configurações gerenciadas pelo servidor. Uma mudança de modelo no meio da sessão em uma sessão em nuvem é rejeitada quando o modelo solicitado é excluído pela lista de permissões. A rejeição do lado do servidor na criação da sessão se aplica a [restrições de modelo da organização](#organization-model-restrictions), não à chave de configurações `availableModels`.
* Cowork, a aba de trabalho agentic no aplicativo Claude Desktop, não é uma superfície Claude Code e não recebe configurações gerenciadas pelo servidor por design. Um arquivo de configurações gerenciadas se aplica a sessões Cowork quando está presente onde a sessão é executada; sessões Cowork remotas são executadas em VMs gerenciadas pela Anthropic, onde um arquivo implantado no dispositivo não está presente.
* Sessões em [provedores de terceiros](/pt/server-managed-settings#platform-availability) como Bedrock, Vertex AI, Foundry e [Claude Platform on AWS](/pt/claude-platform-on-aws) não recebem configurações gerenciadas pelo servidor, portanto entregue a lista de permissões através de arquivos de configurações gerenciadas ou MDM lá.
* A entrega gerenciada pelo servidor também requer que a sessão se autentique com um login de organização ou uma chave de API configurada diretamente. Frotas que geram chaves apenas através de um script [`apiKeyHelper`](/pt/settings#available-settings) devem entregar a lista de permissões através de arquivos de configurações gerenciadas ou MDM.
* A aba Desktop Code também hospeda [sessões SSH](/pt/desktop#ssh-sessions), que leem o arquivo de configurações gerenciadas do host remoto em que são executadas. Veja [Configurações gerenciadas do Desktop](/pt/desktop#managed-settings).
* Os seletores de modelo em claude.ai e no aplicativo Desktop ocultam ou desabilitam modelos excluídos pela lista de permissões da sua organização. O estado do seletor é uma conveniência para os usuários; a imposição acontece na sessão.
Comportamento do modelo padrão
A opção Padrão no seletor de modelo não é afetada por `availableModels` a menos que [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model) também esteja definido. Por si só, `availableModels` deixa Padrão disponível, resolvendo para o padrão de tempo de execução do sistema [baseado no nível de assinatura do usuário](#default-model-setting). Se o padrão do nível é um modelo que você pretende restringir, defina `enforceAvailableModels` também.
Um array `availableModels` vazio nunca ativa a imposição do modelo Padrão: com `availableModels: []`, as seleções de modelo nomeadas são bloqueadas, mas o modelo Padrão para o tipo de conta permanece utilizável independentemente de `enforceAvailableModels`.
Impor a lista de permissões para o modelo Padrão
Defina `enforceAvailableModels: true` junto com um `availableModels` não vazio em configurações gerenciadas para estender a lista de permissões à opção Padrão. Isso requer Claude Code v2.1.175 ou posterior.
```json theme={null}
{
"availableModels": ["sonnet", "haiku"],
"enforceAvailableModels": true
}
```
Quando o modelo padrão para o tipo de conta do usuário não está na lista de permissões, a opção Padrão se resolve para a primeira entrada `availableModels` que nomeia um modelo permitido e disponível, e a linha Padrão do seletor `/model` mostra esse modelo. Isso se aplica em todos os lugares onde o padrão é alcançado: inicialização da sessão, seleção de Padrão em `/model`, a palavra-chave `"default"` em [cadeias de modelo de fallback](#fallback-model-chains) e o fallback usado quando uma seleção excluída é descartada.
`enforceAvailableModels` não tem efeito quando `availableModels` não está definido ou está vazio: com `availableModels: []`, o modelo Padrão para o tipo de conta permanece utilizável, portanto a configuração não pode bloquear os usuários de cada modelo. Quando `availableModels` é não vazio, mas nenhuma entrada se resolve para um modelo permitido e disponível, a imposição se degrada e Padrão cai para o padrão do tipo de conta, com um aviso visível apenas em `--debug`. Mantenha pelo menos uma entrada garantidamente disponível na lista para evitar isso.
Implante ambas as chaves na [fonte gerenciada de maior precedência](/pt/settings#settings-precedence): as fontes gerenciadas implantadas pelo administrador não se mesclam, portanto um par colocado em um arquivo de configurações gerenciadas é ignorado quando o console de administração entrega qualquer configuração.
Controlar o modelo em que os usuários executam
A configuração `model` é uma seleção inicial, não uma imposição. Ela define qual modelo está ativo quando uma sessão é iniciada, mas os usuários ainda podem abrir `/model` e escolher Padrão, que se resolve para o padrão do sistema para seu nível, independentemente do que `model` está definido, a menos que [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model) o redirecione.
Para controlar totalmente a experiência do modelo, combine estas configurações:
* **`availableModels`**: restringe para quais modelos nomeados os usuários podem alternar
* **`enforceAvailableModels`**: estende a lista de permissões `availableModels` à opção Padrão, para que Padrão não possa se resolver para um modelo fora da lista
* **`model`**: define a seleção de modelo inicial quando uma sessão é iniciada
* **`ANTHROPIC_DEFAULT_SONNET_MODEL`** / **`ANTHROPIC_DEFAULT_OPUS_MODEL`** / **`ANTHROPIC_DEFAULT_HAIKU_MODEL`** / **`ANTHROPIC_DEFAULT_FABLE_MODEL`**: controlam para o que a opção Padrão e os aliases `sonnet`, `opus`, `haiku` e `fable` se resolvem
Este exemplo inicia os usuários em Sonnet 4.5, limita o seletor a Sonnet e Haiku, e garante que Padrão se resolve para um modelo na lista de permissões em vez do padrão do nível:
```json theme={null}
{
"model": "claude-sonnet-4-5",
"availableModels": ["claude-sonnet-4-5", "haiku"],
"enforceAvailableModels": true,
"env": {
"ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-5"
}
}
```
Sem `enforceAvailableModels` ou o bloco `env`, um usuário que seleciona Padrão no seletor obteria a versão mais recente para seu nível, contornando a fixação de versão em `model` e `availableModels`. As duas configurações cobrem escopos diferentes: `enforceAvailableModels` faz Padrão obedecer à lista de permissões, enquanto o bloco `env` fixa qual versão um alias permitido como `sonnet` se resolve. Use `enforceAvailableModels` sozinho quando restringir famílias de modelo é suficiente; adicione o bloco `env` quando você também precisar fixar uma versão específica.
Comportamento de mesclagem
Quando a [fonte de configurações gerenciadas de maior precedência](/pt/server-managed-settings#settings-precedence) define `availableModels`, apenas essa lista se aplica: as entradas em configurações de usuário, projeto ou local não podem estendê-la, e as fontes gerenciadas implantadas pelo administrador não se mesclam entre si, portanto uma lista implantada em um arquivo de configurações gerenciadas é ignorada quando as configurações gerenciadas pelo servidor entregam qualquer chave. Caso contrário, as listas de configurações de usuário, projeto e local são [concatenadas e desduplicadas](/pt/settings#settings-precedence) como outras configurações de array. {/* min-version: 2.1.175 */}A partir de Claude Code v2.1.175, a lista gerenciada substitui entradas de menor precedência; versões anteriores as mesclam.
Dentro da lista efetiva, uma entrada nomeando um modelo específico em uma família, seja um prefixo de versão ou um ID de modelo completo, desativa a entrada de wildcard dessa família: `["sonnet", "claude-sonnet-4-5"]` permite apenas versões Sonnet 4.5, não cada modelo Sonnet.
IDs de modelo Mantle
Quando o [endpoint Bedrock Mantle](/pt/amazon-bedrock#use-the-mantle-endpoint) está habilitado, as entradas em `availableModels` que começam com `anthropic.` são adicionadas ao seletor `/model` como opções personalizadas e roteadas para o endpoint Mantle. Esta é uma exceção à correspondência de alias descrita em [Fixar modelos para implantações de terceiros](#pin-models-for-third-party-deployments). A configuração ainda restringe o seletor às entradas listadas, e um ID Mantle incorpora um nome de família, portanto conta como uma entrada específica e desativa o wildcard dessa família: junto com qualquer ID Mantle, liste os prefixos de versão ou IDs completos que você deseja manter selecionáveis. Veja [Comportamento de mesclagem](#merge-behavior).
Restrições de modelo da organização
Os administradores da organização restringem quais modelos os membros podem executar desabilitando modelos individuais no Console Claude. Use este botão do Console em vez de `availableModels` quando seus membros se autenticam através da API Anthropic e você deseja um único switch em toda a organização sem implantar arquivos de configurações. Esta restrição é entregue com os direitos da conta quando Claude Code se autentica, separada de qualquer lista `availableModels` em configurações, e o servidor impõe a mesma restrição independentemente quando uma sessão é criada. Requer Claude Code v2.1.187 ou posterior.
Um modelo restrito é ocultado do seletor `/model`. Selecioná-lo pelo nome com `--model`, a variável de ambiente `ANTHROPIC_MODEL` ou a configuração `model` mostra o aviso `Model "" is restricted by your organization's settings. Using instead.` e a sessão é iniciada em um modelo permitido. Digitar `/model ` para um modelo restrito é rejeitado com `Model '' is restricted by your organization's settings. Run /model to choose a different model.` e a sessão mantém seu modelo atual.
Os dois mecanismos se compõem: um modelo é selecionável apenas quando é permitido por `availableModels` e não é restrito pela organização. As restrições da organização são entregues a sessões na API Anthropic e implantações de [gateway LLM](/pt/llm-gateway). Sessões em Bedrock, Vertex AI, Foundry e Claude Platform on AWS não as recebem, portanto use `availableModels` nesses provedores.
Comportamento especial do modelo
Configuração do modelo `default`
O comportamento de `default` depende do tipo de sua conta:
* **Max, Team Premium, Enterprise pagamento conforme o uso e API Anthropic**: padrão para Opus 4.8
* **Claude Platform na AWS**: padrão para Opus 4.7
* **Pro, Team Standard e assentos de assinatura Enterprise**: padrão para Sonnet 5
* **Bedrock, Vertex e Foundry**: padrão para Sonnet 4.5
Enterprise pagamento conforme o uso significa uma organização Enterprise cobrada por uso em vez de por assento de assinatura.
Quando as configurações gerenciadas [aplicam a lista de permissões para o modelo Padrão](#enforce-the-allowlist-for-the-default-model) e o padrão do tipo de conta não está em `availableModels`, `default` resolve para o Padrão aplicado em vez do padrão do tipo de conta acima.
Fable 5 não é o modelo padrão em nenhum tipo de conta. As sessões usam Fable 5 apenas depois que você o escolhe, com `/model fable`, uma configuração `model` ou o alias `best` onde Fable 5 está disponível. Escolhê-lo com `/model` o salva como o modelo selecionado em suas configurações de usuário, portanto as sessões posteriores começam em Fable 5 até que você altere os modelos.
Configuração do modelo `opusplan`
O alias de modelo `opusplan` fornece uma abordagem híbrida automatizada:
* **Em Plan Mode**: usa `opus` para raciocínio complexo e decisões de arquitetura
* **Em modo de execução**: muda automaticamente para `sonnet` para geração de código e implementação
Isso oferece o melhor dos dois mundos: o raciocínio superior do Opus para planejamento e a eficiência do Sonnet para execução.
A fase Opus do Plan Mode usa a mesma janela de contexto da configuração do modelo `opus`. Nos níveis de assinatura onde Opus é [automaticamente atualizado para contexto 1M](#extended-context), `opusplan` recebe a atualização em Plan Mode também. Para forçar contexto 1M para ambas as fases quando você não está em um nível de atualização automática, defina o modelo para `opusplan[1m]`.
Quando [`availableModels`](#restrict-model-selection) exclui Opus, `opusplan` permanece em Sonnet em Plan Mode em vez de alternar. Da mesma forma, uma sessão Haiku que normalmente seria atualizada para Sonnet em Plan Mode permanece em Haiku quando Sonnet é excluído.
Para uma abordagem híbrida onde Claude decide no meio da tarefa quando consultar um segundo modelo em vez de alternar no limite do plano, veja a [ferramenta advisor](/pt/advisor).
Cadeias de modelo de fallback
Quando o modelo primário está sobrecarregado, indisponível ou retorna outro erro de servidor não retentável, Claude Code pode alternar para um modelo de fallback em vez de falhar na solicitação. Erros de autenticação, faturamento, limite de taxa, tamanho de solicitação e transporte nunca acionam uma alternância; esses seguem sua manipulação de erro e retry normal.
Configure um ou mais modelos de fallback e Claude Code os tenta em ordem, mostrando um aviso quando alterna. A alternância dura apenas para a volta atual, portanto sua próxima mensagem tenta o modelo primário primeiro novamente. As cadeias são limitadas a três modelos após remoção de duplicatas, e entradas extras são ignoradas.
Defina uma cadeia para uma sessão com o sinalizador `--fallback-model`, que aceita uma lista separada por vírgulas:
```bash theme={null}
claude --fallback-model sonnet,haiku
```
Para persistir uma cadeia entre sessões, defina `fallbackModel` em [configurações](/pt/settings) como uma matriz:
```json theme={null}
{
"fallbackModel": ["claude-sonnet-5", "claude-haiku-4-5"]
}
```
O sinalizador `--fallback-model` tem precedência sobre a configuração `fallbackModel`. Cada elemento aceita um nome de modelo ou alias, e `"default"` se expande para o modelo padrão.
Dois casos fazem um elemento ser ignorado:
* **Modelo indisponível**: um modelo que não pode ser alcançado, como um modelo aposentado fixado em configurações, é ignorado e Claude Code continua para o próximo elemento.
* **Fora da lista de permissões**: um elemento não permitido por [`availableModels`](#restrict-model-selection) é descartado quando a cadeia é lida e nunca é tentado.
Fallback automático de modelo
Esta seção cobre fallback baseado em conteúdo de Fable 5. Para fallback baseado em disponibilidade quando um modelo está sobrecarregado ou indisponível, veja [Cadeias de modelo de fallback](#fallback-model-chains).
Fable 5 é executado com classificadores de segurança para conteúdo de cibersegurança e biologia. Quando um classificador sinaliza uma solicitação, Claude Code executa novamente essa solicitação no modelo Opus padrão e mostra um aviso na transcrição: Opus 4.8 na API Anthropic e implantações de [gateway LLM](/pt/llm-gateway), ou Opus 4.7 na [Claude Platform na AWS](/pt/claude-platform-on-aws).
A sessão então continua nesse modelo Opus. Para retornar a Fable 5, execute `/model fable`.
O alvo de fallback é verificado contra [`availableModels`](#restrict-model-selection). Quando é bloqueado, nenhum fallback ocorre. A recusa aparece como um erro normal e o modelo da sessão permanece inalterado.
Verificar o que acionou fallback
O fallback pode ser acionado na primeira solicitação de uma sessão, antes de você enviar algo incomum, porque a primeira solicitação carrega contexto do espaço de trabalho, como seu conteúdo CLAUDE.md e status do git. Um repositório que contém material de segurança ou biologia pode acionar o classificador apenas nesse contexto.
Para verificar se as personalizações são o gatilho, inicie uma sessão com `claude --safe-mode`, que desabilita personalizações como CLAUDE.md, skills, servidores MCP e hooks. O status do git e nomes de diretórios não são personalizações e ainda estão inclusos.
Perguntar antes de alternar
Para decidir o que acontece cada vez que uma solicitação é sinalizada, em vez de alternar automaticamente, execute `/config` e desative "switch models when a message is flagged". Uma solicitação sinalizada então pausa a sessão com duas opções: alternar para o modelo Opus ou editar o prompt e tentar novamente em Fable 5.
Alguns casos se comportam diferentemente:
* Se ambos os modelos sinalizarem a mesma solicitação, você pode editar o prompt e tentar novamente, ou iniciar uma nova sessão.
* Em sessões móveis [Claude Code na web](/pt/claude-code-on-the-web), editar e tentar novamente não é suportado. Alterne modelos ou continue a sessão de um navegador de desktop ou do aplicativo de desktop.
* Em [modo não interativo](/pt/cli-reference#cli-flags) e integrações SDK que não podem mostrar o prompt, uma solicitação sinalizada encerra a volta com uma recusa em vez disso.
* Quando o alvo de fallback é bloqueado por [`availableModels`](#restrict-model-selection), o prompt não é mostrado. A solicitação sinalizada termina com a recusa, o mesmo que fallback automático quando o alvo é bloqueado.
Habilitar fallback em Bedrock, Vertex AI e Foundry
Em [Amazon Bedrock](/pt/amazon-bedrock), [Google Vertex AI](/pt/google-vertex-ai) e [Microsoft Foundry](/pt/microsoft-foundry), IDs de modelo são específicos do provedor, portanto o fallback automático opera apenas quando Claude Code pode identificar ambos os modelos envolvidos:
* Claude Code deve reconhecer o modelo atual como Fable 5: o ID do modelo contém `claude-fable-5`, corresponde ao valor de `ANTHROPIC_DEFAULT_FABLE_MODEL` ou é mapeado com [`modelOverrides`](#override-model-ids-per-version).
* O alvo de fallback deve resolver para um modelo Opus: o valor de `ANTHROPIC_DEFAULT_OPUS_MODEL` se definido, caso contrário uma entrada Opus 4.8 na lista de modelos do provedor.
Se qualquer modelo não puder ser identificado, Claude Code não alterna automaticamente. A solicitação sinalizada termina com uma mensagem de recusa, e você pode alternar modelos com [`/model`](#setting-your-model) e tentar novamente. Para habilitar fallback automático nesses provedores, defina `ANTHROPIC_DEFAULT_FABLE_MODEL` para seu ID de modelo Fable 5 e `ANTHROPIC_DEFAULT_OPUS_MODEL` para seu ID de modelo Opus 4.8.
Pesquisa de segurança e cargas de trabalho de biologia
Cargas de trabalho em segurança ofensiva ou biologia, incluindo testes de penetração, exercícios Capture the Flag (CTF) e bases de código adjacentes à biologia, acionam fallback frequentemente, geralmente na primeira solicitação. Para trabalho substancial de biologia, espere que quase todas as solicitações sejam redirecionadas.
Este é o roteamento esperado para esses domínios, não uma sinalização de conta. Se sua organização precisa de capacidade de classe Fable para este trabalho, pergunte ao seu time de contas Anthropic sobre programas de acesso confiável.
Ajustar nível de esforço
[Níveis de esforço](https://platform.claude.com/docs/pt/build-with-claude/effort) controlam raciocínio adaptativo, que permite que o modelo decida se e quanto pensar em cada etapa com base na complexidade da tarefa. Esforço menor é mais rápido e mais barato para tarefas diretas, enquanto esforço maior fornece raciocínio mais profundo para problemas complexos.
Os níveis de esforço disponíveis dependem do modelo. Modelos não listados aqui não suportam esforço:
| Modelo | Níveis |
| :---------------------------- | :-------------------------------------- |
| Fable 5 | `low`, `medium`, `high`, `xhigh`, `max` |
| Sonnet 5, Opus 4.8 e Opus 4.7 | `low`, `medium`, `high`, `xhigh`, `max` |
| Opus 4.6 e Sonnet 4.6 | `low`, `medium`, `high`, `max` |
Se você definir um nível que o modelo ativo não suporta, Claude Code volta para o nível mais alto suportado no ou abaixo do que você definiu. Por exemplo, `xhigh` é executado como `high` em Opus 4.6.
O esforço padrão é `high` em Fable 5, Sonnet 5, Opus 4.8, Opus 4.6 e Sonnet 4.6, e `xhigh` em Opus 4.7.
Quando você executa Fable 5, Opus 4.8 ou Opus 4.7 pela primeira vez, Claude Code aplica o esforço padrão desse modelo mesmo que você tenha definido anteriormente um nível diferente para outro modelo: `high` em Fable 5 e Opus 4.8, e `xhigh` em Opus 4.7. Execute `/effort` novamente para escolher um nível diferente após alternar.
`low`, `medium`, `high` e `xhigh` persistem entre sessões. `max` fornece o raciocínio mais profundo sem restrição no gasto de tokens e se aplica apenas à sessão atual, exceto quando definido através da variável de ambiente `CLAUDE_CODE_EFFORT_LEVEL`.
O menu `/effort` também oferece `ultracode`. Ultracode é uma configuração de Claude Code em vez de um nível de esforço do modelo: envia `xhigh` para o modelo e adicionalmente tem Claude orquestrar [fluxos de trabalho dinâmicos](/pt/workflows) para tarefas substanciais. Se aplica apenas à sessão atual. Defina através de `/effort`, ou passe `"ultracode": true` via `--settings` ou uma solicitação de controle do Agent SDK. Não faz parte da configuração `effortLevel`, do sinalizador `--effort` ou `CLAUDE_CODE_EFFORT_LEVEL`.
Escolher um nível de esforço
Cada nível negocia gasto de tokens contra capacidade. O padrão é adequado para a maioria das tarefas de codificação; ajuste quando você quiser um equilíbrio diferente.
| Nível | Quando usá-lo |
| :---------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `low` | Reserve para tarefas curtas, delimitadas, sensíveis à latência que não são sensíveis à inteligência |
| `medium` | Reduz o uso de tokens para trabalho sensível a custos que pode fazer concessões em inteligência |
| `high` | Equilibra o uso de tokens e inteligência. Padrão em Fable 5, Sonnet 5, Opus 4.8, Opus 4.6 e Sonnet 4.6 |
| `xhigh` | Raciocínio mais profundo com gasto de tokens mais alto. Padrão em Opus 4.7 |
| `max` | Pode melhorar o desempenho em tarefas exigentes, mas pode mostrar retornos decrescentes e é propenso a pensar demais. Teste antes de adotar amplamente |
| `ultracode` | Uma configuração de Claude Code que planeja um [fluxo de trabalho dinâmico](/pt/workflows) para cada tarefa substancial com raciocínio `xhigh` por mensagem. Apenas de sessão |
A escala de esforço é calibrada por modelo, portanto o mesmo nome de nível não representa o mesmo valor subjacente entre modelos.
Usar ultrathink para raciocínio profundo único
Inclua `ultrathink` em qualquer lugar em seu prompt para solicitar raciocínio mais profundo nessa volta sem alterar sua configuração de esforço de sessão. Claude Code reconhece a palavra-chave e adiciona uma instrução no contexto. O nível de esforço enviado para a API permanece inalterado. Outras frases como "think", "think hard" e "think more" são passadas como texto de prompt ordinário e não são reconhecidas como palavras-chave.
Definir o nível de esforço
Você pode alterar o esforço através de qualquer um dos seguintes:
* **`/effort`**: execute `/effort` sem argumentos para abrir um controle deslizante interativo, `/effort` seguido por um nome de nível para defini-lo diretamente, ou `/effort auto` para redefinir para o padrão do modelo
* **Em `/model`**: use as teclas de seta esquerda/direita para ajustar o controle deslizante de esforço ao selecionar um modelo
* **Sinalizador `--effort`**: passe um nome de nível para defini-lo para uma única sessão ao iniciar Claude Code
* **Variável de ambiente**: defina `CLAUDE_CODE_EFFORT_LEVEL` para um nome de nível ou `auto`
* **Configurações**: defina `effortLevel` para `low`, `medium`, `high` ou `xhigh` em seu arquivo de configurações. `max` e `ultracode` são [apenas de sessão](#adjust-effort-level) e não são aceitos aqui
* **Frontmatter de skill e subagent**: defina `effort` em um arquivo markdown de [skill](/pt/skills#frontmatter-reference) ou [subagent](/pt/sub-agents#supported-frontmatter-fields) para substituir o nível de esforço quando esse skill ou subagent é executado
A variável de ambiente tem precedência sobre todos os outros métodos, depois seu nível configurado, depois o padrão do modelo. O esforço de frontmatter se aplica quando esse skill ou subagent está ativo, substituindo o nível de sessão, mas não a variável de ambiente.
O controle deslizante de esforço aparece em `/model` quando um modelo suportado é selecionado. O nível de esforço atual também é exibido ao lado do logo e spinner, por exemplo "with low effort", para que você possa confirmar qual configuração está ativa sem abrir `/model`.
Raciocínio adaptativo e orçamentos de pensamento fixos
O raciocínio adaptativo torna o pensamento opcional em cada etapa, portanto Claude pode responder mais rápido a prompts rotineiros e reservar pensamento mais profundo para etapas que se beneficiam dele. Se você quiser que Claude pense mais ou menos frequentemente do que o nível atual produz, você pode dizer isso diretamente em seu prompt ou em `CLAUDE.md`; o modelo responde a essa orientação dentro de sua configuração de esforço.
Fable 5, Sonnet 5 e Opus 4.7 e posterior sempre usam raciocínio adaptativo. O modo de orçamento de pensamento fixo e `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` não se aplicam a eles.
Em Opus 4.6 e Sonnet 4.6, você pode definir `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` para reverter para o orçamento de pensamento fixo anterior controlado por `MAX_THINKING_TOKENS`. Veja [variáveis de ambiente](/pt/env-vars).
Pensamento estendido
Pensamento estendido é o raciocínio que Claude emite antes de responder. Em modelos que suportam [raciocínio adaptativo](#adjust-effort-level), o nível de esforço é o controle principal para quanto pensamento acontece; as configurações abaixo ativam ou desativam o pensamento e controlam como ele é exibido.
| Controle | Como defini-lo |
| :--------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Alternar para a sessão atual | Pressione `Option+T` no macOS ou `Alt+T` no Windows e Linux |
| Definir o padrão global | Execute `/config` e alterne o modo de pensamento. Salvo como `alwaysThinkingEnabled` em `~/.claude/settings.json` |
| Desabilitar independentemente do esforço | Defina [`MAX_THINKING_TOKENS=0`](/pt/env-vars), que desativa o pensamento na API Anthropic exceto em Fable 5. Em [provedores de terceiros](/pt/third-party-integrations) isso omite o parâmetro `thinking` em vez disso, e modelos de raciocínio adaptativo ainda podem pensar. Outros valores se aplicam apenas com um [orçamento de pensamento fixo](#adaptive-reasoning-and-fixed-thinking-budgets) |
O pensamento não pode ser desativado em Fable 5. O alternador de sessão, `alwaysThinkingEnabled` e `MAX_THINKING_TOKENS=0` não têm efeito lá, e Fable 5 decide por etapa quanto pensar com base no nível de esforço.
A saída de pensamento é recolhida por padrão. Pressione `Ctrl+O` para alternar o modo verboso e ver o raciocínio como texto em itálico cinzento. Sessões interativas na API Anthropic recebem blocos de pensamento redigidos por padrão, portanto defina `showThinkingSummaries: true` em [configurações](/pt/settings) se você quiser os resumos completos disponíveis quando expandir. Você é cobrado por todos os tokens de pensamento gerados, mesmo quando recolhidos ou redigidos.
Contexto estendido
Fable 5, Sonnet 5, Opus 4.6 e posterior, e Sonnet 4.6, suportam uma [janela de contexto de 1 milhão de tokens](https://platform.claude.com/docs/pt/build-with-claude/context-windows#1m-token-context-window) para sessões longas com grandes bases de código.
A disponibilidade varia por modelo e plano. Na API Anthropic, Fable 5, Sonnet 5, Opus 4.8 e Opus 4.7 sempre são executados com a janela 1M. Nos planos Max, Team e Enterprise, Opus é automaticamente atualizado para contexto 1M sem configuração adicional. Isso se aplica aos assentos Team Standard e Team Premium. Sonnet 4.6 com contexto 1M não faz parte da atualização automática e requer [créditos de uso](https://support.claude.com/pt/articles/12429409-extra-usage-for-paid-claude-plans) em todos os planos de assinatura, incluindo Max.
| Plano | Opus com contexto 1M | Sonnet 4.6 com contexto 1M |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Max, Team e Enterprise | Incluído na assinatura | Requer [créditos de uso](https://support.claude.com/pt/articles/12429409-extra-usage-for-paid-claude-plans) |
| Pro | Requer [créditos de uso](https://support.claude.com/pt/articles/12429409-extra-usage-for-paid-claude-plans) | Requer [créditos de uso](https://support.claude.com/pt/articles/12429409-extra-usage-for-paid-claude-plans) |
| API e pagamento conforme o uso | Acesso completo | Acesso completo |
Para desabilitar completamente o contexto 1M, defina `CLAUDE_CODE_DISABLE_1M_CONTEXT=1`. Isso remove variantes de modelo 1M do seletor de modelo. Veja [variáveis de ambiente](/pt/env-vars).
A janela de contexto 1M usa preços de modelo padrão sem prêmio para tokens além de 200K. Para planos onde o contexto estendido está incluído em sua assinatura, o uso permanece coberto por sua assinatura. Para planos que acessam contexto estendido através de créditos de uso, os tokens são cobrados para créditos de uso.
Se sua conta suporta contexto 1M, a opção aparece no seletor de modelo (`/model`) nas versões mais recentes do Claude Code. Se você não a vir, tente reiniciar sua sessão.
Você também pode usar o sufixo `[1m]` com aliases de modelo ou nomes de modelo completos:
```bash theme={null}
# Use o alias opus[1m] ou sonnet[1m]
/model opus[1m]
/model sonnet[1m]
# Ou anexe [1m] a um nome de modelo completo
/model claude-opus-4-8[1m]
```
Janela de contexto do Sonnet 5
Na API Anthropic, Sonnet 5 sempre é executado com a janela de contexto 1M. Não há variante de 200K, nenhum sufixo `[1m]` para selecionar e nenhum crédito de uso necessário em qualquer plano. As sessões fazem compactação automática antes que a janela encha, em cerca de 967K tokens por padrão; defina [`CLAUDE_CODE_AUTO_COMPACT_WINDOW`](/pt/env-vars) para escolher um limite diferente.
Duas configurações orçam a janela em 200K em vez disso e fazem compactação automática nesse limite:
* **Gateway LLM**: quando `ANTHROPIC_BASE_URL` aponta para um [gateway](/pt/llm-gateway), Claude Code não pode verificar o suporte a 1M. Para usar a janela completa, selecione Sonnet 5 (1M context) no seletor de modelo, que mapeia para `sonnet[1m]`.
* **`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`**: trata sessões Sonnet 5 como tendo uma janela de 200K, para implantações que precisam limitar o contexto.
Verificando seu modelo atual
Você pode ver qual modelo está usando atualmente em dois lugares:
* Na [linha de status](/pt/statusline), se você tiver uma configurada
* Em `/status`, que também exibe as informações de sua conta
Adicionar uma opção de modelo personalizado
Use `ANTHROPIC_CUSTOM_MODEL_OPTION` para adicionar uma única entrada personalizada ao seletor `/model` sem substituir os aliases integrados. Isso é útil para testar IDs de modelo que Claude Code não lista por padrão. Para implantações de gateway LLM, Claude Code pode preencher o seletor a partir do endpoint `/v1/models` do gateway quando `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` está definido, portanto essa variável é necessária apenas quando a descoberta está desabilitada ou não retorna o modelo que você deseja. Consulte [descoberta de modelo de gateway](/pt/llm-gateway-protocol#model-discovery).
Este exemplo define todas as três variáveis para tornar uma implantação Opus roteada por gateway selecionável:
```bash theme={null}
export ANTHROPIC_CUSTOM_MODEL_OPTION="my-gateway/claude-opus-4-8"
export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="Opus via Gateway"
export ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION="Custom deployment routed through the internal LLM gateway"
```
A entrada personalizada aparece na parte inferior do seletor `/model`. `ANTHROPIC_CUSTOM_MODEL_OPTION_NAME` e `ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION` são opcionais. Se omitidos, o ID do modelo é usado como o nome e a descrição padrão é `Custom model ()`.
Claude Code ignora a validação para o ID do modelo definido em `ANTHROPIC_CUSTOM_MODEL_OPTION`, portanto você pode usar qualquer string que seu endpoint de API aceite. Quando [`availableModels`](#restrict-model-selection) está definido, inclua o ID do modelo personalizado na lista de permissões também: a entrada personalizada é filtrada do seletor e uma seleção `--model` dela é rejeitada como qualquer outro modelo excluído. Um ID personalizado que incorpora um nome de família, como `my-gateway/claude-opus-4-8`, conta como uma entrada específica para essa família e desabilita seu curinga, portanto também liste as versões que você pretende manter selecionáveis. Consulte [Comportamento de mesclagem](#merge-behavior).
Variáveis de ambiente
Você pode usar as seguintes variáveis de ambiente para controlar os nomes de modelo para os quais os aliases mapeiam. Cada valor deve ser um nome de modelo completo, ou o identificador equivalente para seu provedor de API.
| Variável de ambiente | Descrição |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ANTHROPIC_DEFAULT_FABLE_MODEL` | O modelo a usar para `fable`, e o ID de modelo que Claude Code reconhece como Fable 5 para [fallback automático de modelo](#automatic-model-fallback) em provedores de terceiros |
| `ANTHROPIC_DEFAULT_OPUS_MODEL` | O modelo a usar para `opus`, ou para `opusplan` quando Plan Mode está ativo. |
| `ANTHROPIC_DEFAULT_SONNET_MODEL` | O modelo a usar para `sonnet`, ou para `opusplan` quando Plan Mode não está ativo. |
| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | O modelo a usar para `haiku`, ou [funcionalidade de fundo](/pt/costs#background-token-usage) |
| `CLAUDE_CODE_SUBAGENT_MODEL` | O modelo a usar para todos os [subagents](/pt/sub-agents#choose-a-model) e [agent teams](/pt/agent-teams). Substitui tanto o parâmetro `model` por invocação quanto o frontmatter `model` da definição do subagent. Defina como `inherit` para usar resolução de modelo normal em vez disso |
Nota: `ANTHROPIC_SMALL_FAST_MODEL` está descontinuado em favor de `ANTHROPIC_DEFAULT_HAIKU_MODEL`.
Fixar modelos para implantações de terceiros
Ao implantar Claude Code através de [Bedrock](/pt/amazon-bedrock), [Vertex AI](/pt/google-vertex-ai), [Foundry](/pt/microsoft-foundry) ou [Claude Platform on AWS](/pt/claude-platform-on-aws), fixe versões de modelo antes de lançar para usuários.
Sem fixação, Claude Code usa aliases de modelo como `fable`, `opus`, `sonnet` e `haiku` que resolvem para um ID de modelo padrão integrado para cada provedor. Esse padrão pode ficar atrás da versão mais recente do Anthropic, e o modelo para o qual aponta pode ainda não estar habilitado na conta de um usuário. Quando o padrão não está disponível, os usuários de Bedrock e Vertex AI veem um aviso e voltam para a versão anterior para essa sessão, enquanto os usuários de Foundry veem erros porque Foundry não tem verificação de inicialização equivalente.
Defina as variáveis de ambiente de modelo para IDs de versão específicos como parte de sua configuração inicial. Fixar permite que você controle quando seus usuários se movem para um novo modelo.
Use as seguintes variáveis de ambiente com IDs de modelo específicos de versão para seu provedor:
| Provedor | Exemplo |
| :-------- | :------------------------------------------------------------------- |
| Bedrock | `export ANTHROPIC_DEFAULT_OPUS_MODEL='us.anthropic.claude-opus-4-8'` |
| Vertex AI | `export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'` |
| Foundry | `export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'` |
Aplique o mesmo padrão para `ANTHROPIC_DEFAULT_FABLE_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL` e `ANTHROPIC_DEFAULT_HAIKU_MODEL`. Para IDs de modelo atuais e legados em todos os provedores, veja [Visão geral de modelos](https://platform.claude.com/docs/en/about-claude/models/overview). Para atualizar usuários para uma nova versão de modelo, atualize essas variáveis de ambiente e reimplante.
Para habilitar [contexto estendido](#extended-context) para um modelo fixado, anexe `[1m]` ao ID do modelo em `ANTHROPIC_DEFAULT_OPUS_MODEL` ou `ANTHROPIC_DEFAULT_SONNET_MODEL`:
```bash theme={null}
export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8[1m]'
```
O sufixo `[1m]` aplica a janela de contexto 1M a todo o uso dos aliases `opus` e `sonnet`, incluindo a fase Opus do modo de plano de [`opusplan`](#opusplan-model-setting).
* Claude Code remove o sufixo antes de enviar o ID do modelo para seu provedor.
* Apenas anexe `[1m]` quando o modelo subjacente [suportar contexto 1M](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window).
* O sufixo é lido por variável, não por modelo. No Bedrock, Vertex e Foundry, um ID de modelo sem `[1m]` em uma variável usa contexto 200K mesmo se outra variável define o mesmo modelo com o sufixo. Sonnet 5 sempre é executado com a janela 1M nesses provedores e nunca precisa do sufixo.
Uma lista de permissões `availableModels` entregue através de [MDM ou um arquivo de configurações gerenciado](/pt/settings#settings-files) ainda se aplica ao usar provedores de terceiros; [configurações gerenciadas pelo servidor não são entregues lá](/pt/server-managed-settings#platform-availability). A filtragem corresponde a um alias de modelo como `opus`, um prefixo de versão como `claude-opus-4-8`, ou o ID de modelo completo em forma de provedor. Prefixos específicos do provedor como `us.anthropic.` não são removidos, então para permitir um modelo específico, liste o mesmo ID em forma de provedor que o seletor mostra, ou mapeie através de [`modelOverrides`](#override-model-ids-per-version). Qualquer sufixo `[1m]` é removido tanto da entrada da lista de permissões quanto do modelo solicitado antes da correspondência.
Personalizar exibição e capacidades do modelo fixado
Quando você fixa um modelo em um provedor de terceiros, o ID específico do provedor aparece como está no seletor `/model` e Claude Code pode não reconhecer quais recursos o modelo suporta. Você pode substituir o nome de exibição e declarar capacidades com variáveis de ambiente complementares para cada modelo fixado.
Essas variáveis têm efeito em provedores de terceiros, como Bedrock, Vertex AI e Foundry. As variáveis `_NAME` e `_DESCRIPTION` também têm efeito quando `ANTHROPIC_BASE_URL` aponta para um [gateway LLM](/pt/llm-gateway). Elas não têm efeito ao conectar diretamente a `api.anthropic.com`.
| Variável de ambiente | Descrição |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `ANTHROPIC_DEFAULT_OPUS_MODEL_NAME` | Nome de exibição para o modelo Opus fixado no seletor `/model`. Padrão para o ID do modelo quando não definido |
| `ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION` | Descrição de exibição para o modelo Opus fixado no seletor `/model`. Padrão para `Custom Opus model` quando não definido |
| `ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES` | Lista separada por vírgulas de capacidades que o modelo Opus fixado suporta |
Os mesmos sufixos `_NAME`, `_DESCRIPTION` e `_SUPPORTED_CAPABILITIES` estão disponíveis para `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL`, `ANTHROPIC_DEFAULT_FABLE_MODEL` e `ANTHROPIC_CUSTOM_MODEL_OPTION`.
Claude Code habilita recursos como [níveis de esforço](#adjust-effort-level) e [pensamento estendido](#extended-thinking) correspondendo o ID do modelo contra padrões conhecidos. IDs específicos do provedor, como ARNs Bedrock ou nomes de implantação personalizados, geralmente não correspondem a esses padrões, deixando recursos suportados desabilitados. Defina `_SUPPORTED_CAPABILITIES` para informar ao Claude Code quais recursos o modelo realmente suporta:
| Valor de capacidade | Habilita |
| ---------------------- | --------------------------------------------------------------------------------------------- |
| `effort` | [Níveis de esforço](#adjust-effort-level) e o comando `/effort` |
| `xhigh_effort` | {/* min-version: 2.1.111 */}O nível de esforço `xhigh` |
| `max_effort` | O nível de esforço `max` |
| `thinking` | [Pensamento estendido](#extended-thinking) |
| `adaptive_thinking` | Raciocínio adaptativo que aloca dinamicamente o pensamento com base na complexidade da tarefa |
| `interleaved_thinking` | Pensamento entre chamadas de ferramenta |
Quando `_SUPPORTED_CAPABILITIES` é definido, as capacidades listadas são habilitadas e as capacidades não listadas são desabilitadas para o modelo fixado correspondente. Quando a variável não está definida, Claude Code volta para detecção integrada baseada no ID do modelo.
Este exemplo fixa Opus para um ARN de modelo personalizado Bedrock, define um nome amigável e declara suas capacidades:
```bash theme={null}
export ANTHROPIC_DEFAULT_OPUS_MODEL='arn:aws:bedrock:us-east-1:123456789012:custom-model/abc'
export ANTHROPIC_DEFAULT_OPUS_MODEL_NAME='Opus via Bedrock'
export ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION='Opus 4.7 routed through a Bedrock custom endpoint'
export ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES='effort,xhigh_effort,max_effort,thinking,adaptive_thinking,interleaved_thinking'
```
Substituir IDs de modelo por versão
As variáveis de ambiente no nível de família acima configuram um ID de modelo por alias de família. Se você precisar mapear várias versões dentro da mesma família para IDs de provedor distintos, use a configuração `modelOverrides` em vez disso.
`modelOverrides` mapeia IDs de modelo Anthropic individuais para as strings específicas do provedor que Claude Code envia para a API do seu provedor. Quando um usuário seleciona um modelo mapeado no seletor `/model`, Claude Code usa seu valor configurado em vez do padrão integrado.
Isso permite que administradores corporativos roteiem cada versão de modelo para um ARN de perfil de inferência Bedrock específico, nome de versão Vertex AI ou nome de implantação Foundry para governança, alocação de custos ou roteamento regional.
Defina `modelOverrides` em seu [arquivo de configurações](/pt/settings#settings-files):
```json theme={null}
{
"modelOverrides": {
"claude-opus-4-7": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-prod",
"claude-opus-4-6": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-46-prod",
"claude-sonnet-4-6": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/sonnet-prod"
}
}
```
As chaves devem ser IDs de modelo Anthropic conforme listado na [Visão geral de modelos](https://platform.claude.com/docs/en/about-claude/models/overview). Para IDs de modelo datados, inclua o sufixo de data exatamente como aparece lá. Chaves desconhecidas são ignoradas.
As substituições substituem os IDs de modelo integrados que suportam cada entrada no seletor `/model`. No Bedrock, as substituições têm precedência sobre qualquer perfil de inferência que Claude Code descobre automaticamente na inicialização. Os valores que você fornece diretamente através de `ANTHROPIC_MODEL`, `--model` ou as variáveis de ambiente `ANTHROPIC_DEFAULT_*_MODEL` são passados para o provedor como estão e não são transformados por `modelOverrides`.
`modelOverrides` funciona junto com `availableModels`. A lista de permissões é avaliada contra o ID de modelo Anthropic, não o valor de substituição, então uma entrada como `"opus"` em `availableModels` continua a corresponder mesmo quando versões do Opus são mapeadas para ARNs. Quando `enforceAvailableModels` é definido em configurações gerenciadas, o Padrão imposto é resolvido através de `modelOverrides` apenas da [fonte gerenciada de precedência mais alta](/pt/server-managed-settings#settings-precedence). O mapeamento de um administrador, como uma versão fixada para um ARN de perfil de inferência, é honrado no Padrão imposto. Substituições de configurações de usuário ou projeto não o afetam.
Configuração de prompt caching
Claude Code usa automaticamente [prompt caching](/pt/prompt-caching) para otimizar o desempenho e reduzir custos. Você pode desabilitar prompt caching globalmente ou para níveis de modelo específicos:
| Variável de ambiente | Descrição |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `DISABLE_PROMPT_CACHING` | Defina como `1` para desabilitar prompt caching para todos os modelos. Tem precedência sobre as configurações por modelo |
| `DISABLE_PROMPT_CACHING_HAIKU` | Defina como `1` para desabilitar prompt caching apenas para modelos Haiku |
| `DISABLE_PROMPT_CACHING_SONNET` | Defina como `1` para desabilitar prompt caching apenas para modelos Sonnet |
| `DISABLE_PROMPT_CACHING_OPUS` | Defina como `1` para desabilitar prompt caching apenas para modelos Opus |
| `DISABLE_PROMPT_CACHING_FABLE` | Defina como `1` para desabilitar prompt caching apenas para modelos Fable |
Para alterar o TTL do cache ou aprender o que dispara uma falha de cache, veja [Como Claude Code usa prompt caching](/pt/prompt-caching).