Guia de compatibilidade do gateway Claude Code

Mantenha um gateway LLM compatível com Claude Code: os endpoints que ele chama, os headers e campos de corpo a encaminhar, e o que quebra quando são removidos.

Esta página documenta as solicitações que Claude Code envia para um gateway, incluindo os endpoints que ele chama, os headers e campos de corpo que o gateway deve encaminhar, e quais recursos deixam de funcionar quando não o faz. É escrita para operadores configurando um produto gateway para funcionar com Claude Code.

O gateway de aplicativos Claude, o gateway auto-hospedado da Anthropic, serve sua própria referência de endpoint em GET /protocol, cobrindo os endpoints de sign-in, inferência, configurações gerenciadas, descoberta de modelo e telemetria desse gateway. É um documento separado deste guia.

Esta página cobre:

• Formatos de API e os endpoints a servir para cada um
• Comportamento do cliente por método de conexão: como IDs de modelo, valores de anthropic-beta, campos de solicitação e padrões diferem entre os formatos e um sign-in de gateway de aplicativos Claude
• Headers de solicitação: quais devem chegar ao upstream e quais seu gateway pode consumir
• Headers de resposta: o que retornar para que a detecção de travamento, tentativas e exibição de limite de uso funcionem
• O bloco de atribuição de prompt do sistema e como ele interage com cache de prompt
• Passagem de recursos: o que quebra quando headers ou campos de corpo são removidos
• Descoberta de modelo

Esta página usa dois termos para o que seu gateway faz com cada header e campo de corpo:

• Encaminhar inalterado: passá-lo para o upstream byte por byte
• Consumir: o gateway pode lê-lo para roteamento, atribuição ou rastreamento e não precisa encaminhá-lo

Qualquer coisa não marcada como encaminhar inalterado é sua para consumir ou ignorar.

Formatos de API

Um gateway deve expor pelo menos um dos seguintes formatos de API para clientes Claude Code. Um cliente escolhe um formato e aponta Claude Code para seu gateway com as variáveis na coluna Selecionado pela tabela abaixo.

Google Cloud's Agent Platform é o endpoint Claude do Google Cloud, anteriormente Vertex AI; seus nomes de variáveis mantêm a grafia VERTEX.

Foundry e Claude Platform on AWS

Microsoft Foundry e a Claude Platform on AWS implementam o formato Anthropic Messages. Claude Code roteia para eles através de suas próprias variáveis, ANTHROPIC_FOUNDRY_BASE_URL e ANTHROPIC_AWS_BASE_URL, mas um gateway fronteando qualquer um deles implementa a linha Anthropic Messages acima. Um gateway fronteando a Claude Platform on AWS também deve encaminhar o header anthropic-workspace-id, que essa plataforma requer em cada requisição.

Endpoints opcionais e tráfego de inicialização

Endpoints de contagem de tokens são os únicos opcionais: quando estão ausentes, Claude Code volta para uma estimativa baseada em caracteres do uso de contexto.

Corresponda no caminho, não na URL completa:

• Requisições de inferência postam para /v1/messages?beta=true
• O método Google Cloud's Agent Platform sufixos anexam ao caminho do modelo do publisher, como em /projects/{project}/locations/{location}/publishers/anthropic/models/{model}:streamRawPredict

Um gateway também vê tráfego de inicialização de melhor esforço que pode rejeitar sem quebrar nada. Um gateway no formato Anthropic Messages recebe uma sonda de aquecimento de conexão HEAD /api/hello, que Claude Code pula quando um proxy HTTP ou certificado de cliente está configurado. Um gateway no formato Amazon Bedrock recebe uma requisição GET /inference-profiles?type=SYSTEM_DEFINED e, quando o modelo configurado é um perfil de inferência, buscas GET /inference-profiles/{profile}.

A verificação de disponibilidade do fast mode nunca aparece nos logs do gateway: ela chama api.anthropic.com diretamente em vez de seguir ANTHROPIC_BASE_URL, então em uma rede que bloqueia egresso direto para api.anthropic.com, o fast mode pode relatar um erro de conectividade enquanto a inferência através do gateway continua funcionando. A verificação de segurança de domínio WebFetch também chama api.anthropic.com diretamente. Use fast mode behind proxies and LLM gateways cobre as variáveis que o restauram.

