Pular para o conteúdo principal
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.
Esta página cobre: 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. Qual formato Claude Code fala é determinado pela configuração do cliente: a variável na coluna Selecionado pela tabela abaixo aponta Claude Code para seu gateway nesse formato.
FormatoSelecionado porEndpointsEncaminhar inalterado
Anthropic MessagesANTHROPIC_BASE_URL/v1/messages, /v1/messages/count_tokens (opcional)headers de solicitação anthropic-beta e anthropic-version
Bedrock InvokeModelANTHROPIC_BEDROCK_BASE_URL com CLAUDE_CODE_USE_BEDROCK=1/model/{model}/invoke, /model/{model}/invoke-with-response-streamcampos de corpo de solicitação anthropic_beta e anthropic_version
Vertex rawPredictANTHROPIC_VERTEX_BASE_URL com CLAUDE_CODE_USE_VERTEX=1:rawPredict, :streamRawPredict, count-tokens:rawPredict (opcional)headers de solicitação anthropic-beta e anthropic-version, e o campo de corpo de solicitação anthropic_version

​
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 estima o uso de contexto localmente. Solicitações de inferência são postadas em /v1/messages?beta=true, então corresponda no caminho, não na URL completa. O método Vertex 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: uma sonda de conectividade HEAD /, e em gateways no formato Bedrock uma solicitação GET /inference-profiles?type=SYSTEM_DEFINED.

​
Streaming

Respostas de inferência devem fazer streaming. Claude Code consome eventos enviados pelo servidor conforme chegam, então um gateway que armazena em buffer respostas completas antes de retransmiti-las congela o cliente.

​
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 Bedrock ou Vertex, 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 Bedrock ou Vertex
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.
HeaderDescrição
Authorization, x-api-keyA credencial do gateway do desenvolvedor, em um ou ambos os headers dependendo de qual variável de credencial eles definiram
anthropic-versionVersão da API, atualmente 2023-06-01. Solicitações no formato Bedrock e Vertex também carregam o campo de corpo anthropic_version, cujo valor é a string de dialeto do provedor, não o valor deste header
anthropic-betaValores de capacidade separados por vírgula para a solicitação. Encaminhe o header verbatim; não faça uma lista de permissões de valores individuais, porque o conjunto muda com lançamentos de Claude Code. Quando o desenvolvedor se autentica com um login claude.ai, que é possível quando ANTHROPIC_BASE_URL é definido sem uma variável de credencial de gateway, este header também carrega uma capacidade OAuth que o upstream requer, e removê-lo falha essas solicitações com 401
x-claude-code-session-idUm identificador único para a sessão atual de Claude Code. Use-o para agregar todas as solicitações de uma sessão sem analisar corpos de solicitação
x-claude-code-agent-idIdentificador do subagente que emitiu a solicitação, presente apenas em solicitações de um agente que Claude Code gerou dentro da sessão. Use-o com o ID da sessão para atribuir custo a agentes paralelos
x-claude-code-parent-agent-idIdentificador do agente que gerou o agente solicitante, presente apenas para agentes aninhados
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 Bedrock ou Vertex, 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, então não afeta o cache de prompt de primeira parte; qualquer outro upstream o recebe como parte do prompt. Anthropic e os endpoints Claude dos provedores de nuvem o leem para atribuição, então para omiti-lo defina CLAUDE_CODE_ATTRIBUTION_HEADER=0 em vez de removê-lo no gateway. 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, então um cache de prompt do lado do gateway com chave no corpo completo da solicitação funciona sem desabilitá-lo. Antes de v2.1.181, o bloco incluía um token por solicitação; nessas versões, defina CLAUDE_CODE_ATTRIBUTION_HEADER=0 se seu gateway implementar tal cache.

​
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. 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.
RecursoHeader e par de corpoSintoma quando quebradoRemediação
Raciocínio adaptativoSem header beta. Claude Code envia thinking: {"type": "adaptive"} para Claude 4.6 e posterior, e trata nomes de modelos que não reconhece, como aliases de gateway, como modelos atuais que recebem o campo400 nomeando o campo thinking ou a tag adaptive quando a compilação do modelo upstream não a aceitaAtualize o upstream. Em Opus 4.6 e Sonnet 4.6, desenvolvedores podem definir CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1 em vez disso
Gerenciamento de contextoHeader beta de gerenciamento de contexto emparelhado com o campo de corpo context_management400 com Extra inputs are not permitted. Comum quando um gateway aceita solicitações no formato Anthropic mas as encaminha para BedrockEncaminhe ambos, ou CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
Contexto estendido e pensamento intercaladoApenas headers beta, sem campo de corpoSilenciosamente indisponível quando o header é removido; o upstream nunca vê a solicitação de capacidadeEncaminhe anthropic-beta verbatim
Campos de ferramenta betaHeaders beta relacionados a ferramentas emparelhados com campos de schema de ferramenta como strict e defer_loading400 nomeando o campo de schema de ferramenta não reconhecido quando o corpo passa sem seu headerEncaminhe ambos, ou CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
Esforço e saídas estruturadasO campo de corpo output_config carrega esforço, formato de saída estruturada e configurações de orçamento de tarefa; cada um emparelhado com seu próprio header beta400 nomeando output_config, frequentemente Extra inputs are not permitted, em upstreams Bedrock e VertexEncaminhe o campo e seus headers juntos
Contagem de tokensSem emparelhamento beta; usa o endpoint count_tokensClaude Code volta a estimar o uso de contexto localmenteExponha o endpoint se quiser contagens exatas
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

Claude Code tenta novamente automaticamente após algumas rejeições upstream e desabilita a capacidade rejeitada pelo resto da conversa. Rejeições do campo thinking, de assinaturas de pensamento, e de mensagens de sistema no meio da conversa todas se recuperam dessa forma. Rejeições de gerenciamento de contexto e campo de schema de ferramenta não tentam novamente; 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.

​
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. Não afeta raciocínio adaptativo, que é selecionado por modelo em vez de por beta, e nunca suprime a capacidade OAuth que autenticação de assinatura requer. 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. 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. Isso requer Claude Code v2.1.129 ou posterior.

​
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
  • Tráfego não essencial está desabilitado, através de CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC ou política organizacional

​
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. A solicitação de descoberta envia exatamente um header de credencial:
  • ANTHROPIC_AUTH_TOKEN como um token bearer, quando definido
  • Caso contrário, a chave de API resolvida, incluindo um valor apiKeyHelper, no header x-api-key
Isso difere de solicitações de inferência, que enviam um valor helper em ambos os headers. Um gateway que autentica /v1/models deve aceitar x-api-key para implantações helper. Qualquer header de ANTHROPIC_CUSTOM_HEADERS também é incluído. Claude Code lê id e o display_name opcional de cada entrada no array data da resposta, e ignora entradas cujo id não começa com claude ou anthropic: 
{
  "data": [
    { "id": "claude-sonnet-4-6", "display_name": "Claude Sonnet 4.6" },
    { "id": "claude-opus-4-7" }
  ]
}

​
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 é rotulada “Do gateway” e usa display_name quando fornecido. Um ID descoberto é ignorado apenas quando corresponde exatamente a uma linha já no seletor, ou quando tanto o ID descoberto quanto o existente se resolvem para Fable. Linhas integradas são chaveadas em aliases como sonnet, então um ID descoberto como claude-sonnet-4-6 adiciona sua própria linha “Do gateway” ao lado da entrada integrada. A configuração gerenciada availableModels limita o que a descoberta pode adicionar. 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 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. Para o resto do conjunto de documentação do gateway e as referências de API subjacentes: