Configurare Claude Code

La CLI di Anthropic sull'endpoint di OneProvider. La configurazione richiede due variabili d'ambiente e una chiamata di verifica.

Installazione

curl -fsSL https://claude.ai/install.sh | bash
# or:
brew install --cask claude-code

Opzione 1: variabili d'ambiente (sessione corrente)

Il modo più rapido è impostare le variabili solo nel terminale corrente. Non restano tra una sessione e l'altra: se vuoi che sopravvivano a un riavvio, vedi «Rendi permanente» in fondo.

export ANTHROPIC_BASE_URL=https://api.oneprovider.dev
export ANTHROPIC_AUTH_TOKEN=sk-your-key-here

Opzione 2: impostazioni permanenti

Claude Code legge le impostazioni utente da settings.json. Il modello predefinito e gli alias delle famiglie qui sotto derivano dai modelli attivi del catalogo.

Percorso del file: ~/.claude/settings.json

{
"env": {
"ANTHROPIC_BASE_URL": "https://api.oneprovider.dev",
"ANTHROPIC_AUTH_TOKEN": "sk-your-key-here",
"ANTHROPIC_MODEL": "claude-sonnet-5-5",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5-5",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-5-5"
},
"model": "claude-sonnet-5-5"
}

Verifica

claude -p "say hi in one sentence"

Dovresti vedere una risposta di una sola frase entro un secondo o due. Se vedi 401, la chiave è sbagliata; 400 invalid_request_error significa che il nome del modello non corrisponde all'elenco canonico (la risposta elenca gli ID supportati).

Problemi comuni

# validate the file
jq . ~/.claude/settings.json
# auto-replace smart quotes with ASCII
sed -i.bak $'s/[\u201c\u201d]/"/g' ~/.claude/settings.json

L'elenco completo dei sintomi 400 / 401 / 403 / 404 / 429 / 503 / 504, con cause e soluzioni, è nella pagina Risoluzione dei problemi .

Uso degli strumenti

Claude Code usa lo schema degli strumenti nativo di Anthropic. L'API accetta ogni nome di strumento (Read, Write, Edit, Bash, Grep, Glob, TodoWrite, ecc.) con tool_choice: auto, che è ciò che la CLI emette di default. Non serve alcun header anthropic-beta.

Se il tuo orchestratore personalizzato imposta tool_choice: {"type": "any"} oppure tool_choice: {"type": "tool", "name": "X"}, l'API li riscrive in auto più un suggerimento nel prompt di sistema. Vedi Uso degli strumenti per la tabella completa.

Rendi permanente

Quando tutto funziona e vuoi che le variabili restino tra le sessioni del terminale, aggiungile al file rc della tua shell (macOS / Linux) o al registro dell'ambiente utente (Windows). I nuovi terminali le prenderanno in automatico.

# append to ~/.zshrc (default macOS shell)
cat >> ~/.zshrc <<'EOF'
export ANTHROPIC_BASE_URL=https://api.oneprovider.dev
export ANTHROPIC_AUTH_TOKEN=sk-your-key-here
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
EOF
# apply to the current session:
source ~/.zshrc

Quale modello scegliere

Claude Code parla il protocollo Anthropic, quindi funziona meglio con la famiglia Claude. Usa claude-sonnet-5-5 come scelta di tutti i giorni: prezzo e qualità bilanciati per modifiche, test e spiegazioni. Passa a claude-opus-5-5 per decisioni di architettura, grandi refactoring e bug che non riesci a individuare; costa di più per token. Usa claude-haiku-5-5 per domande rapide, messaggi di commit e lavori in background dove conta più la velocità che la profondità. Dentro una sessione esegui /model per cambiare, oppure parti con claude --model claude-opus-5-5. Le impostazioni qui sopra associano gli alias sonnet, opus e haiku a questi ID. Gli ID attuali sono nella pagina dei modelli e le tariffe nella pagina dei prezzi . I prezzi sono per milione di token, quindi imposta un limite di spesa sulla chiave e tieni d'occhio «Consumo» nella tua Dashboard.

Errori comuni e soluzioni

claude: command not found dopo l'installazione

Apri prima un nuovo terminale: il programma di installazione mette il binario in ~/.local/bin. Se manca ancora, aggiungilo con export PATH="$HOME/.local/bin:$PATH" nel file rc della tua shell. Con Homebrew, verifica che brew install --cask claude-code sia terminato senza errori.

400 invalid_request_error sul modello

