# Claude Code CLI — Configuration with OmniRoute (Italiano)

🌐 **Languages:** 🇺🇸 [English](../../../../guides/CLAUDE-CODE-CONFIGURATION.md) · 🇪🇹 [am](../../../am/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇸🇦 [ar](../../../ar/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇦🇿 [az](../../../az/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇧🇬 [bg](../../../bg/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇧🇩 [bn](../../../bn/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇧🇦 [bs](../../../bs/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇨🇿 [cs](../../../cs/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇩🇰 [da](../../../da/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇩🇪 [de](../../../de/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇬🇷 [el](../../../el/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇪🇸 [es](../../../es/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇪🇪 [et](../../../et/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇷 [fa](../../../fa/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇫🇮 [fi](../../../fi/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇫🇷 [fr](../../../fr/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇪 [ga](../../../ga/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [gu](../../../gu/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇳🇬 [ha](../../../ha/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇱 [he](../../../he/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [hi](../../../hi/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇭🇷 [hr](../../../hr/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇭🇺 [hu](../../../hu/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇦🇲 [hy](../../../hy/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇩 [id](../../../id/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇳🇬 [ig](../../../ig/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇯🇵 [ja](../../../ja/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇬🇪 [ka](../../../ka/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇰🇭 [km](../../../km/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [kn](../../../kn/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇰🇷 [ko](../../../ko/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇱🇹 [lt](../../../lt/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇱🇻 [lv](../../../lv/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [ml](../../../ml/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [mr](../../../mr/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇲🇾 [ms](../../../ms/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇲🇹 [mt](../../../mt/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇲🇲 [my](../../../my/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇳🇵 [ne](../../../ne/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇳🇱 [nl](../../../nl/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇳🇴 [no](../../../no/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [or](../../../or/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [pa](../../../pa/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇵🇭 [phi](../../../phi/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇵🇱 [pl](../../../pl/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇵🇹 [pt](../../../pt/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇷🇴 [ro](../../../ro/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇷🇺 [ru](../../../ru/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇱🇰 [si](../../../si/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇸🇰 [sk](../../../sk/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇸🇮 [sl](../../../sl/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇷🇸 [sr](../../../sr/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇸🇪 [sv](../../../sv/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇰🇪 [sw](../../../sw/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [ta](../../../ta/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇮🇳 [te](../../../te/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇹🇭 [th](../../../th/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇹🇷 [tr](../../../tr/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇵🇰 [ur](../../../ur/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇺🇿 [uz](../../../uz/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇻🇳 [vi](../../../vi/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇳🇬 [yo](../../../yo/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/CLAUDE-CODE-CONFIGURATION.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/CLAUDE-CODE-CONFIGURATION.md)

---

Indirizza la CLI di **Claude Code** (`claude`) verso OmniRoute — in locale o su un VPS remoto —
con profili specifici per modello, replicando la configurazione di Codex.

---

## Avvio rapido

```bash
# Avvia Claude Code con un'istanza OmniRoute locale (rileva automaticamente il contesto attivo)
omniroute launch

# Con un'istanza OmniRoute remota (dopo `omniroute connect <host>`, avviene automaticamente)
omniroute launch --remote http://192.168.0.15:20128 --api-key oma_live_xxx

# Genera profili specifici per modello, quindi avviane uno
omniroute setup-claude            # scrive ~/.claude/profiles/<name>/settings.json
omniroute launch --profile glm52  # Claude Code usa glm/glm-5.2 tramite OmniRoute
```

---

## Come Claude Code si connette a un gateway

Claude Code comunica tramite l'**API Anthropic Messages** e viene indirizzato a un endpoint
personalizzato mediante variabili d'ambiente (non dispone di un flag `--base-url`):

| Variabile                                    | Scopo                                                                                             |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `ANTHROPIC_BASE_URL`                         | URL radice del gateway (Claude Code aggiunge `/v1/messages`). **Senza suffisso `/v1`.**           |
| `ANTHROPIC_AUTH_TOKEN`                       | Inviato come `Authorization: Bearer …` — usa il token di accesso / la chiave API di OmniRoute     |
| `ANTHROPIC_API_KEY`                          | Alternativa: inviato come `x-api-key`. Se sono impostati entrambi, prevale `ANTHROPIC_AUTH_TOKEN` |
| `ANTHROPIC_MODEL`                            | Forza un modello specifico (sovrascrive il valore predefinito del selettore `/model`)             |
| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | `1` → il selettore nativo `/model` elenca i modelli `claude*`/`anthropic*` da `/v1/models`        |
| `CLAUDE_CODE_MAX_OUTPUT_TOKENS`              | Limita i token di output per risposta (ad es. `65536`)                                            |
| `CLAUDE_CODE_AUTO_COMPACT_WINDOW`            | Soglia di token per la compattazione automatica                                                   |

> Le variabili d'ambiente vengono lette **una sola volta all'avvio** — riavvia Claude Code dopo averle modificate.

`omniroute launch` le imposta tutte automaticamente: determina l'URL di base e il token
dal contesto attivo (quindi, dopo `omniroute connect <vps>`, `omniroute launch`
funziona immediatamente), verifica lo stato del server ed esegue `claude`.

---

## Alias di discovery — mostrare i modelli non-Claude nel selettore `/model`

Il gateway model discovery di Claude Code elenca solo gli id che iniziano con `claude`
o `anthropic`, quindi con `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` il selettore
nativo `/model` mostra normalmente **solo** i modelli Claude/Anthropic di OmniRoute — un
`kimi/kimi-k2.6` o un `glm/glm-5.2` non appare mai, anche se il routing funziona correttamente.

OmniRoute può creare un mirror di qualsiasi modello abilitato (e combo) sotto un id
`claude/…` in modo che superi quel filtro e appaia nel selettore:

```
kimi/kimi-k2.6            →  claude/kimi/kimi-k2.6      "Kimi K2.6 (OmniRoute)"
glm/glm-5.2              →  claude/glm/glm-5.2         "GLM 5.2 (OmniRoute)"
<combo "custo-otimizado"> →  claude/combo/custo-otimizado
```

Quando selezioni uno di questi in Claude Code, OmniRoute rimuove il wrapper `claude/`
ripristinando l'id reale prima del routing — un autentico id `claude/<real-claude-model>`
(il vero provider Claude OAuth) viene sempre lasciato invariato.

Per impostazione predefinita vengono sottoposti a mirror solo gli id base. Con il feature
flag opzionale `CATALOG_MIRROR_REFINEMENTS_ENABLED` attivo, anche le varianti
reasoning-effort già elencate nel catalogo (ad es. `codex/gpt-6-sol-high`) vengono
sottoposte a mirror come qualsiasi altro id, così Claude Code può selezionare un livello
di effort esplicito, mentre gli id integrati `auto/*` che il percorso di richiesta non può
materializzare non vengono sottoposti a mirror. La presenza o meno delle varianti di effort
nell'elenco resta comunque governata da `OMNIROUTE_DISABLE_THINKING_LEVEL_VARIANTS` — il
mirror non aggiunge mai una variante assente dal catalogo base.

**Questa funzione è disattivata per impostazione predefinita** ed è controllata da un gate
a tre livelli (vince il più specifico), così un OmniRoute standard non raddoppia mai il
proprio catalogo per i client che non usano Claude Code:

| Livello  | Dove                                                                                                   |
| -------- | ------------------------------------------------------------------------------------------------------ |
| Modello  | Pagina di dettaglio del provider → toggle "Esponi in Claude Code" per singolo modello                  |
| Provider | Pagina di dettaglio del provider → toggle a livello di provider (copre tutti i suoi modelli)           |
| Globale  | Impostazioni → Feature Flag → `EXPOSE_CC_DISCOVERY_ALIASES` (disattivato per impostazione predefinita) |

La variabile d'ambiente `EXPOSE_CC_DISCOVERY_ALIASES` forza l'attivazione del livello
globale e ha la precedenza sull'override della dashboard (la schermata Feature Flag mostra
una nota "attivo tramite variabile d'ambiente" in tal caso). I toggle per provider e per
modello permettono di affinare la configurazione a partire da lì — ad es. globale
disattivato + provider Kimi attivato espone solo i modelli di Kimi.

> ⚠️ **Disallineamento della finestra sui modelli non-Claude.** Claude Code presume una
> finestra di contesto di 200K per qualsiasi id che non riconosce (non può leggere una
> finestra reale da `/v1/models`). Per un modello con una finestra più grande (ad es. i
> 256K di Kimi K2), imposta `CLAUDE_CODE_AUTO_COMPACT_WINDOW` su un valore inferiore alla
> finestra reale del modello, in modo che l'auto-compattazione non scatti prematuramente.
> I profili generati sopra lo fanno già per ogni modello.

---

## Blocco di onboarding nella dashboard

La scheda dello strumento Claude (**Dashboard → CLI Code**) visualizza il frammento esatto di `settings.json`
per questa istanza, accanto al pulsante informativo sull'alias di rilevamento, con un pulsante per copiarlo:

```jsonc
{
  "env": {
    "ANTHROPIC_BASE_URL": "http://<il tuo OmniRoute>:20128",
    "ANTHROPIC_AUTH_TOKEN": "<la tua chiave API OmniRoute>",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1",
  },
}
```

L'URL di base è quello risolto dalla scheda (inclusa un'eventuale sostituzione personalizzata inserita), già
normalizzato, senza suffisso `/v1` né barra finale. **La chiave non viene mai visualizzata**: il blocco include un
segnaposto, in modo che uno screenshot o un frammento incollato non possano divulgarla. Sostituisci il segnaposto con la tua chiave.

Aggiungi `CLAUDE_CODE_AUTO_COMPACT_WINDOW` nello stesso blocco `env` per qualsiasi modello la cui finestra di
contesto effettiva non sia 200K: Claude Code presume 200K per ogni id che non riconosce, quindi, in caso contrario,
la compattazione automatica viene attivata nel momento sbagliato (consulta l'avviso nella sezione precedente).
Il generatore di frammenti accetta anche questo valore, quindi un chiamante che conosce la finestra del modello
di destinazione può includerlo direttamente.

Fonte: `src/shared/services/claudeCliConfig.ts::buildClaudeDiscoverySettingsSnippet` (generatore
puro, sottoposto a test unitari) visualizzato da `ClaudeGatewayOnboardingBlock`.

### Fissare un account (facoltativo)

Per inviare ogni richiesta di Claude Code tramite uno specifico account del provider, aggiungi l'header
`x-omniroute-connection` tramite `ANTHROPIC_CUSTOM_HEADERS` nello stesso blocco `env`:

```jsonc
"ANTHROPIC_CUSTOM_HEADERS": "x-omniroute-connection: <connection id>"
```

Copia l'id dal chip `xxxxxxxx…` nella riga della connessione della pagina del provider. Il vincolo si
applica solo agli id di modelli singoli (`provider/model`), non alle combinazioni. Consulta
[Associazione dell'account per singola richiesta](../reference/API_REFERENCE.md#account-pinning-per-request) per il
comportamento esatto del fallback.

---

## Profili (`CLAUDE_CONFIG_DIR`)

Claude Code **non dispone di file di profilo nativi** (a differenza di `~/.codex/<name>.config.toml` di Codex).
Il meccanismo idiomatico è `CLAUDE_CONFIG_DIR`: una directory di configurazione separata per
ogni profilo, ciascuna con i propri `settings.json`, credenziali, cronologia e cache.

`omniroute setup-claude` recupera il catalogo `/v1/models` attivo e scrive un
profilo per ogni modello in `~/.claude/profiles/<name>/settings.json`, riutilizzando
**gli stessi nomi di `setup-codex`** (`glm52`, `kimi-k27`, `deepseek-pro`, …):

```jsonc
// ~/.claude/profiles/glm52/settings.json
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "glm/glm-5.2",
  "effortLevel": "xhigh",
  "env": {
    "ANTHROPIC_BASE_URL": "http://192.168.0.15:20128",
    "ANTHROPIC_MODEL": "glm/glm-5.2",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1",
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "190000",
  },
}
```

> **Il token di autenticazione non viene mai scritto nel profilo.** Avvia con
> `omniroute launch --profile <name>` (inietta `ANTHROPIC_AUTH_TOKEN` dal
> contesto attivo), oppure esporta autonomamente `ANTHROPIC_AUTH_TOKEN` ed esegui
> `CLAUDE_CONFIG_DIR=~/.claude/profiles/<name> claude`.

**Sincronizzazione automatica dopo il rilevamento dei modelli (facoltativa).** OmniRoute può rigenerare automaticamente gli stessi
file `~/.claude/profiles/<name>/settings.json` ogni volta che la sincronizzazione dei modelli di un provider
modifica il catalogo attivo, in modo che i modelli nuovi o rinominati ottengano profili senza dover rieseguire il
comando. È **disattivata per impostazione predefinita**: attivala dalla **dashboard CLI Code** ("Sincronizzazione
automatica dei profili CLI" → Claude Code), oppure imposta `OMNIROUTE_AUTO_SYNC_CLAUDE_PROFILES=true` (rispetta anche
`CLI_ALLOW_CONFIG_WRITES`, attivo per impostazione predefinita). Quando è abilitata, scrive soltanto i file di profilo; non
modifica mai la configurazione Claude attiva/predefinita, l'autenticazione o `~/.claude/settings.json`.

### Generazione e utilizzo dei profili

```bash
# OmniRoute locale
omniroute setup-claude

# VPS remoto (incorpora l'URL del VPS in ogni profilo)
omniroute setup-claude --remote http://192.168.0.15:20128 --api-key oma_live_xxx

# Solo alcuni provider
omniroute setup-claude --only glm,kimi

# Scrive anche i profili per i provider CLI locali (zcode, auggie, devin-cli-agentic,
# codex-app-server) non rilevati su questo host (ignorati per impostazione predefinita per una destinazione locale)
omniroute setup-claude --include-local

# Anteprima senza scrivere
omniroute setup-claude --dry-run

# Avvia un profilo
omniroute launch --profile kimi-k27
```

---

## Livelli dei modelli (facoltativo)

Claude Code instrada le richieste verso livelli di capacità. Associa ciascun livello a un modello OmniRoute tramite variabili di ambiente /
impostazioni se desideri utilizzare provider diversi per ciascun livello:

```bash
export ANTHROPIC_DEFAULT_OPUS_MODEL="glm/glm-5.2"
export ANTHROPIC_DEFAULT_SONNET_MODEL="kmc/kimi-k2.6"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="glm/glm-4.7-flash"
```

In caso contrario, viene utilizzato un singolo `ANTHROPIC_MODEL` (quello impostato dai profili) per tutto.

---

## Modalità remota

Dopo aver eseguito `omniroute connect <host>` (vedi
[Modalità remota](./REMOTE-MODE.md)), `omniroute launch` e `omniroute setup-claude`
utilizzano automaticamente quel server remoto e il relativo token di accesso con ambito limitato, senza
richiedere flag aggiuntivi. Puoi sovrascrivere questa configurazione per una singola esecuzione con `--remote` / `--api-key`.

---

## Risoluzione dei problemi

**Claude Code ignora il gateway** — verifica che `ANTHROPIC_BASE_URL` **non
contenga `/v1`** e riavvia `claude` (le variabili di ambiente vengono lette una sola volta all'avvio). `omniroute launch`
gestisce automaticamente questo aspetto.

**Il selettore `/model` è vuoto / non mostra i modelli del gateway** — sono necessari Claude Code
v2.1.219+ e `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1`. Nel selettore vengono visualizzati solo gli ID modello `claude*` /
`anthropic*`; per forzare qualsiasi altro modello, utilizza
`ANTHROPIC_MODEL=<id>` (è ciò che fanno i profili).

**`400 Ambiguous model 'claude-…'`** — Claude Code invia sempre ID modello **senza prefisso**
(ad esempio `claude-opus-4-8`), quindi, quando sono connessi sia i provider Claude Code (`cc/…`) sia
Claude (`claude/…`), l'ID senza prefisso corrisponde a due route e
OmniRoute si rifiuta di fare una scelta arbitraria. Puoi risolvere in uno dei due modi: imposta un ID con prefisso tramite
`ANTHROPIC_MODEL=cc/claude-opus-4-8`, oppure abilita **Preferisci Claude Code per i
modelli Claude senza prefisso** — l'opzione nella pagina del provider Claude, oppure
`OMNIROUTE_PREFER_CLAUDE_CODE_FOR_UNPREFIXED_CLAUDE_MODELS=true` (disattivata per impostazione predefinita;
vedi [Ambiente](../reference/ENVIRONMENT.md)) — che instrada invece gli ID `claude-*`
senza prefisso verso Claude Code. I prefissi espliciti dei provider hanno sempre la precedenza.

**Errori di autenticazione** — il profilo non contiene alcun token. Utilizza `omniroute launch --profile`
(che lo inserisce) oppure esporta `ANTHROPIC_AUTH_TOKEN`.

**I profili non sono isolati** — ogni profilo utilizza una directory `CLAUDE_CONFIG_DIR` distinta;
verifica che `echo $CLAUDE_CONFIG_DIR` all'interno della sessione punti a
`~/.claude/profiles/<name>`.