Claude Code: Configurazione dell'endpoint API personalizzato tramite gateway di terze parti con modelli open-source cinesi

Claude Code può essere configurato per comunicare con un endpoint compatibile con Anthropic invece di utilizzare direttamente un endpoint del fornitore. Questo consente di testare un flusso di lavoro gestito da un gateway con ID modello esposti dal gateway, incluso per i modelli open-source cinesi presenti nel catalogo attuale di ECAIX.

Questa guida riguarda un flusso di lavoro di compatibilità specifico per il fornitore. La documentazione ufficiale del gateway di Claude Code di Anthropic spiega che Anthropic non supporta il routing di Claude Code verso modelli non Claude tramite un gateway. ECAIX non afferma che questo flusso di lavoro sia ufficialmente supportato da Anthropic, e un modello non Claude potrebbe non fornire tutte le capacità di Claude Code.

Avvio rapido

Se hai già compreso i limiti di compatibilità, segui prima questo percorso breve:

1. Apri il catalogo attuale dei modelli ECAIX e scegli un ID modello attivo.
2. Crea una chiave API ECAIX e mantienila fuori dal controllo di versione.
3. Imposta ANTHROPIC_BASE_URL su https://ecaix.com/api/ai/v1/anthropic.
4. Esegui la richiesta diagnostica sottostante e registra lo stato HTTP.
5. Esegui Claude Code in un progetto di test in sola lettura con claude -p.
6. Testa gli strumenti, lo streaming, i limiti di contesto e le autorizzazioni separatamente.

Stato di validazione alla pubblicazione

Questa tabella è intenzionalmente distinta: un esempio di configurazione non è lo stesso di un risultato di compatibilità misurato.

Cosa cambia questa configurazione

La configurazione ha quattro parti separate:

1. Claude Code è il client che crea compiti di coding e invia richieste.
2. Il gateway compatibile con Anthropic riceve richieste in un endpoint di stile Anthropic.
3. L'ID modello seleziona il modello upstream esposto dal gateway.
4. La chiave API autentica la richiesta e determina l'account, il limite di quota e le autorizzazioni.

Cambiare l'endpoint non trasforma un modello non Claude in Claude. Cambia solo quale superficie API compatibile riceve la richiesta. L'uso degli strumenti, la gestione del contesto, gli alias dei modelli, il comportamento dello streaming e i flussi di autorizzazione possono variare in base alla versione del client e alla implementazione del gateway.

Prima di iniziare

Servono:

• Un'installazione di Claude Code che supporta la configurazione dell'endpoint tramite ambiente o impostazioni.
• Una chiave API ECAIX.
• Un ID modello attualmente presente nel catalogo dei modelli ECAIX.
• Un terminale dove puoi eseguire una piccola richiesta di test senza esporre la chiave API nel controllo di versione.

Il catalogo cambia nel tempo. Prima di copiare un ID modello in un file di configurazione, apri la direttiva dei modelli ECAIX e conferma che il modello è attivo e disponibile per lo stile API che intendi utilizzare.

Configurare il gateway dell'endpoint

Claude Code memorizza le impostazioni in ~/.claude/settings.json su molte installazioni. La schema delle impostazioni può cambiare, quindi tratti il seguente come un modello di partenza e confrontalo con la documentazione della tua versione installata.

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://ecaix.com/api/ai/v1/anthropic",
    "ANTHROPIC_API_KEY": "YOUR_ECAIX_API_KEY",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT": "1"
  },
  "model": "deepseek-v4.1-flash"
}

Non commetta questo file se contiene una chiave API reale. Preferisci una variabile ambientale locale, un gestore di segreti o il meccanismo di credenziali raccomandato dalla tua installazione di Claude Code.

Puoi anche configurare l'endpoint in una sessione shell durante il test:

export ANTHROPIC_BASE_URL="https://ecaix.com/api/ai/v1/anthropic"
export ANTHROPIC_API_KEY="YOUR_ECAIX_API_KEY"
export ANTHROPIC_MODEL="deepseek-v4.1-flash"

I nomi delle variabili e le impostazioni supportate da una particolare versione di Claude Code possono cambiare. Se il client ignora ANTHROPIC_MODEL, usa il campo modello o il meccanismo di alias dei modelli documentato dalla tua versione. Il gateway deve comunque riconoscere l'ID modello finale.

Verifica prima dell'endpoint compatibile con Anthropic

Prima di avviare una sessione di coding interattiva, invia una piccola richiesta. Questo separa i problemi di endpoint, autenticazione e ID modello dai comportamenti specifici di Claude Code.

Il comando sotto salva separatamente i header e il corpo della risposta, poi stampa lo stato HTTP. Usa una chiave autorizzata solo nella shell locale; mai incollala in un articolo, un problema o un log condiviso.

curl -sS -D /tmp/ecaix-anthropic-headers.txt \
  -o /tmp/ecaix-anthropic-response.json \
  -w '\nHTTP %{http_code}\n' \
  "${ANTHROPIC_BASE_URL}/messages" \
  -H "x-api-key: ${ANTHROPIC_API_KEY}" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "deepseek-v4.1-flash",
    "max_tokens": 128,
    "messages": [
      {"role": "user", "content": "Reply with one short sentence."}
    ]
  }'

Interpretazione attesa:

• 200: ispeziona la forma della risposta e conferma i campi modello o di utilizzo restituiti.
• 401 o 403: verifica la chiave, l'intestazione, lo scope dell'account e delle autorizzazioni prima di modificare il prompt.
• 404: verifica l'URL base, il suffisso /messages e la deploy dell'endpoint.
• 400: riduci la richiesta al corpo più piccolo valido e verifica i campi specifici del modello.
• 5xx o timeout: registra il tempo di richiesta e il corpo della risposta, poi separa il comportamento di timeout del gateway, upstream e del client.

Una risposta riuscita conferma che la chiave, l'endpoint, la formattazione della richiesta e l'ID modello hanno funzionato insieme per quella richiesta. Non prova che tutte le funzionalità di Claude Code funzionino.

Scegliere un ID modello

Il catalogo ECAIX contiene famiglie di modelli da fornitori cinesi. L'ID modello giusto dipende dalla task, non solo dal nome del modello.

Sviluppo e coding generale

Inizia con un modello attuale DeepSeek, Qwen, GLM o Seed capace di coding visibile nel catalogo. Ad esempio, un catalogo potrebbe esporre ID come deepseek-v4.1-flash, qwen3.8-flash, glm-5.3 o seed-2.0-code. La disponibilità e le capacità possono cambiare, quindi verifica sempre la pagina del modello attuale prima di pubblicare una configurazione.

Lavoro su repository e documenti tecnici lunghi

Per grandi repository o documenti tecnici lunghi, confronta la lunghezza del contesto mostrata nella pagina del modello. Una finestra di contesto più grande non significa automaticamente risultati migliori per repository: la struttura del prompt, il supporto agli strumenti, i limiti di output e i limiti di richiesta del gateway contano anche.

Flussi di lavoro agenti e chiamate di strumenti

Se il flusso di lavoro richiede chiamate di strumenti o strumenti, verifica la documentazione del modello e dell'endpoint. Alcuni fornitori esponono le chiamate di strumenti tramite API compatibili con OpenAI, mentre altri esponono nomi di campo diversi o supportano solo una sottoclasse di comportamento degli strumenti. Inizia con un test di chiamata di strumento semplice prima di dare accesso al modello a un repository reale o a un sistema esterno.

Sviluppo di lavoro in lingua cinese

I modelli open-source cinesi possono essere utili quando il codice, la documentazione, il tracker di problemi o il flusso di lavoro della squadra contiene materiali in lingua cinese. Valuta il modello con i tuoi prompt e campioni di repository invece di basarti solo su classifiche generali.

Testare Claude Code dopo che la richiesta API funziona

Una volta che la richiesta diretta è riuscita, inizia con un comando in sola lettura o a basso rischio:

claude -p "Explain what this repository does without editing files."

Poi prova una task strettamente limitata. Ad esempio:

claude -p "List the likely entry points for the web application. Do not modify files."

Utilizza test sempre più impegnativi:

1. Risposta in testo puro.
2. Spiegazione breve di codice.
3. Navigazione di repository.
4. Modifica controllata in una branch temporanea.
5. Utilizzo di strumenti o compiti multi-passi.
6. Comportamento di streaming e contesto lungo.

Non assumere che una risposta di testo riuscita dimostri che i prompt di autorizzazione, le chiamate di strumenti, lo streaming, i limiti di contesto o l'editing di file si comportino identicamente come in una sessione di Claude Code.

Scegliere la strada API giusta

Claude Code è solo un flusso di lavoro client. La strada API giusta dipende dal client e dall'insieme di funzionalità che vuoi utilizzare:

Per ECAIX, usa la documentazione delle Messaggi Anthropic per la strada di stile Anthropic e la documentazione delle Chat Completions per client compatibili con OpenAI. Usa la direttiva dei modelli per confermare il modello attuale e la pagina dei prezzi per i prezzi attuali mostrati.

Matrice di compatibilità

La seguente matrice è un limite di evidenza al momento della pubblicazione, non un'affermazione che ogni funzionalità sia supportata:

Questa distinzione impedisce di presentare una richiesta minima riuscita come certificazione completa della compatibilità di Claude Code.

Pagine dettagliate dei modelli e ID attuali

Usa le pagine dettagliate dei modelli invece di copiare un vecchio nome di modello da un blog:

• DeepSeek v4.1 Flash
• Qwen 3.8 Flash
• GLM 5.3
• [Kimi K3](/models/kimi/k