Streaming

Transmita respostas de inferência em stream. Claude Code lê o stream conforme ele chega, então se seu gateway armazena respostas completas antes de retransmiti-las, Claude Code trava.

Quando o cliente fala o formato Amazon Bedrock, retransmita o corpo da resposta InvokeModelWithResponseStream e seu header Content-Type: application/vnd.amazon.eventstream sem modificações, e não converta o stream para server-sent events. Veja Streaming errors behind a gateway or proxy.

Encaminhe pings de keep-alive também. Em conexões através de ANTHROPIC_BASE_URL ou ANTHROPIC_AWS_BASE_URL, Claude Code conta cada byte que seu gateway retransmite, incluindo eventos SSE ping e linhas de comentário, e aborta um stream que fica silencioso por 300 segundos por padrão. Os pings do upstream são o único tráfego durante pausas de pensamento longo, então se seu gateway remove ou armazena eles, Claude Code aborta o stream durante essas pausas; Automatic retries cobre o que um stream abortado relata com base em quanto a resposta havia progredido. Um upstream que não envia pings em absoluto, como o event-stream binário do Amazon Bedrock, deixa essas pausas sem nada para encaminhar. Ao traduzir de tal upstream, emita seus próprios eventos ping durante lacunas silenciosas. Gateways alcançados através de ANTHROPIC_BEDROCK_BASE_URL, ANTHROPIC_VERTEX_BASE_URL, ou ANTHROPIC_FOUNDRY_BASE_URL não são envolvidos por este watchdog de nível de byte, mesmo quando retransmitem o formato Anthropic Messages; lá, um timeout ocioso de 5 minutos aborta um stream silencioso em vez disso, e em conexões ANTHROPIC_BEDROCK_BASE_URL você pode adicionar o watchdog de byte com CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK.

Incompatibilidade de formato com o upstream

Qual formato o cliente fala determina o que seu gateway recebe. O modo de falha comum é uma incompatibilidade entre o formato que o cliente envia para seu gateway e o formato que o provedor upstream atrás dele aceita.

• Quando o cliente fala o formato Amazon Bedrock ou Google Cloud's Agent Platform, Claude Code envia apenas o subconjunto de seu conjunto completo de capacidades que esses provedores aceitam
• Quando o cliente fala o formato Anthropic Messages, Claude Code envia o conjunto completo, mesmo que seu gateway encaminhe para um upstream Amazon Bedrock ou Google Cloud's Agent Platform

Fazer a ponte dessa diferença é trabalho do seu gateway. Feature pass-through descreve o que quebra quando não faz.

Se seu upstream é Amazon Bedrock ou Google Cloud's Agent Platform, você pode evitar a ponte expondo o formato desse provedor em vez disso. Route to a cloud provider through a gateway mostra a configuração do cliente para esse formato.

Como o método de conexão altera o comportamento do cliente

A forma como um desenvolvedor se conecta ao seu gateway determina quais IDs de modelo, valores de anthropic-beta e campos de solicitação o Claude Code envia, e quais padrões ele aplica. Seu gateway vê um dos três comportamentos de cliente:

• Formato Amazon Bedrock ou Agent Platform: o desenvolvedor define CLAUDE_CODE_USE_BEDROCK=1 com ANTHROPIC_BEDROCK_BASE_URL, ou CLAUDE_CODE_USE_VERTEX=1 com ANTHROPIC_VERTEX_BASE_URL, apontando para seu gateway. Claude Code usa os IDs de modelo, campos de solicitação e padrões desse provedor.
• Formato Anthropic Messages: o desenvolvedor define ANTHROPIC_BASE_URL para seu gateway. Claude Code trata o gateway como a API Claude e não consegue dizer para qual upstream você encaminha.
• Entrada do gateway de aplicativos Claude: o desenvolvedor entra em um gateway de aplicativos Claude. Esse gateway fala o formato Anthropic Messages, mas pode rotear para qualquer upstream, então Claude Code envia apenas os valores de anthropic-beta e suposições de capacidade de modelo que Amazon Bedrock e Agent Platform também aceitam.

Solicitações e padrões por método de conexão