L'ID del modello non è nel catalogo, spesso un vecchio alias come claude-3-5-sonnet. Imposta ANTHROPIC_MODEL e le tre variabili ANTHROPIC_DEFAULT_*_MODEL come nel settings.json qui sopra, oppure elenca gli ID validi con curl -s https://api.oneprovider.dev/v1/models -H "x-api-key: $KEY".

404 o «The requested API endpoint does not exist»

ANTHROPIC_BASE_URL deve essere esattamente https://api.oneprovider.dev: senza /v1 e senza /v1/messages in fondo. Il percorso lo aggiunge Claude Code.

429 «Insufficient balance on this API key»

Il saldo dell'area personale o il limite di spesa della chiave è esaurito. Riprovare non serve: ricarica il saldo o alza il limite nell'area personale, poi invia di nuovo la richiesta.

La risposta si interrompe a metà o la connessione si azzera

Disattiva qualsiasi VPN o proxy VLESS: mettono in buffer gli stream e rompono HTTP/2. OneProvider non ha restrizioni regionali e non mette in buffer gli stream. Una richiesta deve iniziare a rispondere entro 6 minuti ed è limitata a 10 minuti in totale, vedi codici di errore .

Ho modificato settings.json ma non è cambiato nulla

Claude Code legge il blocco env all'avvio: chiudi e riavvia claude. Tieni le variabili in ~/.claude/settings.json o nella tua shell: il .claude/settings.json di un progetto viene letto dopo la configurazione del primo avvio e può essere troppo tardi.

FAQ

Mi serve un account o un abbonamento Claude?

No. Basta la chiave di OneProvider. Claude Code non deve mai accedere a claude.ai; se mostra una schermata di accesso, segui i passaggi per Auth conflict qui sopra.

Posso usare GPT o altri modelli in Claude Code?

Claude Code invia richieste Anthropic Messages, quindi lì usa gli ID Claude. Per i modelli GPT usa Codex , Cursor o Cline .

Come torno al mio accesso Anthropic?

Elimina le variabili ANTHROPIC_* impostate qui sopra dal blocco env di settings.json e dal file rc della tua shell, apri un nuovo terminale ed esegui /login.

Dove vedo quanto è costata una sessione?

Nella pagina «Consumo» della Dashboard della chiave: ogni richiesta con il suo modello e il numero di token. Un limite di spesa per chiave ferma un agente fuori controllo.

Funziona su Windows?

Sì. Scegli Windows nel selettore del sistema operativo in alto: le stesse due variabili si impostano con PowerShell e settings.json si trova nel tuo profilo utente, sotto .claude.

L'estensione Claude Code per VS Code è la stessa cosa?

Condivide il file delle impostazioni. Vedi Claude Code in VS Code .

Risposte rapide

Quale base URL devo usare?

Claude Code e gli SDK Anthropic usano https://api.oneprovider.dev. Gli SDK OpenAI e i client compatibili con OpenAI usano https://api.oneprovider.dev/v1. Con una sola chiave funzionano entrambi; l'elenco dei modelli è nella pagina dei modelli , le tariffe nella pagina dei prezzi .

Come mi autentico?

Invia la chiave sk-… così com'è in x-api-key oppure in Authorization: Bearer: uno dei due, mai entrambi. Tieni la chiave in una variabile d'ambiente, non in un file che finisce nel commit. Altro sull'autenticazione .

Dove ottengo una chiave?

Apri la tua area personale nel bot Telegram @oneprovider_robot oppure su app.oneprovider.dev, ricarica il saldo e premi «Emetti una chiave». Ogni chiave può avere un proprio limite di spesa. Area personale e chiavi API .

Cosa significano 401, 404 e 429?

401: la chiave manca, è scritta male o è inviata nell'header sbagliato; incolla la chiave intera, senza virgolette né spazi. 404: di solito la base URL è sbagliata, per esempio manca /v1 o è doppio. 429 con “Insufficient balance”: il saldo dell'area personale o il limite di spesa della chiave è esaurito, quindi ricarica invece di riprovare; qualsiasi altro 429 è un limite di frequenza, quindi attendi il tempo indicato in Retry-After. Dettagli: codici di errore e risoluzione dei problemi .

Perché gli stream si interrompono o si resettano?

VPN e proxy VLESS spesso mettono in buffer gli SSE o rompono la negoziazione HTTP/2. OneProvider non ha restrizioni regionali e non mette in buffer gli stream: disattiva il proxy e riprova.

Dove chiedo se non basta?

Scrivi a @Oneproviderhelpbot su Telegram oppure apri «Assistenza» nell'area personale sul sito, indicando il codice di stato HTTP e il testo esatto dell'errore. Come funziona l'assistenza .