IT ▾

HomeGuida

Configurazione del proxy Claude Code con un'API compatibile con OpenAI

Questa configurazione del proxy di Claude Code richiede cinque passaggi: ottenere una chiave, scrivere una configurazione LiteLLM, avviare il proxy, impostare due variabili d'ambiente ed eseguire un test. Richiede circa dieci minuti.

Cinque pietre di attraversamento luminose che conducono da un terminale a un server, che mostrano una configurazione del proxy passo dopo passo

Punti chiave

  1. Esegui un proxy LiteLLM locale che inoltra a https://api.claudecodeproxyapi.com/v1
  2. Indirizza Claude Code al proxy con ANTHROPIC_BASE_URL e ANTHROPIC_AUTH_TOKEN
  3. Mappa il nome del modello che invia Claude Code al modello upstream uncensored
  4. Testa il proxy con curl prima di avviare la CLI

Cosa ti serve

  • Una chiave API dalla pagina delle chiavi. Iscriviti con Google o email e password, poi richiedi il credito di prova da $0,50 con un clic.
  • Python 3.9 o versione successiva, per installare il proxy.
  • Claude Code installato e funzionante sulla tua macchina.

Perché un proxy? Claude Code parla il formato Anthropic Messages, e la nostra API parla il formato OpenAI Chat Completions con l'ID del modello uncensored. Il proxy traduce tra i due. Se vuoi prima il contesto, leggi la guida alla risoluzione dei problemi del proxy. Il modello è un modello a pesi aperti, non Claude, quindi aspettati un comportamento diverso su task multi-step difficili.

Passo 1: installa il proxy

Usa un ambiente virtuale in modo che le dipendenze del proxy rimangano separate dai tuoi progetti:

python3 -m venv ~/litellm-env
source ~/litellm-env/bin/activate
pip install 'litellm[proxy]'

LiteLLM è un software open-source di terze parti. I comandi e le chiavi di configurazione qui sotto corrispondono alla sua documentazione pubblica al momento della scrittura, ma controlla la sua documentazione corrente se un flag è cambiato.

Passo 2: scrivi la configurazione

Crea config.yaml. Il model_name è il nome che invia il client. Il blocco litellm_params indica dove inoltrarlo. Il prefisso openai/ dice a LiteLLM di parlare con un server compatibile OpenAI.

cat > config.yaml <<'EOF'
model_list:
  - model_name: claude-sonnet
    litellm_params:
      model: openai/uncensored
      api_base: https://api.claudecodeproxyapi.com/v1
      api_key: os.environ/UPSTREAM_KEY
EOF

L'alias claude-sonnet è un esempio, non un requisito. Claude Code può inviare diversi nomi di modello, ad esempio un modello principale e uno più piccolo per i task in background. Aggiungi una voce model_list per ogni nome che vedi nel log del proxy, tutte puntate allo stesso upstream. Indirizzare ogni alias a uncensored va bene, perché c'è solo un modello.

La chiave viene letta da una variabile d'ambiente in modo che non finisca mai in un file che potresti committare.

Passo 3: avvia il proxy

export UPSTREAM_KEY="YOUR_KEY"
litellm --config config.yaml --port 4000

Lascia aperto questo terminale. Dovresti vedere il server in ascolto sulla porta 4000. Ora controlla il percorso upstream dal lato del proxy con una richiesta di test nel formato Anthropic, che è ciò che invierà Claude Code:

curl http://localhost:4000/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: sk-local-anything" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet",
    "max_tokens": 200,
    "messages": [{"role": "user", "content": "Reply with the word ready."}]
  }'

Una risposta JSON il cui contenuto include la parola "ready" significa che la traduzione funziona da capo a fondo: formato Anthropic in, formato OpenAI a https://api.claudecodeproxyapi.com/v1, e ritorno. Se imposti una chiave master nella configurazione LiteLLM, usala al posto di sk-local-anything.

Passo 4: indirizza Claude Code al proxy

Claude Code legge il suo indirizzo API e token dalle variabili d'ambiente. Impostali nella shell in cui avvii la CLI:

export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_AUTH_TOKEN="sk-local-anything"
export ANTHROPIC_MODEL="claude-sonnet"
claude

Usa l'indirizzo del proxy senza un suffisso /v1 qui, perché la CLI aggiunge il proprio percorso. Il token deve solo soddisfare il proxy, poiché la vera chiave upstream è quella che hai esportato come UPSTREAM_KEY. Se usi il file di impostazioni della CLI per i valori delle variabili d'ambiente invece che dalla shell, inserisci gli stessi tre nomi lì. I nomi delle variabili d'ambiente per Claude Code possono cambiare tra le release, quindi verificale contro la documentazione corrente di Claude Code se qualcosa viene ignorato.

Passo 5: esegui un primo task e osserva il log

Inizia in piccolo. Chiedi alla CLI di spiegare un file o di aggiungere un commento a una funzione. Nel terminale del proxy dovresti vedere una richiesta per ogni passaggio. Nota ogni nome di modello che appare; se uno non è nella tua model_list, il proxy risponde con un errore, quindi aggiungilo e riavvia.

La chiamata di funzioni è importante qui, poiché la CLI legge i file e modifica il codice attraverso gli strumenti. L'API supporta tools, tool_choice e tool_calls in streaming, e il proxy li converte. Una minore aderenza a uno schema degli strumenti si manifesta come una modifica fallita o un passaggio ripetuto. Quando succede questo, accorcia il task e riprova prima di decidere che la configurazione è rotta.

