> ## Documentation Index
> Fetch the complete documentation index at: https://veniceai-mintlify-de47a659.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code

> Instrada le richieste della CLI Claude Code su Venice con claude-code-router per accesso pay-per-token ai modelli di coding Claude Opus, Sonnet e Fable.

[Claude Code](https://code.claude.com/docs) è lo strumento CLI di Anthropic per il coding agentico. Questa guida ti mostra come eseguirlo tramite Venice per l'accesso anonimizzato e pay-per-token ai modelli Claude.

<CardGroup cols={3}>
  <Card title="Paga per token" icon="coins">
    Nessun abbonamento. Paghi solo per ciò che usi
  </Card>

  <Card title="Modelli Claude" icon="cpu">
    Accedi ai modelli Opus, Sonnet e Fable attuali tramite Venice
  </Card>

  <Card title="Prompt caching" icon="bolt">
    Il caching di Venice funziona insieme a Claude Code
  </Card>
</CardGroup>

## Perché serve un router

Claude Code si connette direttamente all'API di Anthropic per impostazione predefinita. Per usarlo con Venice, hai bisogno di [claude-code-router](https://github.com/musistudio/claude-code-router), un proxy locale open source che:

<Steps>
  <Step title="Intercetta" icon="hand-stop">
    Cattura le richieste in uscita di Claude Code prima che raggiungano Anthropic
  </Step>

  <Step title="Trasforma" icon="refresh">
    Converte le richieste Anthropic Messages nel formato chat OpenAI-compatibile di Venice
  </Step>

  <Step title="Reindirizza" icon="route">
    Inoltra le richieste a `api.venice.ai/api/v1/chat/completions`
  </Step>
</Steps>

***

## Prerequisiti

<CardGroup cols={3}>
  <Card title="Account Venice" icon="user" href="https://venice.ai/settings/api?utm_source=venice-api-documentation">
    Con crediti Venice
  </Card>

  <Card title="Node.js" icon="brand-nodejs" href="https://nodejs.org/">
    v22 o superiore
  </Card>

  <Card title="Claude Code" icon="terminal" href="https://code.claude.com/docs">
    Installato via npm
  </Card>
</CardGroup>

***

## Configurazione

<Steps>
  <Step title="Installa o aggiorna Claude Code">
    Installa l'ultima versione della CLI Claude Code:

    ```bash theme={null}
    npm install -g @anthropic-ai/claude-code@latest
    claude --version
    ```
  </Step>

  <Step title="Installa Claude Code Router">
    ```bash theme={null}
    npm install -g @musistudio/claude-code-router@latest
    npm list -g @musistudio/claude-code-router --depth=0
    ```
  </Step>

  <Step title="Ottieni la tua API key">
    Genera una chiave da [venice.ai/settings/api](https://venice.ai/settings/api?utm_source=venice-api-documentation). La aggiungerai a CCR nel prossimo passaggio.
  </Step>

  <Step title="Aggiungi Venice come provider">
    Avvia l'interfaccia di gestione di CCR:

    ```bash theme={null}
    ccr ui
    ```

    Nella pagina **Providers**, scegli **Add provider** e poi **Other / custom API endpoint**. Inserisci:

    * **Nome:** `Venice`
    * **Endpoint API:** `https://api.venice.ai/api/v1`
    * **API key:** la tua API key Venice

    CCR dovrebbe rilevare automaticamente **OpenAI Chat**. In caso contrario, apri **Advanced settings**, disattiva il rilevamento automatico del protocollo e seleziona **OpenAI Chat**.

    Usa **Search models** o **Custom models** per aggiungere i modelli Claude che desideri, quindi esegui **Check Connection** e salva il provider. La verifica della connessione invia una richiesta reale con un limite di output di un token.
  </Step>

  <Step title="Crea un profilo Claude Code">
    In **Agent Config**, scegli **Add profile** e poi **Claude Code**:

    * Assegna al profilo il nome `Claude Code - Venice`.
    * Mantieni **Effect scope** impostato su **Only opened from CCR** durante i test.
    * Scegli **CLI only** o **CLI & APP**.
    * Imposta **Model** su un modello Venice come `Venice/claude-opus-4-8`.
    * Per mantenere ogni livello di Claude Code su Venice, imposta anche i campi opzionali dei modelli Fable, Opus, Sonnet e Haiku su modelli Venice.

    Salva il profilo.
  </Step>

  <Step title="Avvia e verifica">
    Avvia il profilo per nome:

    ```bash theme={null}
    ccr "Claude Code - Venice"
    ```

    In Claude Code:

    1. Esegui `/context` e conferma che la finestra di contesto corrisponda al modello selezionato. Per `claude-opus-4-8`, dovrebbe mostrare `1M`.
    2. Esegui `/model` se vuoi passare a un altro modello Venice; le varianti 1M sono contrassegnate con **1M context**.
    3. Invia un messaggio di prova, poi controlla i **Request logs** in CCR per confermare che sia stato usato Venice.
  </Step>
</Steps>

***

## Modelli supportati

| Modello              | ID Venice              | Contesto |
| -------------------- | ---------------------- | -------- |
| Claude Fable 5.1     | `claude-fable-5-1`     | 1M       |
| Claude Fable 5       | `claude-fable-5`       | 1M       |
| Claude Opus 5        | `claude-opus-5`        | 1M       |
| Claude Opus 5 Fast   | `claude-opus-5-fast`   | 1M       |
| Claude Opus 4.8      | `claude-opus-4-8`      | 1M       |
| Claude Opus 4.8 Fast | `claude-opus-4-8-fast` | 1M       |
| Claude Opus 4.7      | `claude-opus-4-7`      | 1M       |
| Claude Opus 4.6      | `claude-opus-4-6`      | 1M       |
| Claude Opus 4.5      | `claude-opus-4-5`      | 198K     |
| Claude Sonnet 5      | `claude-sonnet-5`      | 1M       |
| Claude Sonnet 4.6    | `claude-sonnet-4-6`    | 1M       |
| Claude Sonnet 4.5    | `claude-sonnet-4-5`    | 198K     |

Il catalogo cambia nel tempo. Usa **Search models** in CCR o [`GET /models?type=text`](/api-reference/endpoint/models/list) per l'elenco e i limiti aggiornati.

<Info>
  Claude Code è ottimizzato per i modelli Claude. Sebbene altri modelli disponibili tramite Venice (GPT, DeepSeek, Grok, ecc.) possano funzionare, non possiamo garantire un'esperienza equivalente poiché Claude Code si basa su funzionalità specifiche di Claude come l'extended thinking. Per altri modelli, considera l'uso dell'[API standard di Venice](/api-reference/endpoint/chat/completions).
</Info>

***

## Aggiornare un'installazione esistente

Aggiorna CCR prima di risolvere i problemi di un'installazione esistente:

```bash theme={null}
npm install -g @musistudio/claude-code-router@latest
npm list -g @musistudio/claude-code-router --depth=0
ccr ui
```

Le versioni attuali di CCR memorizzano la configurazione attiva in `~/.claude-code-router/config.sqlite`. Un vecchio `config.json` viene importato quando il database non esiste. Dopo la migrazione, apporta le modifiche tramite `ccr ui` invece di continuare a modificare `config.json`.

Se un processo in background è ancora in esecuzione dopo un aggiornamento, riavvialo:

```bash theme={null}
ccr stop
ccr start
```

***

## Prompt caching

Il [prompt caching](/guides/features/prompt-caching) di Venice funziona con i marker di cache nativi di Claude Code. Nessun transformer di cache aggiuntivo è necessario per la configurazione normale.

***

## Risoluzione dei problemi

<AccordionGroup>
  <Accordion title="Il contesto raggiunge il 100% in anticipo o la compattazione fallisce">
    1. Aggiorna CCR con `npm install -g @musistudio/claude-code-router@latest`.
    2. Avvia una nuova sessione di Claude Code dal profilo CCR.
    3. Esegui `/model` e seleziona la voce Venice contrassegnata con **1M context**.
    4. Esegui `/context` e conferma che la finestra sia `1M`, non `200K`.

    Le versioni più vecchie di CCR potrebbero non esporre a Claude Code la finestra di contesto o l'utilizzo dei token corretti.
  </Accordion>

  <Accordion title="CCR si arresta in modo anomalo durante l'avvio">
    Conferma Node.js 22 o più recente e aggiorna CCR:

    ```bash theme={null}
    node --version
    npm list -g @musistudio/claude-code-router --depth=0
    ```

    Usa `ccr serve` per l'esecuzione in primo piano ed esporre l'errore di avvio originale. Uno stack `Cannot read properties of undefined (reading 'error')` proveniente da `server.logger.error` indica un'installazione di CCR obsoleta; aggiornala prima di indagare oltre.
  </Accordion>

  <Accordion title="Claude Code segnala ConnectionRefused">
    Avvia il gateway e verificane lo stato di salute:

    ```bash theme={null}
    ccr start
    curl http://127.0.0.1:3456/health
    ```

    Un controllo di salute fallito significa che il gateway locale di CCR non è disponibile; la richiesta non ha raggiunto Venice.
  </Accordion>

  <Accordion title="Le modifiche alla configurazione vengono ignorate">
    Apri `ccr ui` ed effettua lì la modifica. Le versioni attuali di CCR memorizzano la configurazione in `config.sqlite`; `config.json` è solo una fonte di migrazione per le installazioni più vecchie.
  </Accordion>
</AccordionGroup>

***

## Risorse

<CardGroup cols={3}>
  <Card title="Documentazione API Venice" icon="book" href="/api-reference/api-spec">
    Riferimento completo dell'API
  </Card>

  <Card title="claude-code-router" icon="brand-github" href="https://github.com/musistudio/claude-code-router">
    Codice sorgente e issue
  </Card>

  <Card title="Release di CCR" icon="history" href="https://github.com/musistudio/claude-code-router/releases">
    Versioni attuali e note di rilascio
  </Card>
</CardGroup>