Guida di compatibilità del gateway Claude Code

• Formati API e gli endpoint da servire per ciascuno
• Comportamento del client per metodo di connessione: come gli ID modello, i valori anthropic-beta, i campi di richiesta e i valori predefiniti differiscono tra i formati e un accesso al gateway delle app Claude
• Intestazioni di richiesta: quali devono raggiungere l’upstream e quali il tuo gateway può consumare
• Intestazioni di risposta: cosa restituire affinché il rilevamento dei blocchi, i tentativi e la visualizzazione del limite di utilizzo funzionino
• Il blocco di attribuzione del prompt di sistema e come interagisce con la memorizzazione nella cache dei prompt
• Passaggio delle funzionalità: cosa si interrompe quando le intestazioni o i campi del corpo vengono rimossi
• Scoperta dei modelli

• Inoltra invariato: passalo all’upstream byte per byte
• Consuma: il gateway può leggerlo per il routing, l’attribuzione o la traccia e non è necessario inoltrarlo

​

Formati API

​

Foundry e Claude Platform on AWS

​

Endpoint opzionali e traffico di avvio

• Le richieste di inferenza vengono inviate a /v1/messages?beta=true
• Il metodo Google Cloud’s Agent Platform i suffissi si allegano al percorso del modello dell’editore, come in /projects/{project}/locations/{location}/publishers/anthropic/models/{model}:streamRawPredict

​

Streaming

• Se il tuo gateway memorizza nel buffer una risposta finché non è completa, Claude Code si blocca.
• Claude Code si aspetta la sequenza di eventi completa di ogni risposta, in ordine, fino agli eventi finali message_delta e message_stop. Se il corpo termina in modo pulito dopo che un blocco di contenuto è iniziato ma prima di quel message_delta finale, Claude Code tratta la risposta come una connessione interrotta. La risposta sopra potrebbe essere incompleta descrive ciò che l’utente vede in quel caso, e Tentativi automatici indica quando Claude Code invece invia di nuovo la richiesta.
• Quando un guardrail di Amazon Bedrock blocca una risposta, gli eventi che Bedrock invia possono fare riferimento a un blocco di contenuto il cui content_block_stop è già arrivato, e Claude Code si basa sul riceverli così come sono stati inviati. AWS Guardrails descrive come termina quella risposta.
• Claude Code interrompe una risposta in streaming quando nessun byte lo raggiunge per un tempo superiore al suo timeout di inattività dello streaming. Durante una lunga pausa di ragionamento, gli eventi SSE ping dell’upstream possono essere gli unici byte sul flusso, quindi un gateway che li elimina o li memorizza nel buffer può far scattare quel timeout a metà di una risposta. Un gateway che traduce da un upstream senza ping, come l’event stream binario di Amazon Bedrock, presenta la stessa lacuna a meno che non emetta i propri eventi ping.
• Con il formato Amazon Bedrock InvokeModel, Claude Code legge la risposta di /model/{model}/invoke-with-response-stream come il corpo binario application/vnd.amazon.eventstream restituito da Bedrock, e non riesce ad analizzarlo se un gateway lo converte in server-sent events o riscrive l’header Content-Type. Errori di streaming dietro un gateway o proxy descrive ciò che l’utente vede in quel caso.

​

Mancata corrispondenza di formato con l’upstream

• Quando il client parla il formato Amazon Bedrock o Google Cloud’s 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 Amazon Bedrock o Google Cloud’s Agent Platform

​

Come il metodo di connessione cambia il comportamento del client

• Formato Amazon Bedrock o Agent Platform: lo sviluppatore imposta CLAUDE_CODE_USE_BEDROCK=1 con ANTHROPIC_BEDROCK_BASE_URL, oppure CLAUDE_CODE_USE_VERTEX=1 con ANTHROPIC_VERTEX_BASE_URL, puntando al vostro gateway. Claude Code utilizza gli ID modello, i campi di richiesta e le impostazioni predefinite di quel provider.
• Formato Anthropic Messages: lo sviluppatore imposta ANTHROPIC_BASE_URL al vostro gateway. Claude Code tratta il gateway come l’API Claude e non può determinare quale upstream state inoltrando.
• Accesso al gateway delle app Claude: lo sviluppatore accede a un gateway delle app Claude. Quel gateway parla il formato Anthropic Messages ma può instradare a qualsiasi upstream, quindi Claude Code invia solo i valori anthropic-beta e le assunzioni sulle capacità del modello che anche Amazon Bedrock e Agent Platform accettano.