A tabela abaixo compara os três métodos de conexão, um comportamento por linha. Ela omite Microsoft Foundry e Claude Platform on AWS, que também usam o formato Anthropic Messages, mas que Claude Code alcança através de suas próprias variáveis. Para esses, consulte as páginas Microsoft Foundry e Claude Platform on AWS.

Para os recursos que cada conexão suporta e a telemetria que envia para Anthropic por padrão, consulte Disponibilidade de recursos e Comportamentos padrão por provedor de API.

Configurações para IDs de modelo não reconhecidos

Duas configurações do lado do cliente alteram o que Claude Code assume para um ID de modelo que não reconhece, independentemente do método de conexão que o desenvolvedor usa:

• Janela de contexto: Claude Code assume 200K, ou 1M quando o ID carrega [1m]. Para declarar a janela real, consulte Corrigir a janela para um gateway ou ID de modelo personalizado
• Capacidades: para dar a um alias de gateway as capacidades do modelo por trás dele, mapeie o ID Anthropic desse modelo para seu alias com uma entrada modelOverrides nas configurações que você distribui. Para onde as variáveis ANTHROPIC_DEFAULT_*_MODEL_SUPPORTED_CAPABILITIES se aplicam, consulte feature pass-through

Headers de solicitação

Claude Code inclui esses headers em solicitações de API. Nomes de headers não diferenciam maiúsculas de minúsculas no fio. Encaminhe anthropic-version e anthropic-beta inalterados, mais anthropic-workspace-id quando o upstream é a Claude Platform on AWS; o resto o gateway pode consumir para roteamento, atribuição e rastreamento, e não precisa encaminhar.

IDs de subagentes são gerados novamente cada vez que Claude Code gera um subagente. Agentes companheiros, os membros nomeados de uma equipe de agentes, reutilizam um ID estável baseado em nome entre reconexões. Em ambos os casos, o ID identifica um agente, não uma pessoa ou dispositivo, então não trate o header de ID de agente como um identificador de usuário.

Se seus desenvolvedores definirem ANTHROPIC_CUSTOM_HEADERS, esses headers também aparecem em solicitações.

Headers de dica de gateway

Claude Code também pode enviar dicas de roteamento: fatos por solicitação que um gateway ou roteador pode usar para agendar, armazenar em cache ou atribuir uma solicitação. Requer Claude Code v2.1.273 ou posterior.

Se uma solicitação as carrega depende de onde Claude Code as envia:

• Conexão direta com a API Anthropic: enviado por padrão
• URL base personalizada: desativado por padrão, porque um proxy que rejeita headers desconhecidos falharia na solicitação. Para recebê-los, defina CLAUDE_CODE_GATEWAY_HINT_HEADERS=1 para seus desenvolvedores, por exemplo no bloco env de configurações gerenciadas
• Qualquer outro backend, incluindo Amazon Bedrock, Agent Platform do Google Cloud, Microsoft Foundry e Claude Platform on AWS: enviado apenas quando CLAUDE_CODE_GATEWAY_HINT_HEADERS=1 está definido

Definir CLAUDE_CODE_GATEWAY_HINT_HEADERS para 0 interrompe os headers em cada conexão.

Os headers carregam apenas o que as linhas abaixo listam: vocabulários fixos, nomes de ferramentas e durações, nunca texto de prompt ou conteúdo de arquivo. Cada valor é ASCII imprimível.

Antes de analisar x-claude-code-prev-tool-durations, verifique como Claude Code constrói o valor e o que deixa de fora:

• Entradas: uma por chamada de ferramenta que foi executada, na ordem em que seu resultado foi coletado, em milissegundos inteiros
• Limite: Claude Code envia no máximo 32 entradas e 4 KB, mantendo as primeiras entradas
• Codificação: nomes de ferramentas são codificados em percentual, cobrindo %, ;, =, vírgula, espaço e qualquer caractere fora do ASCII imprimível
• Análise: dividir em ;, depois em =, e decodificar cada nome
• Ausência: chamadas de compactação, solicitações laterais e a primeira solicitação de um novo prompt nunca a carregam. Não leia um header ausente como uma volta que não executou ferramentas
• Tempos: cada um exclui prompts de permissão e hooks, e chamadas de ferramenta paralelas cada uma relata seu próprio tempo, então as entradas não somam a lacuna entre solicitações

