SpyBara
Go Premium

llm-gateway-protocol.md 2026-06-29 23:02 UTC to 2026-06-30 23:02 UTC

20 added, 15 removed.

2026
Tue 30 23:02 Mon 29 23:02 Sat 27 01:01 Fri 26 23:00 Thu 25 23:58 Wed 24 22:02 Tue 23 22:00 Mon 22 23:59 Fri 19 22:58 Thu 18 22:00 Wed 17 17:02 Tue 16 21:57 Mon 15 23:02 Sat 13 21:59 Fri 12 22:00 Thu 11 23:01 Wed 10 23:57 Tue 9 06:34 Mon 8 06:52 Sat 6 06:24 Fri 5 06:45 Thu 4 06:52 Wed 3 06:53 Tue 2 06:51

Riferimento del protocollo del gateway

Il contratto API tra Claude Code e un gateway LLM: endpoint, intestazioni e campi del corpo da inoltrare, degradazione delle funzionalità quando i campi vengono rimossi, intestazioni di attribuzione per il tracciamento dei costi e scoperta dei modelli.

Questa pagina documenta le richieste che Claude Code invia a un gateway, inclusi gli endpoint che chiama, le intestazioni e i campi del corpo che il gateway deve inoltrare, e quali funzionalità smettono di funzionare quando non lo fa. È scritta per gli operatori che configurano un prodotto gateway per funzionare con Claude Code.

Un gateway delle app Claude in esecuzione serve una versione leggibile da macchina di questo contratto su GET /protocol, coprendo gli stessi requisiti di inoltro più gli endpoint specifici del gateway delle app Claude per l'accesso SSO, la consegna delle impostazioni gestite e la telemetria. Il gateway delle app Claude viene eseguito dallo stesso binario claude della CLI, quindi la guida rapida del gateway delle app Claude è il percorso più breve verso un'istanza in esecuzione da cui è possibile recuperare la specifica.

Questa pagina copre:

Questa pagina utilizza due termini per quello che il vostro gateway fa con ogni intestazione e campo del corpo:

  • Inoltrare invariato: passarlo all'upstream byte per byte
  • Consumare: il gateway può leggerlo per il routing, l'attribuzione o il tracciamento e non è necessario inoltrarlo

Qualsiasi cosa non contrassegnata come inoltrare invariato è vostro da consumare o ignorare.

Formati API

Un gateway deve esporre almeno uno dei seguenti formati API ai client Claude Code. Quale formato Claude Code parla è determinato dalla configurazione del client: la variabile nella colonna Selezionato da della tabella sottostante punta Claude Code al vostro gateway in quel formato. Agent Platform è l'endpoint Claude di Google Cloud, precedentemente Vertex AI; i nomi delle sue variabili mantengono l'ortografia VERTEX.

Formato Selezionato da Endpoint Inoltrare invariato
Anthropic Messages ANTHROPIC_BASE_URL /v1/messages, /v1/messages/count_tokens (opzionale) intestazioni di richiesta anthropic-beta e anthropic-version
Bedrock InvokeModel ANTHROPIC_BEDROCK_BASE_URL con CLAUDE_CODE_USE_BEDROCK=1 /model/{model}/invoke, /model/{model}/invoke-with-response-stream campi del corpo della richiesta anthropic_beta e anthropic_version
Agent Platform rawPredict ANTHROPIC_VERTEX_BASE_URL con CLAUDE_CODE_USE_VERTEX=1 :rawPredict, :streamRawPredict, count-tokens:rawPredict (opzionale) intestazioni di richiesta anthropic-beta e anthropic-version, e il campo del corpo della richiesta anthropic_version

Foundry e Claude Platform on AWS

Microsoft Foundry e Claude Platform on AWS implementano il formato Anthropic Messages. Claude Code instrada verso di loro attraverso le loro variabili, ANTHROPIC_FOUNDRY_BASE_URL e ANTHROPIC_AWS_BASE_URL, ma un gateway che le fronteggia implementa la riga Anthropic Messages sopra. Un gateway che fronteggia Claude Platform on AWS deve anche inoltrare l'intestazione anthropic-workspace-id, che quella piattaforma richiede su ogni richiesta.

Endpoint opzionali e traffico di avvio

Gli endpoint di conteggio dei token sono gli unici opzionali: quando sono assenti, Claude Code stima l'utilizzo del contesto localmente. Le richieste di inferenza vengono inviate a /v1/messages?beta=true, quindi abbinate sul percorso, non sull'URL completo. Il metodo Agent Platform allega i suffissi al percorso del modello dell'editore, come in /projects/{project}/locations/{location}/publishers/anthropic/models/{model}:streamRawPredict.

