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 que configuram um produto gateway para funcionar com Claude Code.

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

Esta página cobre:

• Formatos de API e os endpoints a servir para cada um
• Headers de solicitação: quais devem chegar ao upstream e quais seu gateway pode consumir
• O bloco de atribuição do prompt do sistema e como ele interage com o cache de prompt
• Passagem de recursos: o que quebra quando headers ou campos de corpo são removidos
• Descoberta de modelos

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 por da 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 solicitaçã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 a uma estimativa baseada em caracteres do uso de contexto.

Corresponda no caminho, não na URL completa:

• Solicitações de inferência são postadas em /v1/messages?beta=true
• O método Google Cloud's Agent Platform anexa sufixos ao caminho do modelo do editor, 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 ignora quando um proxy HTTP ou certificado de cliente está configurado. Um gateway no formato Amazon Bedrock recebe uma solicitaçã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 atrás de proxies e gateways LLM cobre as variáveis que o restauram.

Streaming

Respostas de inferência de stream. Claude Code lê o stream conforme chega, então se seu gateway armazena em buffer 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 Erros de streaming atrás de um gateway ou proxy.

Retransmita também pings de keep-alive. 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 os remove ou armazena em buffer, Claude Code aborta o stream durante essas pausas; Tentativas automáticas cobre o que um stream abortado relata com base em quanto a resposta havia progredido. Um upstream que não envia pings, como o event-stream binário do Amazon Bedrock, deixa essas pausas sem nada para retransmitir. 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 de inatividade de 5 minutos aborta um stream silencioso, 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 essa ponte é trabalho do seu gateway. Passagem de recursos descreve o que quebra quando não o faz.

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 para cada geração. 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.

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.

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, Claude Code tenta novamente a solicitação sem os blocos de pensamento anteriores da conversa e os mantém fora de cada solicitação posterior. Novas respostas ainda incluem pensamento
• 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 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, e qualquer redirecionamento é tratado como falha para que a credencial não vaze para um alvo de redirecionamento. Um gateway que responde lentamente ou redireciona /v1/models, mesmo http para https, falha na descoberta silenciosamente; sirva o endpoint diretamente na URL base configurada.

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