Encaminhar como listas abertas

Trate os headers e campos de corpo como listas abertas, não fechadas. Claude Code ganha capacidades ao longo dos lançamentos, e elas chegam como novos valores anthropic-beta, novos campos de corpo de solicitação e ocasionalmente novos headers anthropic-* ou x-claude-code-*.

Ao encaminhar para um upstream no formato Anthropic, passe headers de solicitação anthropic-* e campos de corpo de solicitação através inalterados em vez de fazer uma lista de permissões dos que você vê hoje. Um gateway fixado a uma lista observada remove o header ou campo da próxima capacidade e quebra-o no lançamento que a introduz.

A exceção é um upstream não-Anthropic, como Amazon Bedrock ou Agent Platform do Google Cloud, onde fazer a ponte da diferença de schema é trabalho do gateway; consulte passagem de recursos.

Cabeçalhos de resposta

Claude Code lê esses cabeçalhos de resposta para detectar fluxos travados, para decidir se e quando tentar novamente, e para mostrar limites de uso. A tabela lista o que retornar para cada um. Também encaminhe corpos de resposta de erro sem modificações, para que a recuperação de rejeição de capacidade do Claude Code possa corresponder à redação do erro do upstream.

Bloco de atribuição do prompt do sistema

Claude Code prepara um bloco de atribuição curto para o prompt do sistema contendo a versão do cliente e uma impressão digital derivada da conversa. O endpoint api.anthropic.com remove o bloco antes do processamento quando ele chega inalterado como o primeiro bloco do sistema, portanto não afeta o cache de prompt de primeira parte. Qualquer outro upstream o recebe como parte do prompt.

A remoção é posicional, portanto funciona apenas quando o gateway encaminha o array system inalterado. Para manter o bloco fora do prompt sem perder outro conteúdo do sistema:

• Encaminhe o array system exatamente como recebido, mantendo o bloco primeiro: adicionar outro bloco do sistema, reordenar o array ou convertê-lo em uma única string derrota a remoção, e o bloco então chega ao modelo e à chave do cache de prompt.
• Mantenha o bloco em sua própria entrada de array: o endpoint trata um bloco mesclado que começa com o cabeçalho de atribuição como atribuição em sua totalidade e descarta tudo mesclado nele, incluindo o resto do prompt do sistema.
• Se seu gateway deve reformular o conteúdo do sistema, defina CLAUDE_CODE_ATTRIBUTION_HEADER=0 para que Claude Code omita o bloco. Anthropic e os endpoints Claude dos provedores de nuvem leem o bloco para atribuição, portanto omita-o no cliente em vez de removê-lo ou movê-lo no gateway.

A variável existe para compatibilidade com gateway e cache de terceiros, não como controle de privacidade: em uma conexão direta a solicitação completa já vai para a API Anthropic de qualquer forma. Quando ambas as condições a seguir se mantêm, Claude Code mantém o bloco em solicitações do classificador de modo automático mesmo quando você define a variável como 0:

• As solicitações vão para api.anthropic.com, com ANTHROPIC_BASE_URL não definido ou nomeando esse host e nenhum provedor de terceiros selecionado.
• A credencial ativa não é uma credencial de perfil Anthropic ou federação.

As solicitações do classificador pulam o resto do prompt do sistema de Claude Code, portanto nessas solicitações o bloco é o único marcador no corpo da solicitação que as identifica como tráfego de Claude Code. Quando qualquer condição falha, através de um gateway LLM, em um provedor de terceiros ou com uma credencial de perfil ou federação ativa, definir 0 remove o bloco das solicitações do classificador também. Antes de v2.1.229, essa exceção não existia: definir 0 removia o bloco dessas solicitações do classificador, e quando a API recusava as solicitações não identificadas, o modo automático falhava em cada ação que enviava ao classificador.