Un gateway vede anche il traffico di avvio best-effort che può rifiutare senza rompere nulla: una sonda di connettività HEAD /, e su gateway in formato Bedrock una richiesta GET /inference-profiles?type=SYSTEM_DEFINED.

Streaming

Le risposte di inferenza devono essere in streaming. Claude Code consuma gli eventi inviati dal server mentre arrivano, quindi un gateway che memorizza nel buffer le risposte complete prima di inoltrarle blocca il client.

Mancata corrispondenza del formato con l'upstream

Quale formato il client parla determina cosa riceve il vostro gateway. La modalità di errore comune è una mancata corrispondenza tra il formato che il client invia al vostro gateway e il formato che il provider upstream dietro di esso accetta.

  • Quando il client parla il formato Bedrock o Agent Platform, Claude Code invia solo il sottoinsieme del suo set di capacità completo che quei provider accettano
  • Quando il client parla il formato Anthropic Messages, Claude Code invia il set completo, anche se il vostro gateway inoltra a un upstream Bedrock o Agent Platform

Colmare quella differenza è il compito del vostro gateway. Passaggio delle funzionalità descrive cosa si interrompe quando non lo fa.

Intestazioni delle richieste

Claude Code include queste intestazioni sulle richieste API. I nomi delle intestazioni non fanno distinzione tra maiuscole e minuscole sul filo. Inoltrare anthropic-version e anthropic-beta invariate, più anthropic-workspace-id quando l'upstream è Claude Platform on AWS; il resto il gateway può consumare per il routing, l'attribuzione e il tracciamento, e non è necessario inoltrare.

Intestazione Descrizione
Authorization, x-api-key La credenziale del gateway dello sviluppatore, in una o entrambe le intestazioni a seconda di quale variabile di credenziale impostano
anthropic-version Versione API, attualmente 2023-06-01. Le richieste in formato Bedrock e Agent Platform portano anche il campo del corpo anthropic_version, il cui valore è la stringa del dialetto del provider, non il valore di questa intestazione
anthropic-beta Valori di capacità separati da virgole per la richiesta. Inoltrare l'intestazione verbatim; non creare un elenco di consentiti dei singoli valori, perché l'insieme cambia con i rilasci di Claude Code. Quando lo sviluppatore si autentica con un accesso claude.ai, che è possibile quando ANTHROPIC_BASE_URL è impostato senza una variabile di credenziale del gateway, questa intestazione porta anche una capacità OAuth che l'upstream richiede, e rimuoverla fa fallire quelle richieste con 401
x-claude-code-session-id Un identificatore univoco per la sessione Claude Code corrente. Usarlo per aggregare tutte le richieste da una sessione senza analizzare i corpi delle richieste
x-claude-code-agent-id Identificatore del subagent che ha emesso la richiesta, presente solo sulle richieste da un agente che Claude Code ha generato all'interno della sessione. Usarlo con l'ID della sessione per attribuire il costo agli agenti paralleli
x-claude-code-parent-agent-id Identificatore dell'agente che ha generato l'agente richiedente, presente solo per gli agenti annidati

Gli ID dei subagent vengono generati freschi per ogni spawn. Gli agenti compagni, i membri denominati di un team di agenti, riutilizzano un ID stabile basato sul nome tra le riconnessioni. In entrambi i casi l'ID identifica un agente, non una persona o un dispositivo, quindi non trattate l'intestazione dell'ID dell'agente come un identificatore utente.

Se i vostri sviluppatori impostano ANTHROPIC_CUSTOM_HEADERS, quelle intestazioni appaiono anche sulle richieste.

Inoltrare come elenchi aperti

Trattate le intestazioni e i campi del corpo come elenchi aperti, non chiusi. Claude Code guadagna capacità nei rilasci, e arrivano come nuovi valori anthropic-beta, nuovi campi del corpo della richiesta, e occasionalmente nuove intestazioni anthropic-* o x-claude-code-*.

Quando inoltrate a un upstream in formato Anthropic, passate le intestazioni di richiesta anthropic-* e i campi del corpo della richiesta invariati piuttosto che creare un elenco di consentiti di quelli che vedete oggi. Un gateway bloccato a un elenco osservato rimuove l'intestazione o il campo della prossima capacità e lo interrompe nel rilascio che lo introduce.

L'eccezione è un upstream non-Anthropic come Bedrock o Agent Platform, dove colmare la differenza dello schema è il compito del gateway; vedere passaggio delle funzionalità.

Blocco di attribuzione del prompt di sistema

Claude Code antepone un breve blocco di attribuzione al prompt di sistema contenente la versione del client e un'impronta digitale derivata dalla conversazione. L'endpoint api.anthropic.com rimuove il blocco prima dell'elaborazione, quindi non influisce sul prompt caching di prima parte; qualsiasi altro upstream lo riceve come parte del prompt. Anthropic e gli endpoint Claude dei provider cloud lo leggono per l'attribuzione, quindi per ometterlo impostare CLAUDE_CODE_ATTRIBUTION_HEADER=0 piuttosto che rimuoverlo nel gateway.