​

Richieste e impostazioni predefinite per metodo di connessione

​

Impostazioni per ID modello non riconosciuti

• Finestra di contesto: Claude Code assume 200K, o 1M quando l’ID contiene [1m]. Per dichiarare la finestra reale, consultate Correggere la finestra per un gateway o un ID modello personalizzato
• Capacità: per dare a un alias del gateway le capacità del modello dietro di esso, mappate l’ID Anthropic di quel modello al vostro alias con una voce modelOverrides nelle impostazioni che distribuite. Per dove si applicano le variabili ANTHROPIC_DEFAULT_*_MODEL_SUPPORTED_CAPABILITIES, consultate feature pass-through

​

Intestazioni delle richieste

​

Intestazioni di suggerimento del gateway

• Connessione diretta all’API Anthropic: inviati per impostazione predefinita
• URL di base personalizzato: disattivato per impostazione predefinita, perché un proxy che rifiuta intestazioni sconosciute farebbe fallire la richiesta. Per riceverli, impostare CLAUDE_CODE_GATEWAY_HINT_HEADERS=1 per i vostri sviluppatori, ad esempio nel blocco env delle impostazioni gestite
• Qualsiasi altro backend, inclusi Amazon Bedrock, Agent Platform di Google Cloud, Microsoft Foundry e Claude Platform on AWS: inviati solo quando CLAUDE_CODE_GATEWAY_HINT_HEADERS=1 è impostato

• Voci: una per ogni chiamata di strumento che è stata eseguita, nell’ordine in cui il suo risultato è stato raccolto, in millisecondi interi
• Limite: Claude Code invia al massimo 32 voci e 4 KB, mantenendo le prime voci
• Codifica: i nomi degli strumenti sono codificati in percentuale, coprendo %, ;, =, virgola, spazio e qualsiasi carattere al di fuori di ASCII stampabile
• Analisi: dividere su ;, quindi su =, e decodificare ogni nome
• Assenza: le chiamate di compattazione, le richieste laterali e la prima richiesta di un nuovo prompt non la portano mai. Non leggere un’intestazione mancante come un turno che non ha eseguito alcuno strumento
• Tempi: ognuno esclude i prompt di autorizzazione e gli hook, e le chiamate di strumento parallele ciascuna segnalano il proprio tempo, quindi le voci non si sommano al divario tra le richieste

​

Inoltrare come elenchi aperti

​

Intestazioni di risposta

​

Blocco di attribuzione del prompt di sistema

• Inoltrare l’array system esattamente come ricevuto, mantenendo il blocco per primo: anteporre un altro blocco di sistema, riordinare l’array o convertirlo in una singola stringa annulla la rimozione, e il blocco raggiunge quindi il modello e la chiave della cache del prompt.
• Mantenere il blocco nella sua voce di array separata: l’endpoint tratta un blocco unito che inizia con l’intestazione di attribuzione come attribuzione nella sua interezza e scarta tutto ciò che vi è stato unito, incluso il resto del prompt di sistema.
• Se il vostro gateway deve rimodellare il contenuto di sistema, impostare CLAUDE_CODE_ATTRIBUTION_HEADER=0 in modo che Claude Code ometta il blocco. Anthropic e gli endpoint Claude dei provider cloud leggono il blocco per l’attribuzione, quindi ometterlo nel client piuttosto che rimuoverlo o spostarlo nel gateway.

• Le richieste vanno a api.anthropic.com, con ANTHROPIC_BASE_URL non impostato o che nomina quell’host e nessun provider di terze parti selezionato.
• La credenziale attiva non è una credenziale di profilo Anthropic o di federazione.

• Implementa una cache del prompt basata sul corpo della richiesta.
• Inoltra richieste a un provider di terze parti come Amazon Bedrock, Microsoft Foundry, o Google Cloud’s Agent Platform, nel formato Anthropic Messages o nel formato proprio del provider, dove il prefisso mutevole riduce il riutilizzo della cache del prompt su quel provider.

