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 vedi | Causa | Soluzione |
|---|---|---|
| Connessione rifiutata | Il proxy non è in esecuzione o la porta è diversa | Avvialo e fai corrispondere la porta in ANTHROPIC_BASE_URL |
| Proxy 404 o "modello non trovato" | Il nome del modello inviato dalla CLI non è nella configurazione | Aggiungi quel nome a model_list |
| Upstream 401 | UPSTREAM_KEY errata o vuota | Riesporta la chiave nella shell del proxy e riavvia |
429 con concurrency | Più di 8 richieste parallele (2 nella prova) | Riduci gli agenti paralleli |
429 con rate_limited | Più di 300 richieste al minuto (60 in prova) | Riduci la frequenza e riprova |
429 con Retry-After: 5 | Sovraccarico temporaneo | Riprova dopo cinque secondi |
| Flusso bloccato | Una richiesta in streaming tiene il suo slot fino alla fine | Annullala 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.