A partir de Claude Code v2.1.181, o bloco é estável pela vida útil de uma conversa quando solicitações são roteadas através de uma URL base personalizada, portanto um cache de prompt do lado do gateway com chave no corpo completo da solicitação funciona sem desabilitá-lo, e qualquer provedor para o qual seu gateway encaminha recebe um prefixo de prompt estável. Antes de v2.1.181, o bloco incluía um token por solicitação que alterava o início do prompt do sistema em cada solicitação. Nessas versões, defina CLAUDE_CODE_ATTRIBUTION_HEADER=0 quando seu gateway faz qualquer um destes:

• Implementa um cache de prompt com chave no corpo da solicitação.
• Encaminha solicitações para um provedor de terceiros como Amazon Bedrock, Microsoft Foundry ou Agent Platform do Google Cloud, no formato Anthropic Messages ou no próprio formato do provedor, onde o prefixo em mudança reduz a reutilização do cache de prompt nesse provedor.

Passagem de recursos

Claude Code trata um gateway ANTHROPIC_BASE_URL como um endpoint no formato Anthropic e envia a ele os headers beta e campos de corpo de solicitação que envia para api.anthropic.com, exceto um pequeno conjunto de diagnósticos e padrões reservados para conexões diretas, como o padrão de streaming de ferramenta de granulação fina coberto abaixo. Esse conjunto varia por lançamento, então não dependa de seu conteúdo.

Capacidades que adicionam campos de corpo os emparelham com um header beta, e o par viaja junto. Um gateway que remove o header enquanto passa o corpo, ou encaminha um corpo no formato Anthropic para um upstream com um schema diferente, produz erros 400 difíceis; apenas quando ambas as metades estão ausentes juntas o recurso desativa silenciosamente. Um gateway que reescreve ou redige corpos de solicitação para inspeção de conteúdo quebra o emparelhamento da mesma forma que remover o faz, então inspecione sem modificar. A tabela observa onde um recurso se desvia do emparelhamento.

Streaming de ferramenta de granulação fina é um dos padrões de conexão direta: está desativado por padrão sempre que solicitações são roteadas através de uma URL base personalizada, e um gateway o recebe quando desenvolvedores definem CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING=1.

As variáveis ANTHROPIC_DEFAULT_*_MODEL_SUPPORTED_CAPABILITIES declaram capacidades de modelo apenas nas configurações do provedor: CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX, CLAUDE_CODE_USE_FOUNDRY, e CLAUDE_CODE_USE_MANTLE. Elas não têm efeito atrás de um gateway ANTHROPIC_BASE_URL.

Retry automático e encaminhamento de erro

O que Claude Code faz após uma rejeição upstream depende do que foi rejeitado:

• Quando o upstream rejeita o campo thinking, uma mensagem de sistema no meio da conversa, ou o marcador cache_control em tal mensagem, Claude Code tenta novamente a solicitação e desabilita a capacidade rejeitada pelo resto da conversa
• Quando o upstream rejeita uma assinatura de pensamento, incluindo com um 400 cuja mensagem diz que o bloco está bound to a different conversation, Claude Code remove blocos de pensamento anteriores da solicitação, tenta novamente, e os mantém fora de cada solicitação posterior. Novas respostas ainda incluem pensamento
• Quando o gateway ou seu upstream rejeita a entrada da ferramenta advisor em tools como um tipo de ferramenta não reconhecido, Claude Code tenta novamente a solicitação uma vez sem essa entrada e seu valor anthropic-beta. Solicitações posteriores para essa URL base deixam o advisor de fora até Claude Code sair, e /advisor fica indisponível para o desenvolvedor por esse tempo. Claude Code reconhece essa rejeição por uma resposta 400 ou 422 cuja mensagem nomeia o tipo de ferramenta após Input tag, como Input tag 'advisor_20260301'. Antes da v2.1.280, Claude Code não tentava novamente essa rejeição
• Claude Code não tenta novamente rejeições de gerenciamento de contexto ou campos de schema de ferramenta, então esses erros 400 chegam ao desenvolvedor

A rejeição bound to a different conversation vem da verificação de pensamento preservado da API, que falha quando conteúdo de system, tools, ou messages anteriores difere da solicitação que produziu o pensamento. Um gateway que reescreve qualquer um desses conteúdos pode causar a rejeição em si; Bibliotecas, proxies e gateways cobre o que passar inalterado.