​

Passaggio delle funzionalità

​

Coppie di intestazione beta e campo del corpo

​

Ritentativo automatico e inoltro degli errori

• Quando un 400 indica che il valore enabled o adaptive di thinking.type non è supportato, Claude Code riprova una volta con l’altro tipo e mantiene il campo thinking. Le richieste successive a quel modello mantengono il tipo cambiato finché Claude Code non esce. Prima della v2.1.121, Claude Code non riprovava, quindi thinking.type.enabled is not supported raggiungeva lo sviluppatore
• Quando l’upstream rifiuta una voce role: "system" all’interno di messages, Claude Code riprova una volta senza quei messaggi di sistema a metà conversazione e ne riporta invece il testo nei messaggi utente. Le richieste successive nella conversazione mantengono quella forma finché lo sviluppatore non esegue /clear o la conversazione non viene compattata
• Quando l’upstream rifiuta solo il marcatore cache_control su un messaggio di sistema a metà conversazione, Claude Code mantiene i messaggi di sistema e riprova una volta con il marcatore spostato. Il marcatore va sull’ultima voce in messages che non è un messaggio di sistema, in quel nuovo tentativo e nelle richieste successive finché Claude Code non esce
• Quando l’upstream rifiuta una thinking signature, incluso con un 400 il cui messaggio dice che il blocco è bound to a different conversation, Claude Code rimuove i blocchi di pensiero precedenti dalla richiesta, ritenta, e li mantiene fuori da ogni richiesta successiva. Le nuove risposte includono ancora il pensiero
• Quando il gateway o il suo upstream rifiuta la voce dello strumento advisor in tools come tipo di strumento non riconosciuto, Claude Code riprova una volta senza quella voce e il suo valore anthropic-beta. Le richieste successive li omettono. Claude Code riconosce questo rifiuto da una risposta 400 o 422 il cui messaggio nomina il tipo di strumento dopo Input tag, come Input tag 'advisor_20260301'. Prima della v2.1.280, Claude Code non riprovava dopo questo rifiuto
• Quando l’upstream rifiuta output_config.effort o il suo valore anthropic-beta, il gateway vede la richiesta ancora una volta senza di essi. Le richieste successive li omettono. Il tuo gateway non richiede modifiche se inoltra il 400 dell’upstream senza modificarlo e il messaggio:
  • Nomina output_config.effort insieme a Extra inputs are not permitted
  • Dice che il modello non supporta il parametro di sforzo
  • Inizia con Unexpected value(s) ed elenca effort-2025-11-24 per l’intestazione anthropic-beta. Richiede la v2.1.310 o successiva. Gli sviluppatori il cui ANTHROPIC_BETAS elenca il valore continuano a inviarlo e a ricevere il 400, quindi chiedi loro di rimuovere quella voce
• Quando l’upstream rifiuta il campo context_management o il suo valore anthropic-beta, il gateway vede la richiesta ancora una volta senza di essi. Le richieste successive li omettono. Claude Code riconosce questo rifiuto dal suo messaggio, ad esempio uno contenente context_management: Extra inputs are not permitted. Prima della v2.1.304, Claude Code non riprovava dopo questo rifiuto
• Quando un 400 rifiuta per nome un altro valore anthropic-beta, il gateway vede la richiesta ancora una volta senza di esso se il nuovo tentativo copre quel valore
• Quando l’upstream rifiuta un campo beta degli strumenti diverso da defer_loading, come strict, il 400 raggiunge lo sviluppatore. Prima di ciò, il gateway può vedere di nuovo la richiesta senza i campi della ricerca degli strumenti. Per smettere di inviare tali campi, chiedi agli sviluppatori di impostare CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

​

Riprovare senza un valore beta rifiutato

• La frase dell’API: la frase Unexpected value(s) che elenca il valore per l’intestazione anthropic-beta
• Un token beta_header:: capability_rejected: beta_header: seguito dal valore, un token capability_rejected:

• Un valore con un proprio nuovo tentativo, come advisor o la ricerca degli strumenti: il gateway vede invece il nuovo tentativo specifico di quella capacità
• Un valore che Claude Code non riconosce: un valore che uno sviluppatore ha impostato tramite ANTHROPIC_BETAS rimane su ogni richiesta, quindi le richieste dello sviluppatore continuano a fallire con il 400. Chiedi allo sviluppatore di rimuovere la voce
• Un semplice invalid beta flag: Claude Code ipotizza quale valore l’upstream abbia rifiutato. Se la richiesta conteneva un valore tra quelli che ipotizza, il gateway vede di nuovo la richiesta senza quel valore. Se il 400 raggiunge ancora lo sviluppatore, fai in modo che il tuo gateway nomini il valore rifiutato in una di quelle forme

​

Per quanto tempo un valore beta rifiutato resta escluso

​

Riprovare senza la ricerca degli strumenti

​

Disabilitare le capacità pre-release

• La gestione del contesto e il suo campo del corpo context_management
• I campi beta dello schema degli strumenti, come strict e defer_loading. I campi standard degli strumenti name, description, input_schema e cache_control rimangono
• Il campo di output strutturato output_config.format. Richiede Claude Code v2.1.287 o successivo
• Il campo output_config.task_budget
• MCP Tool Search, quindi ogni strumento MCP viene caricato subito, a meno che la tua organizzazione non lo mantenga attivo tramite le impostazioni gestite

• I valori anthropic-beta per contesto esteso, ragionamento interleaved e sforzo, che anche i provider cloud accettano
• Il campo output_config.effort di primo livello. Nuovi tentativi automatici e inoltro degli errori tratta il caso di un upstream che lo rifiuta
• Il campo thinking del ragionamento adattivo, che non ha un’intestazione beta
• Le voci role: "system" che contengono i messaggi di sistema a metà conversazione
• Il valore anthropic-beta OAuth richiesto dall’autenticazione tramite abbonamento
• I valori di intestazione e i campi del corpo che gli sviluppatori aggiungono autonomamente tramite ANTHROPIC_BETAS o CLAUDE_CODE_EXTRA_BODY

• Su una connessione diretta senza la configurazione HIPAA, o attraverso un gateway impostato con ANTHROPIC_BASE_URL, Claude Code continua a inviare l’intestazione beta di ricerca degli strumenti, i campi dello strumento defer_loading e i blocchi tool_reference
• Su un provider cloud, o accedendo attraverso un gateway delle app Claude, l’override non ha effetto
• In una sessione che riceve la configurazione HIPAA, l’override non ha effetto e la ricerca degli strumenti rimane disattivata

​

Scoperta dei modelli

​

Quando viene eseguita la scoperta

• 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

​

Richiesta e risposta

• Authorization: ANTHROPIC_AUTH_TOKEN come token bearer, altrimenti il valore apiKeyHelper come token bearer.
• x-api-key: la chiave API che Claude Code ha risolto, come ANTHROPIC_API_KEY. Quando un valore helper è l’unica credenziale, questa intestazione lo trasporta anche, in modo che il valore arrivi in entrambe le intestazioni.

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

​

Voci del selettore e caching

• Stesso ID: l’ID scoperto corrisponde esattamente all’ID di una riga esistente, oppure i due ID sono ortografie della stessa versione Fable.
• Stesso modello di un alias integrato: quando un ID esplicito scoperto nomina il modello a cui un alias integrato attualmente si risolve, il selettore mostra solo la riga dell’alias. Ad esempio, mentre sonnet si risolve in claude-sonnet-5-5, un claude-sonnet-5-5 scoperto si comprime nella riga sonnet, e un claude-sonnet-5 scoperto ottiene comunque la sua propria riga.

​

Risorse correlate

• Panoramica dei gateway: cos’è un gateway e come scegliere tra l’app gateway Claude e un altro prodotto
• Altri gateway LLM: come implementare un gateway che la vostra organizzazione gestisce e come interagisce con le sottoscrizioni claude.ai
• Distribuire un gateway LLM per la vostra organizzazione: la checklist dell’amministratore che utilizza questa guida
• Connettere Claude Code a un gateway LLM: configurazione per sviluppatore e la tabella di risoluzione dei problemi
• Riferimento delle intestazioni beta: l’insieme attuale dei valori anthropic-beta
• API Messages: il formato API che un gateway in formato Anthropic implementa