{/* min-version: 2.1.181 */}Da Claude Code v2.1.181, il blocco è stabile per la durata di una conversazione quando le richieste instradano attraverso un URL di base personalizzato, quindi una cache del prompt lato gateway basata sul corpo della richiesta completa funziona senza disabilitarla. Prima di v2.1.181 il blocco includeva un token per richiesta; su quelle versioni, impostare CLAUDE_CODE_ATTRIBUTION_HEADER=0 se il vostro gateway implementa una tale cache.

Passaggio delle funzionalità

Claude Code tratta un gateway ANTHROPIC_BASE_URL come un endpoint in formato Anthropic e gli invia le intestazioni beta e i campi del corpo della richiesta che invia a api.anthropic.com, tranne un piccolo insieme di diagnostica e impostazioni predefinite riservate alle connessioni dirette, come l'impostazione predefinita di streaming fine degli strumenti coperta di seguito. Questo insieme varia per rilascio, quindi non dipendete dal suo contenuto.

Le capacità che aggiungono campi del corpo li associano a un'intestazione beta, e la coppia viaggia insieme. Un gateway che rimuove l'intestazione mentre passa il corpo, o inoltra un corpo in formato Anthropic a un upstream con uno schema diverso, produce errori 400 difficili; solo quando entrambe le metà sono assenti insieme la funzionalità si disattiva silenziosamente. Un gateway che riscrive o redige i corpi delle richieste per l'ispezione del contenuto interrompe l'associazione allo stesso modo della rimozione, quindi ispezionare senza modificare. La tabella nota dove una funzionalità si discosta dall'associazione.

Lo streaming fine degli strumenti è una delle impostazioni predefinite della connessione diretta: è disattivato per impostazione predefinita ogni volta che le richieste instradano attraverso un URL di base personalizzato, e un gateway lo riceve quando gli sviluppatori impostano CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING=1.

Funzionalità Intestazione e coppia del corpo Sintomo quando interrotto Rimedio
Ragionamento adattivo Nessuna intestazione beta. Claude Code invia thinking: {"type": "adaptive"} per Claude 4.6 e successivi, e tratta i nomi dei modelli che non riconosce, come gli alias del gateway, come modelli attuali che ricevono il campo 400 che nomina il campo thinking o il tag adaptive quando la build del modello upstream non lo accetta Aggiornare l'upstream. Su Opus 4.6 e Sonnet 4.6, gli sviluppatori possono invece impostare CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1
Gestione del contesto L'intestazione beta di gestione del contesto si associa al campo del corpo context_management 400 con Extra inputs are not permitted. Comune quando un gateway accetta richieste in formato Anthropic ma le inoltra a Bedrock Inoltrare entrambi, o CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
Contesto esteso e pensiero interleaved Solo intestazioni beta, nessun campo del corpo Silenziosamente non disponibile quando l'intestazione viene rimossa; l'upstream non vede mai la richiesta di capacità Inoltrare anthropic-beta verbatim
Beta tool fields Le intestazioni beta relative agli strumenti si associano ai campi dello schema dello strumento come strict e defer_loading 400 che nomina il campo dello schema dello strumento non riconosciuto quando il corpo passa attraverso senza la sua intestazione Inoltrare entrambi, o CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
Sforzo e output strutturati Il campo del corpo output_config contiene impostazioni di sforzo, formato di output strutturato e budget dei compiti; ciascuno si associa con la sua intestazione beta 400 che nomina output_config, spesso Extra inputs are not permitted, su upstream Bedrock e Agent Platform Inoltrare il campo e le sue intestazioni insieme
Conteggio dei token Nessun accoppiamento beta; utilizza l'endpoint count_tokens Claude Code ricade alla stima dell'utilizzo del contesto localmente Esporre l'endpoint se desiderate conteggi esatti

Le variabili ANTHROPIC_DEFAULT_*_MODEL_SUPPORTED_CAPABILITIES variables dichiarano le capacità del modello solo nelle configurazioni del provider: CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX, CLAUDE_CODE_USE_FOUNDRY, e CLAUDE_CODE_USE_MANTLE. Non hanno effetto dietro un gateway ANTHROPIC_BASE_URL.

Ritentativo automatico e inoltro degli errori

Claude Code ritenta automaticamente dopo alcuni rifiuti upstream e disabilita la capacità rifiutata per il resto della conversazione. I rifiuti del campo thinking, delle thinking signatures, e dei messaggi di sistema a metà conversazione si riprendono in questo modo. I rifiuti di gestione del contesto e di campi dello schema dello strumento non ritentano; quegli errori 400 raggiungono lo sviluppatore.