A lógica de retry corresponde à redação de erro do upstream, então encaminhe corpos de resposta de erro inalterados. Um gateway que envolve erros upstream em seu próprio envelope quebra o caminho de recuperação, mesmo quando preserva o código de status, a menos que a mensagem do envelope carregue um token capability_rejected: estável. O gateway de aplicativos Claude substitui esses tokens pela redação de erro dos provedores de nuvem, por exemplo capability_rejected: prompt_too_long.

Desabilitar capacidades de pré-lançamento

CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 impede que Claude Code envie capacidades de pré-lançamento e seus campos de corpo em cada provedor, incluindo gerenciamento de contexto e campos de ferramenta beta. A variável não afeta raciocínio adaptativo, que é selecionado por modelo em vez de por beta. Nunca suprime a capacidade OAuth que autenticação de assinatura requer.

Em Claude Code v2.1.227 ou posterior, sua organização pode manter busca de ferramenta MCP ativada sob essa variável através de configurações gerenciadas. O que Claude Code envia com essa substituição em vigor depende de como você se conecta:

• Em uma conexão direta, ou através de um gateway definido com ANTHROPIC_BASE_URL, Claude Code continua enviando o header beta de busca de ferramenta, campos de ferramenta defer_loading, e blocos tool_reference, e remove o resto
• Em um provedor de nuvem, ou conectado através de um gateway de aplicativos Claude, a substituição não tem efeito

O conjunto de capacidades que Claude Code envia cresce ao longo dos lançamentos. Para strings de header beta atuais, consulte a referência de headers beta; teste seu gateway contra novos lançamentos de Claude Code em vez de fixar a uma lista observada.

Descoberta de modelos

Quando ANTHROPIC_BASE_URL aponta para um gateway que expõe o formato Anthropic Messages, Claude Code pode consultar o endpoint /v1/models do gateway na inicialização e adicionar os modelos retornados ao seletor /model. Se você ou seu administrador definir replaceBuiltInOptions em um modelPicker lineup, Claude Code oculta os modelos descobertos do seletor.

Desenvolvedores o habilitam definindo CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1, em seu próprio ambiente ou através de configurações gerenciadas. A descoberta está desativada por padrão para que gateways apoiados por uma chave de API compartilhada não exponham cada modelo que a chave pode acessar a cada usuário.

Quando a descoberta é executada

A descoberta se aplica apenas ao formato Anthropic Messages. Não é executada quando:

• Qualquer variável de provedor CLAUDE_CODE_USE_* é definida, mesmo se ANTHROPIC_BASE_URL também for definido
• ANTHROPIC_BASE_URL não está definido ou aponta para api.anthropic.com

A descoberta ainda é executada quando o tráfego não essencial é desativado, porque a solicitação vai apenas para seu gateway. Antes da v2.1.257, a descoberta não era executada enquanto o tráfego não essencial estava desativado.

Solicitação e resposta

A solicitação é GET /v1/models?limit=1000 com um timeout de 3 segundos por padrão, e qualquer redirecionamento é tratado como falha para que a credencial não vaze para um alvo de redirecionamento. Um gateway que responde mais lentamente do que o timeout, ou um que redireciona /v1/models, mesmo http para https, falha na descoberta silenciosamente; sirva o endpoint diretamente na URL base configurada.

Para dar a um gateway lento mais tempo, defina CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS. A variável requer Claude Code v2.1.269 ou posterior.

Claude Code envia a solicitação de descoberta com ambos os headers de credencial abaixo e omite um header cujo valor não se resolve. Enviar ambos os headers requer Claude Code v2.1.248 ou posterior. Versões anteriores enviam apenas Authorization quando ANTHROPIC_AUTH_TOKEN é definido e apenas x-api-key caso contrário.

• Authorization: ANTHROPIC_AUTH_TOKEN como um token bearer, caso contrário o valor apiKeyHelper como um token bearer. Nesse caso, Claude Code aguarda o helper retornar antes de enviar a solicitação.
• x-api-key: a chave de API que Claude Code resolveu, como ANTHROPIC_API_KEY. Quando um valor helper é a única credencial, este header também o carrega, para que o valor chegue em ambos os headers.

Claude Code também envia qualquer header de ANTHROPIC_CUSTOM_HEADERS. Quando um header customizado tem um valor não vazio, Claude Code o envia no lugar de um header integrado de mesmo nome, correspondendo nomes case-insensitively.

Quando nenhum valor do header de credencial se resolve, Claude Code pula a descoberta e escreve uma linha [gatewayDiscovery] skipped no log de debug de uma sessão claude --debug. Se você fornecer uma credencial apenas através de ANTHROPIC_CUSTOM_HEADERS, Claude Code ainda pula a descoberta.

Claude Code lê id, o display_name opcional e a description opcional de cada entrada no array data da resposta:

{
  "data": [
    {
      "id": "claude-sonnet-4-6",
      "display_name": "Claude Sonnet 4.6",
      "description": "Default model for everyday coding tasks"
    },
    { "id": "claude-opus-4-8" }
  ]
}

Claude Code mantém uma entrada quando seu id contém claude ou anthropic em qualquer lugar na string, correspondido case-insensitively, e ignora o resto. IDs com prefixo de provedor como vertex_ai/claude-sonnet-4-6 ou bedrock/anthropic.claude-sonnet-4-5 passam no filtro; um ID que não contém nenhuma substring não passa. Antes da v2.1.223, Claude Code mantinha uma entrada apenas quando seu id começava com claude ou anthropic, o que ocultava IDs com prefixo de provedor.

Entradas do seletor e cache

O seletor é a lista de modelos interativa que abre quando um desenvolvedor executa /model em Claude Code. Cada entrada descoberta usa display_name como seu nome quando o gateway envia um que difere do id. Caso contrário, a entrada mostra o nome do modelo quando Claude Code reconhece o id, e o id quando não reconhece. Por exemplo, uma entrada com o id my-gateway-claude-sonnet-4-6 e sem display_name aparece como Sonnet 4.6.

A descoberta adiciona apenas modelos que a configuração gerenciada availableModels permite.

Cada entrada também mostra a description do modelo, recolhida em uma linha. Uma entrada sem description lê "Do gateway" em vez disso. Antes da v2.1.257, cada entrada descoberta lia "Do gateway".

Um ID descoberto não recebe sua própria linha quando corresponde a uma linha já no seletor:

• Mesmo ID: o ID descoberto corresponde exatamente ao ID de uma linha existente, ou os dois IDs são grafias da mesma versão Fable.
• Mesmo modelo que um alias integrado: quando um ID explícito descoberto nomeia o modelo para o qual um alias integrado atualmente se resolve, o seletor mostra apenas a linha do alias. Por exemplo, enquanto sonnet se resolve para claude-sonnet-5, um claude-sonnet-5 descoberto colapsa na linha sonnet, e um claude-sonnet-4-6 descoberto ainda recebe sua própria linha. Antes da v2.1.197, Claude Code não dobrava esses IDs em linhas integradas, então claude-sonnet-5 também recebia sua própria linha "Do gateway".

Os resultados são armazenados em cache em ~/.claude/cache/gateway-models.json, ou %USERPROFILE%\.claude\cache\gateway-models.json no Windows, e atualizados em cada inicialização. Se você definir CLAUDE_CONFIG_DIR, o cache fica sob esse diretório em vez disso. Se a solicitação falhar ou o gateway não implementar /v1/models, o seletor volta para a lista em cache da inicialização anterior ou para a lista de modelos integrada. Se seu gateway serve modelos Claude sob aliases que não correspondem ao filtro de descoberta, desenvolvedores podem adicionar esses aliases manualmente com as variáveis de configuração de modelo.

Recursos relacionados

Para o resto do conjunto de documentação do gateway e as referências de API subjacentes:

• Visão geral de gateway: o que é um gateway e como escolher entre o gateway de aplicativos Claude e outro produto
• Outros gateways LLM: como implantar um gateway que sua organização executa e como ele interage com assinaturas claude.ai
• Implantar um gateway LLM para sua organização: a lista de verificação do administrador que usa este guia
• Conectar Claude Code a um gateway LLM: configuração por desenvolvedor e a tabela de solução de problemas
• Referência de headers beta: o conjunto atual de valores anthropic-beta
• Messages API: o formato de API que um gateway no formato Anthropic implementa