Guia de compatibilidade do gateway Claude Code

• 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

• 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

​

Formatos de API

​

Foundry e Claude Platform on AWS

​

Endpoints opcionais e tráfego de inicialização

• 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

​

Streaming

• Se seu gateway armazena uma resposta em buffer até que ela esteja completa, Claude Code trava.
• Claude Code espera a sequência completa de eventos de cada resposta, em ordem, até os eventos finais message_delta e message_stop. Se o corpo termina de forma limpa depois que um bloco de conteúdo começou, mas antes desse message_delta final, Claude Code trata a resposta como uma conexão descartada. A resposta acima pode estar incompleta descreve o que o usuário vê nesse caso, e Tentativas automáticas diz quando Claude Code reemite a requisição em vez disso.
• Quando um guardrail do Amazon Bedrock bloqueia uma resposta, os eventos que o Bedrock envia podem referenciar um bloco de conteúdo cujo content_block_stop já chegou, e Claude Code depende de recebê-los da forma como foram enviados. AWS Guardrails descreve como essa resposta termina.
• Claude Code aborta uma resposta em streaming quando nenhum byte o alcança por mais tempo do que seu timeout de inatividade de streaming. Durante uma pausa longa de pensamento, os eventos SSE ping do upstream podem ser os únicos bytes no stream, então um gateway que os remove ou armazena em buffer pode acionar esse timeout no meio de uma resposta. Um gateway que traduz de um upstream sem pings, como o event stream binário do Amazon Bedrock, tem a mesma lacuna, a menos que emita seus próprios eventos ping.
• No formato Amazon Bedrock InvokeModel, Claude Code lê a resposta de /model/{model}/invoke-with-response-stream como o corpo binário application/vnd.amazon.eventstream que o Bedrock retorna, e não consegue analisá-la quando um gateway a converte para server-sent events ou reescreve esse header Content-Type. Erros de streaming atrás de um gateway ou proxy descreve o que o usuário vê nesse caso.

​

Incompatibilidade de formato com o upstream

• 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

​

Como o método de conexão altera o comportamento do 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

​

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

• 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 passagem de recursos

​

Headers de solicitação

​

Headers de dica de gateway

• 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

• 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

​

Cabeçalhos de resposta

​

Bloco de atribuição do prompt 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.

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

• 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

​

Pares de header beta e campo de corpo

​

Retry automático e encaminhamento de erro

• Quando um 400 diz que o valor enabled ou adaptive de thinking.type não é suportado, Claude Code tenta novamente uma vez com o outro tipo e mantém o campo thinking. Requisições posteriores para esse modelo mantêm o tipo alterado até Claude Code sair. Antes da v2.1.121, Claude Code não tentava novamente, então thinking.type.enabled is not supported chegava ao desenvolvedor
• Quando o upstream rejeita uma entrada role: "system" dentro de messages, Claude Code tenta novamente uma vez sem essas mensagens de sistema no meio da conversa e leva o texto delas em mensagens de usuário. Requisições posteriores na conversa mantêm esse formato até o desenvolvedor executar /clear ou a conversa ser compactada
• Quando o upstream rejeita apenas o marcador cache_control em uma mensagem de sistema no meio da conversa, Claude Code mantém as mensagens de sistema e tenta novamente uma vez com o marcador movido. O marcador vai na última entrada em messages que não é uma mensagem de sistema, nessa nova tentativa e em requisições posteriores até Claude Code sair
• 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 requisição uma vez sem essa entrada e seu valor anthropic-beta. Requisições posteriores os omitem. 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
• Quando o upstream rejeita output_config.effort ou seu valor anthropic-beta, o gateway vê a requisição mais uma vez sem eles. Requisições posteriores os omitem. Seu gateway não precisa de nenhuma alteração se encaminhar o 400 do upstream sem modificações e a mensagem:
  • Nomear output_config.effort junto com Extra inputs are not permitted
  • Disser que o modelo não suporta o parâmetro de esforço
  • Começar com Unexpected value(s) e listar effort-2025-11-24 para o header anthropic-beta. Requer v2.1.310 ou posterior. Desenvolvedores cujo ANTHROPIC_BETAS lista o valor continuam enviando-o e recebendo o 400, então peça a eles que removam essa entrada
• Quando o upstream rejeita o campo context_management ou seu valor anthropic-beta, o gateway vê a requisição mais uma vez sem eles. Requisições posteriores os omitem. Claude Code reconhece essa rejeição por sua mensagem, por exemplo uma que contenha context_management: Extra inputs are not permitted. Antes da v2.1.304, Claude Code não tentava novamente essa rejeição
• Quando um 400 rejeita outro valor anthropic-beta pelo nome, o gateway vê a requisição mais uma vez sem ele se a nova tentativa cobrir esse valor
• Quando o upstream rejeita um campo de ferramenta beta diferente de defer_loading, como strict, o 400 chega ao desenvolvedor. Antes disso, o gateway pode ver a requisição novamente sem os campos de busca de ferramentas. Para deixar de enviar esses campos, peça aos desenvolvedores que definam CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

​

Tentar novamente sem um valor beta rejeitado

• A frase da API: a frase Unexpected value(s) que lista o valor para o header anthropic-beta
• Um token beta_header:: capability_rejected: beta_header: seguido do valor, um token capability_rejected:

• Um valor com sua própria nova tentativa, como advisor ou busca de ferramentas: o gateway vê a nova tentativa própria dessa capacidade em vez disso
• Um valor que Claude Code não reconhece: um valor que um desenvolvedor definiu por meio de ANTHROPIC_BETAS permanece em cada requisição, então as requisições do desenvolvedor continuam falhando com o 400. Peça ao desenvolvedor que remova a entrada
• Um invalid beta flag isolado: Claude Code tenta adivinhar qual valor o upstream rejeitou. Se a requisição carregava um valor que ele tenta adivinhar, o gateway vê a requisição novamente sem esse valor. Se o 400 ainda chegar ao desenvolvedor, faça seu gateway nomear o valor rejeitado em uma dessas formas

​

Por quanto tempo um valor beta rejeitado fica de fora

​

Tentar novamente sem busca de ferramentas

​

Desabilitar capacidades de pré-lançamento

• Gerenciamento de contexto e seu campo de corpo context_management
• Os campos de schema de ferramenta beta, como strict e defer_loading. Os campos de ferramenta padrão name, description, input_schema e cache_control permanecem
• O campo de saída estruturada output_config.format. Requer Claude Code v2.1.287 ou posterior
• O campo output_config.task_budget
• MCP Tool Search, de modo que cada ferramenta MCP é carregada antecipadamente, a menos que sua organização a mantenha ativada por meio de configurações gerenciadas

• Os valores anthropic-beta para contexto estendido, pensamento intercalado e esforço, que os provedores de nuvem também aceitam
• O campo output_config.effort de nível superior. Retry automático e encaminhamento de erro cobre um upstream que o rejeita
• O campo thinking do raciocínio adaptativo, que não tem header beta
• As entradas role: "system" que carregam mensagens de sistema no meio da conversa
• O valor anthropic-beta de OAuth que a autenticação de assinatura requer
• Valores de header e campos de corpo que os próprios desenvolvedores adicionam por meio de ANTHROPIC_BETAS ou CLAUDE_CODE_EXTRA_BODY

• Em uma conexão direta sem a configuração HIPAA, 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
• Em um provedor de nuvem, ou conectado através de um gateway de aplicativos Claude, a substituição não tem efeito
• Em uma sessão que recebe a configuração HIPAA, a substituição não tem efeito e a busca de ferramenta permanece desativada

​

Descoberta de modelos

​

Quando a descoberta é executada

• 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

​

Solicitação e resposta

• Authorization: ANTHROPIC_AUTH_TOKEN como um token bearer, caso contrário o valor apiKeyHelper como um token bearer.
• 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.

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

​

Entradas do seletor e cache

• 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-5, um claude-sonnet-5-5 descoberto colapsa na linha sonnet, e um claude-sonnet-5 descoberto ainda recebe sua própria linha.

​

Recursos relacionados

• 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