La finestra di contesto è di 100.000 token, prompt e completamento insieme. Sessioni lunghe che superano questo limite falliranno, quindi avvia una nuova sessione per un nuovo task. I costi sono minimi a $0,15 per 1M di token di input e $0,50 per 1M di token di output: una richiesta con 20.000 token in entrata e 800 in uscita costa $0,003 + $0,0004 = $0,0034. Vedi la pagina dei prezzi per le ricariche, che su questo sito sono pagate tramite cripto (USDT su TRC20, USDC su Base).

Risoluzione dei Problemi

Quello che vediCausaSoluzione
Connessione rifiutataIl proxy non è in esecuzione o la porta è diversaAvvialo e fai corrispondere la porta in ANTHROPIC_BASE_URL
Proxy 404 o "modello non trovato"Il nome del modello inviato dalla CLI non è nella configurazioneAggiungi quel nome a model_list
Upstream 401UPSTREAM_KEY errata o vuotaRiesporta la chiave nella shell del proxy e riavvia
429 con concurrencyPiù di 8 richieste parallele (2 nella prova)Riduci gli agenti paralleli
429 con rate_limitedPiù di 300 richieste al minuto (60 in prova)Riduci la frequenza e riprova
429 con Retry-After: 5Sovraccarico temporaneoRiprova dopo cinque secondi
Flusso bloccatoUna richiesta in streaming tiene il suo slot fino alla fineAnnullala nella CLI per liberare lo slot

Per qualsiasi cosa non coperta qui, includi l'intestazione di risposta X-Request-Id quando scrivi al supporto. La documentazione elenca ogni parametro supportato.

Rendi permanente

Digitare le esportazioni ogni volta diventa noioso. Metti l'avvio del proxy in un piccolo script e le variabili del client in un alias, in modo che un comando attivi tutto:

cat > ~/start-proxy.sh <<'EOF'
. ~/litellm-env/bin/activate
export UPSTREAM_KEY="YOUR_KEY"
exec litellm --config ~/config.yaml --port 4000
EOF
chmod +x ~/start-proxy.sh

alias claude-uncensored='ANTHROPIC_BASE_URL=http://localhost:4000 ANTHROPIC_AUTH_TOKEN=sk-local-anything ANTHROPIC_MODEL=claude-sonnet claude'

Poiché le variabili sono impostate solo per quel comando, il tuo comando claude normale continua a funzionare con le sue impostazioni predefinite. Aggiungi l'alias al tuo profilo della shell. Proteggi lo script con i permessi di file come chmod 700, poiché contiene la tua chiave.

Tornare indietro

Se hai esportato le variabili nella shell corrente, esegui unset ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN ANTHROPIC_MODEL e avvia di nuovo la CLI. Nulla è cambiato sul lato API, quindi non c'è nulla da annullare.

Monitorare il tuo saldo e le spese

Ogni risposta dell’API include X-Balance-USD, il credito residuo sulla tua chiave. LiteLLM può inoltrare le intestazioni upstream in alcune configurazioni, ma il modo più sicuro per verificare il tuo saldo è chiamare direttamente l’upstream di tanto in tanto:

curl -i https://api.claudecodeproxyapi.com/v1/models \
  -H "Authorization: Bearer YOUR_KEY" | grep -i x-balance-usd

Le sessioni dell'agent crescono in silenzio. Ogni passaggio rispedisce il contesto di lavoro, quindi una sessione lunga costa di più per richiesta rispetto a una breve. Avviare una nuova sessione per ogni compito mantiene l'input piccolo e il conto basso. Ai prezzi pubblicati ($0.15 per 1M di input e $0.50 per 1M di output), una richiesta con 50.000 token in input e 1.000 in output costa 50.000 x $0.15 / 1M = $0.0075 più $0.0005, che è $0.008. Venti di queste richieste ammontano a $0.16.

Le ricariche vanno da $20 a $500 in importi interi e si pagano con criptovalute (USDT su TRC20 o USDC su Base) su questo sito. Il credito non scade mai, quindi una ricarica più grande con il bonus del +5%, +10% o +15% non mette un limite di tempo al tuo saldo.

Domande e risposte

Quali variabili d’ambiente serve a Claude Code per un proxy?

ANTHROPIC_BASE_URL per l’indirizzo del proxy e ANTHROPIC_AUTH_TOKEN per un token che il proxy accetta. ANTHROPIC_MODEL può indicare l’alias che hai definito. Controlla la documentazione attuale di Claude Code per eventuali modifiche.

Devo mettere /v1 su ANTHROPIC_BASE_URL?

No. Usa l’indirizzo del proxy come http://localhost:4000, perché l’app CLI aggiunge il proprio percorso. /v1 va solo sull’api_base upstream nella configurazione del proxy.

Posso usare un proxy diverso da LiteLLM?

Sì. Qualsiasi proxy che converte le richieste Anthropic Messages in OpenAI Chat Completions funziona, ad esempio claude-code-router. Indirizza il suo upstream a https://api.claudecodeproxyapi.com/v1 con il modello uncensored.

La mia chiave upstream è sicura nella configurazione?

Tienila in una variabile d’ambiente invece che nel file, come mostrato nella configurazione sopra. Non committare la chiave in un repository.

La tua chiave è a un modulo di distanza

Crea un account, copia la chiave, modifica l'URL di base. È tutta la configurazione.