La logica di ritentativo corrisponde alla formulazione dell'errore dell'upstream, quindi inoltrare i corpi della risposta di errore invariati. Un gateway che avvolge gli errori upstream nel suo involucro interrompe il percorso di recupero anche quando preserva il codice di stato.

Disabilitare le capacità pre-release

CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 impedisce a Claude Code di inviare capacità pre-release e i loro campi del corpo su ogni provider, inclusa la gestione del contesto e i campi dello strumento beta. Non influisce sul ragionamento adattivo, che è selezionato dal modello piuttosto che da beta, e non sopprime mai la capacità OAuth che l'autenticazione della sottoscrizione richiede.

L'insieme delle capacità che Claude Code invia cresce nei rilasci. Per le stringhe di intestazione beta attuali, vedere il riferimento delle intestazioni beta; testare il vostro gateway contro i nuovi rilasci di Claude Code piuttosto che bloccare a un elenco osservato.

Scoperta dei modelli

Quando ANTHROPIC_BASE_URL punta a un gateway che espone il formato Anthropic Messages, Claude Code può interrogare l'endpoint /v1/models del gateway all'avvio e aggiungere i modelli restituiti al selettore /model.

Gli sviluppatori lo abilitano impostando CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1, nel loro ambiente o attraverso le impostazioni gestite. La scoperta è disattivata per impostazione predefinita in modo che i gateway supportati da una chiave API condivisa non espongano ogni modello a cui la chiave può accedere a ogni utente. Questo richiede Claude Code v2.1.129 o successivo.

Quando viene eseguita la scoperta

La scoperta si applica solo al formato Anthropic Messages. Non viene eseguita quando:

  • Qualsiasi variabile del provider CLAUDE_CODE_USE_* è impostata, anche se ANTHROPIC_BASE_URL è anche impostato
  • ANTHROPIC_BASE_URL non è impostato o punta a api.anthropic.com
  • Il traffico non essenziale è disabilitato, attraverso CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC o la politica dell'organizzazione

Richiesta e risposta

La richiesta è GET /v1/models?limit=1000 con un timeout di 3 secondi, e qualsiasi reindirizzamento è trattato come fallimento in modo che la credenziale non possa trapelare a una destinazione di reindirizzamento. Un gateway che risponde lentamente o reindirizza /v1/models, anche da http a https, fallisce la scoperta silenziosamente; servire l'endpoint direttamente all'URL di base configurato.

La richiesta di scoperta invia esattamente un'intestazione di credenziale:

  • ANTHROPIC_AUTH_TOKEN come token bearer, quando impostato
  • Altrimenti la chiave API risolta, incluso un valore apiKeyHelper, nell'intestazione x-api-key

Questo differisce dalle richieste di inferenza, che inviano un valore helper in entrambe le intestazioni. Un gateway che autentica /v1/models deve accettare x-api-key per le distribuzioni helper. Qualsiasi intestazione da ANTHROPIC_CUSTOM_HEADERS è inclusa anche.

Claude Code legge id e il display_name opzionale da ogni voce nell'array data della risposta, e ignora le voci il cui id non inizia con claude o anthropic:

{
  "data": [
    { "id": "claude-sonnet-4-6", "display_name": "Claude Sonnet 4.6" },
    { "id": "claude-opus-4-8" }
  ]
}

Voci del selettore e caching

Il selettore è l'elenco interattivo dei modelli che si apre quando uno sviluppatore esegue /model in Claude Code. Ogni voce scoperta è etichettata "From gateway" e utilizza display_name quando fornito. L'impostazione gestita availableModels limita quello che la scoperta può aggiungere.

Un ID scoperto viene saltato solo quando corrisponde esattamente a una riga già nel selettore, o quando sia l'ID scoperto che quello esistente si risolvono in Fable. Le righe integrate sono codificate su alias come sonnet, quindi un ID scoperto come claude-sonnet-4-6 aggiunge la sua propria riga "From gateway" accanto alla voce integrata piuttosto che sostituirla.

I risultati vengono memorizzati nella cache in ~/.claude/cache/gateway-models.json, o %USERPROFILE%\.claude\cache\gateway-models.json su Windows, e aggiornati ad ogni avvio. Se la richiesta fallisce o il gateway non implementa /v1/models, il selettore ricade all'elenco memorizzato nella cache dall'avvio precedente o all'elenco dei modelli integrati. Se il vostro gateway serve modelli Claude con alias che non corrispondono al filtro di scoperta, gli sviluppatori possono aggiungere quegli alias manualmente con le variabili di configurazione del modello.

Per il resto della serie di documentazione del gateway e i riferimenti API sottostanti: