# CLI Tools — OmniRoute (Italiano) 🌐 **Languages:** 🇺🇸 [English](../../../../reference/CLI-TOOLS.md) · 🇪🇹 [am](../../../am/docs/reference/CLI-TOOLS.md) · 🇸🇦 [ar](../../../ar/docs/reference/CLI-TOOLS.md) · 🇦🇿 [az](../../../az/docs/reference/CLI-TOOLS.md) · 🇧🇬 [bg](../../../bg/docs/reference/CLI-TOOLS.md) · 🇧🇩 [bn](../../../bn/docs/reference/CLI-TOOLS.md) · 🇧🇦 [bs](../../../bs/docs/reference/CLI-TOOLS.md) · 🇨🇿 [cs](../../../cs/docs/reference/CLI-TOOLS.md) · 🇩🇰 [da](../../../da/docs/reference/CLI-TOOLS.md) · 🇩🇪 [de](../../../de/docs/reference/CLI-TOOLS.md) · 🇬🇷 [el](../../../el/docs/reference/CLI-TOOLS.md) · 🇪🇸 [es](../../../es/docs/reference/CLI-TOOLS.md) · 🇪🇪 [et](../../../et/docs/reference/CLI-TOOLS.md) · 🇮🇷 [fa](../../../fa/docs/reference/CLI-TOOLS.md) · 🇫🇮 [fi](../../../fi/docs/reference/CLI-TOOLS.md) · 🇫🇷 [fr](../../../fr/docs/reference/CLI-TOOLS.md) · 🇮🇪 [ga](../../../ga/docs/reference/CLI-TOOLS.md) · 🇮🇳 [gu](../../../gu/docs/reference/CLI-TOOLS.md) · 🇳🇬 [ha](../../../ha/docs/reference/CLI-TOOLS.md) · 🇮🇱 [he](../../../he/docs/reference/CLI-TOOLS.md) · 🇮🇳 [hi](../../../hi/docs/reference/CLI-TOOLS.md) · 🇭🇷 [hr](../../../hr/docs/reference/CLI-TOOLS.md) · 🇭🇺 [hu](../../../hu/docs/reference/CLI-TOOLS.md) · 🇦🇲 [hy](../../../hy/docs/reference/CLI-TOOLS.md) · 🇮🇩 [id](../../../id/docs/reference/CLI-TOOLS.md) · 🇳🇬 [ig](../../../ig/docs/reference/CLI-TOOLS.md) · 🇯🇵 [ja](../../../ja/docs/reference/CLI-TOOLS.md) · 🇬🇪 [ka](../../../ka/docs/reference/CLI-TOOLS.md) · 🇰🇭 [km](../../../km/docs/reference/CLI-TOOLS.md) · 🇮🇳 [kn](../../../kn/docs/reference/CLI-TOOLS.md) · 🇰🇷 [ko](../../../ko/docs/reference/CLI-TOOLS.md) · 🇱🇹 [lt](../../../lt/docs/reference/CLI-TOOLS.md) · 🇱🇻 [lv](../../../lv/docs/reference/CLI-TOOLS.md) · 🇮🇳 [ml](../../../ml/docs/reference/CLI-TOOLS.md) · 🇮🇳 [mr](../../../mr/docs/reference/CLI-TOOLS.md) · 🇲🇾 [ms](../../../ms/docs/reference/CLI-TOOLS.md) · 🇲🇹 [mt](../../../mt/docs/reference/CLI-TOOLS.md) · 🇲🇲 [my](../../../my/docs/reference/CLI-TOOLS.md) · 🇳🇵 [ne](../../../ne/docs/reference/CLI-TOOLS.md) · 🇳🇱 [nl](../../../nl/docs/reference/CLI-TOOLS.md) · 🇳🇴 [no](../../../no/docs/reference/CLI-TOOLS.md) · 🇮🇳 [or](../../../or/docs/reference/CLI-TOOLS.md) · 🇮🇳 [pa](../../../pa/docs/reference/CLI-TOOLS.md) · 🇵🇭 [phi](../../../phi/docs/reference/CLI-TOOLS.md) · 🇵🇱 [pl](../../../pl/docs/reference/CLI-TOOLS.md) · 🇵🇹 [pt](../../../pt/docs/reference/CLI-TOOLS.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/reference/CLI-TOOLS.md) · 🇷🇴 [ro](../../../ro/docs/reference/CLI-TOOLS.md) · 🇷🇺 [ru](../../../ru/docs/reference/CLI-TOOLS.md) · 🇱🇰 [si](../../../si/docs/reference/CLI-TOOLS.md) · 🇸🇰 [sk](../../../sk/docs/reference/CLI-TOOLS.md) · 🇸🇮 [sl](../../../sl/docs/reference/CLI-TOOLS.md) · 🇷🇸 [sr](../../../sr/docs/reference/CLI-TOOLS.md) · 🇸🇪 [sv](../../../sv/docs/reference/CLI-TOOLS.md) · 🇰🇪 [sw](../../../sw/docs/reference/CLI-TOOLS.md) · 🇮🇳 [ta](../../../ta/docs/reference/CLI-TOOLS.md) · 🇮🇳 [te](../../../te/docs/reference/CLI-TOOLS.md) · 🇹🇭 [th](../../../th/docs/reference/CLI-TOOLS.md) · 🇹🇷 [tr](../../../tr/docs/reference/CLI-TOOLS.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/reference/CLI-TOOLS.md) · 🇵🇰 [ur](../../../ur/docs/reference/CLI-TOOLS.md) · 🇺🇿 [uz](../../../uz/docs/reference/CLI-TOOLS.md) · 🇻🇳 [vi](../../../vi/docs/reference/CLI-TOOLS.md) · 🇳🇬 [yo](../../../yo/docs/reference/CLI-TOOLS.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/reference/CLI-TOOLS.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/reference/CLI-TOOLS.md) --- Ultimo aggiornamento: 2026-08-23 OmniRoute si integra con tre categorie di strumenti CLI distribuite su tre pagine dedicate della dashboard: | Pagina | Route | Concetto | Numero | | -------------- | ----------------------- | ----------------------------------------------------------------------------------------- | ------------- | | **CLI Code's** | `/dashboard/cli-code` | Strumenti di programmazione indirizzati a OmniRoute (Client → CLI → OmniRoute → Provider) | 26 | | **CLI Agents** | `/dashboard/cli-agents` | Agenti autonomi indirizzati a OmniRoute (stesso flusso, ambito più ampio) | 10 | | **ACP Agents** | `/dashboard/acp-agents` | CLI che OmniRoute avvia come backend tramite stdio/ACP (flusso inverso) | vedi registro | Le route legacy vengono reindirizzate tramite 308: `/dashboard/cli-tools` → `/dashboard/cli-code`, `/dashboard/agents` → `/dashboard/acp-agents`. --- ## Come funziona ``` CLI Code's / CLI Agents (flusso di utilizzo): Claude / Codex / OpenCode / Cline / KiloCode / Continue / Hermes Agent / Goose / ... │ ▼ (tutti puntano a OmniRoute) http://YOUR_SERVER:20128/v1 │ ▼ (OmniRoute instrada verso il provider corretto) Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ... ACP Agents (flusso inverso di avvio): Richiesta del client → OmniRoute → avvia la CLI tramite stdio/ACP → risposta ``` **Vantaggi:** - Un'unica chiave API per gestire tutti gli strumenti - Monitoraggio dei costi di tutte le CLI nella dashboard - Cambio di modello senza dover riconfigurare ogni strumento - Funziona in locale e su server remoti (VPS, Docker, Akamai, Cloudflare Tunnel) --- ## Configurazione automatica con `setup-*` Non è necessario scrivere manualmente la configurazione di ogni strumento. OmniRoute fornisce un comando `setup-*` per ogni CLI supportata, che legge il catalogo dei modelli **attivo** da un'istanza OmniRoute in esecuzione (locale o remota) e scrive sul computer la configurazione specifica dello strumento: ```bash omniroute setup-codex omniroute setup-claude omniroute setup-opencode omniroute setup-cline omniroute setup-kilo omniroute setup-continue omniroute setup-cursor omniroute setup-roo omniroute setup-crush omniroute setup-goose omniroute setup-qwen omniroute setup-aider omniroute setup-5dive omniroute setup-zed ``` Ognuno accetta `--remote --api-key ` (per configurare uno strumento locale affinché utilizzi un'istanza OmniRoute remota), `--dry-run` (per visualizzare un'anteprima senza scrivere) e `--port`. Gli strumenti senza rilevamento automatico dei modelli (Cline, Kilo, Roo, Goose, Aider, Qwen, 5dive) accettano `--model ` (e `--yes` per le esecuzioni non interattive). `setup-5dive` è l'unica procedura che non scrive in `$HOME`: configura un parco di agenti 5dive scrivendo un profilo di autenticazione di proprietà di root sull'host del parco, quindi viene rieseguito tramite `sudo` e non dispone di una propria modalità remota. Per avviare una CLI con le variabili d'ambiente corrette già inserite e senza scrivere alcuna configurazione, utilizza il launcher generico `omniroute run ` (claude, codex, aider, goose, opencode, qwen, gemini — i target e gli alias provengono da `bin/cli/cli-manifest.mjs`); i launcher precedenti specifici per strumento `omniroute launch` (Claude Code) e `omniroute launch-codex` (Codex) rimangono disponibili. Gemini CLI può essere soltanto avviata: è un target di `omniroute run` ma non dispone di alcuna procedura `setup-*`/`configure`. > **Riferimento completo:** la tabella principale — cosa scrive ogni comando, tutti i flag, > modalità locale e remota e quali strumenti richiedono il suffisso `/v1` — è disponibile in > **[Integrazioni CLI](../guides/CLI-INTEGRATIONS.md)**. ### Esecuzione di questi comandi all'interno di un container Un comando `setup-*` eseguito all'interno del container OmniRoute scrive nella home del container stesso, che non viene letta da alcuna CLI dell'host e scompare insieme al container. OmniRoute rileva questa situazione e termina con il codice `2`, mostrando le istruzioni anziché scrivere. Esistono due soluzioni supportate: installare la CLI sull'host e usare `omniroute connect` per connettersi al container, oppure montare tramite bind le directory di configurazione e impostare `CLI_CONFIG_HOME` (il profilo compose `host`). Ogni comando `setup-*`, insieme a `omniroute configure` e `omniroute config set`, accetta `--allow-container-write` quando si intende effettivamente configurare le CLI del container; `OMNIROUTE_ALLOW_CONTAINER_CONFIG_WRITE=true` produce lo stesso risultato per il server. Consulta la [Guida Docker → Configurazione degli strumenti CLI dell'host](../guides/DOCKER_GUIDE.md#configuring-host-cli-tools-when-omniroute-runs-in-docker). L'**endpoint di applicazione** della dashboard (`POST /api/cli-tools/apply`) applica lo stesso controllo: in un container, un'operazione di scrittura la cui destinazione non è montata tramite bind dall' host restituisce **`422`** con `containerEphemeralTarget: true`, il testo sicuro dell'errore e — per gli strumenti dotati di una procedura per l'host (claude, codex, opencode, cline, kilo, continue) — un `hostSetupCommand` (ad es. `omniroute setup-opencode`) da eseguire sull'host; non viene scritto nulla. `dryRun: true` continua a funzionare in modalità container e restituisce un'anteprima con i dati sensibili oscurati e il percorso di destinazione, senza modificare il disco. Il contenuto dell'anteprima non costituisce una configurazione contenente credenziali da copiare o importare. Esegui l'applicazione sull'host usando gli input originali relativi a strumento/URL di base/chiave API/modello, oppure utilizza il comando di configurazione lato host indicato. Consulta [Sicurezza della configurazione CLI](../security/CLI-CONFIGURATION.md) per l'intestazione dell'anteprima e il contratto della richiesta. Questo comportamento è intenzionale ed è protetto da test di regressione in `tests/unit/api/cli-tools/apply-container-guard.test.ts` — non "correggere" mai un errore 422 rimuovendo il controllo. --- ## Fonte autorevole Il catalogo unificato si trova in `src/shared/constants/cliTools.ts` come `CLI_TOOLS: Record`. Ogni voce contiene questi campi (definiti in `src/shared/schemas/cliCatalog.ts`): | Campo | Tipo | Descrizione | | ----------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------ | | `category` | `"code" \| "agent"` | La pagina in cui viene visualizzato lo strumento | | `vendor` | `string` | Origine dello strumento ("Anthropic", "OSS (P. Gauthier)") | | `acpSpawnable` | `boolean` | Utilizzabile anche come agente ACP (viene mostrato un badge) | | `baseUrlSupport` | `"full" \| "partial" \| "none"` | Livello di supporto per endpoint personalizzati. `"none"` = backlog MITM | | `configType` | `"env" \| "custom" \| "guide" \| "custom-builder" \| "mitm"` | Meccanismo di configurazione | | `id`, `name`, `color`, `description`, `docsUrl` | standard | Campi principali di visualizzazione | Le voci con `baseUrlSupport: "none"` **non vengono mostrate** nelle pagine della dashboard: sono registrate nel backlog MITM per il piano 11 (vedere `_tasks/features-v3.8.6/refactorpages/_orchestration/_plan11-mitm-backlog.md`). ### Livelli di funzionalità (catalogato × rilevabile × configurabile × avviabile) Non tutti gli strumenti catalogati sono rilevabili, configurabili o avviabili. Ogni livello ha una singola fonte dichiarativa e un test di divergenza ne mantiene l'allineamento: | Livello | Significato | Dichiarato in | | ----------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ | | **Catalogato** | Compare nel catalogo della dashboard (nome, fornitore, documentazione, tipo di configurazione) | `src/shared/constants/cliTools.ts` (`CLI_TOOLS`) | | **Rilevabile** | Rilevamento del binario/della configurazione, controlli di integrità, percorsi di configurazione | `src/shared/services/cliRuntime.ts` (catalogo runtime `CLI_TOOLS`) | | **Configurabile** | Supportato da `omniroute configure ` (esiste una procedura di configurazione) | `bin/cli/cli-manifest.mjs` (`configure: true`) | | **Avviabile** | Supportato da `omniroute run ` (iniezione di variabili d'ambiente/argomenti definita) | `bin/cli/cli-manifest.mjs` (`run: true`) | `bin/cli/cli-manifest.mjs` è il manifest eseguibile canonico per le interfacce dei comandi CLI: `run`, `configure` e i generatori di completamento della shell derivano tutti da esso i propri elenchi di destinazioni, la risoluzione degli alias (ad esempio `kilocode`/`kilo-code`/`kilo_cli` → `kilo`) e il collegamento del flag `--model`. Il controllo di divergenza `tests/unit/cli/cli-manifest-drift.test.ts` verifica che il manifest, il catalogo runtime, il catalogo dell'interfaccia utente e ogni interfaccia che li utilizza rimangano sincronizzati: una destinazione aggiunta a un'interfaccia ma non alle altre fa fallire la suite anziché consentire una divergenza silenziosa. --- ## 1. Catalogo di CLI Code (27 strumenti) Tutti gli strumenti visualizzati in `/dashboard/cli-code`. Quelli con `baseUrlSupport: none` vengono configurati tramite MITM o una guida manuale anziché mediante un URL di base personalizzato: | id | nome | fornitore | supporto URL di base | tipo di configurazione | avviabile tramite ACP | | ------------ | ----------------------- | ------------------- | -------------------- | ---------------------- | --------------------- | | claude | Claude Code | Anthropic | full | env | true | | codex | OpenAI Codex CLI | OpenAI | full | custom | true | | zcode | ZCode (GLM Coding Plan) | Z.ai | none | custom | false | | cline | Cline | OSS (ex-Claude Dev) | full | custom | true | | kilo | Kilo Code | Kilo-Org | full | custom | false | | roo | Roo Code | Roo (OSS) | full | guide | false | | continue | Continue | continue.dev | full | guide | false | | aider | Aider | OSS (P. Gauthier) | full | guide | true | | forge | ForgeCode | Antinomy HQ | full | custom | true | | jcode | jcode | 1jehuang (OSS) | full | custom | false | | deepseek-tui | DeepSeek TUI | Hunter Bown (OSS) | full | custom | false | | codewhale | CodeWhale | Hmbown (OSS) | full | custom | false | | opencode | OpenCode | Anomaly (ex-SST) | full | guide | true | | droid | Factory Droid | Factory AI | partial | guide | false | | copilot | GitHub Copilot CLI | GitHub/MS | full | custom | false | | cursor-cli | Cursor CLI | Anysphere | partial | guide | true | | smelt | Smelt | leonardcser (OSS) | full | custom | false | | pi | Pi (pi-coding-agent) | M. Zechner (OSS) | full | custom | false | | grok-build | Grok Build | xAI | full | custom | false | | crush | Crush | OSS (Charm) | full | custom | false | | qwen | Qwen Code | Alibaba | full | guide | true | | zed | Zed | Zed Industries | full | guide | false | | cursor | Cursor | Anysphere | none | guide | false | | antigravity | Antigravity | Google | none | mitm | false | | hermes | Hermes | Nous Research | none | guide | false | | kiro | Kiro AI | Amazon | none | mitm | false | | custom | CLI personalizzata | — | full | custom-builder | false | Gli strumenti con `baseUrlSupport: "partial"` mostrano il badge "⚠ URL di base parziale" nella scheda della dashboard. --- ## 2. Catalogo degli agenti CLI (10 strumenti) Agenti autonomi visualizzati in `/dashboard/cli-agents`: | id | nome | fornitore | supporto baseUrl | avviabile tramite ACP | | ------------ | ---------------- | ------------------------ | ---------------- | --------------------- | | hermes-agent | Hermes Agent | Nous Research | full | false | | openclaw | OpenClaw | OSS (P. Steinberger) | full | true | | goose | Goose | Block / Linux Foundation | full | true | | interpreter | Open Interpreter | OSS | full | true | | warp | Warp AI | Warp Inc. | partial | true | | agent-deck | Agent Deck | asheshgoplani (OSS) | full | false | | omp | Oh My Pi | OSS | full | true | | letta | Letta CLI | Letta | full | false | | prime-agent | Prime Agent | Prime Intellect (OSS) | full | false | | 5dive | 5dive | OSS (5dive-ai) | full | false | --- ## 3. Agenti ACP (/dashboard/acp-agents) Questa pagina (rinominata da `/dashboard/agents`) mostra le CLI che OmniRoute può **avviare** come motori di esecuzione backend tramite il protocollo stdio/ACP. Il catalogo viene gestito separatamente in `src/lib/acp/registry.ts` e **non** coincide con `CLI_TOOLS`. --- ## 4. Backlog MITM (non visualizzato nella dashboard) Le seguenti CLI non supportano nativamente un URL di base personalizzato e **non sono elencate** nelle pagine CLI Code o CLI Agents. Sono candidate all'intercettazione MITM nel piano 11: | CLI | Motivo | | ------------------- | ---------------------------------------------------------------- | | windsurf | BYOK limitato a determinati modelli Claude + URL/token aziendale | | amp | Ecosistema chiuso (Sourcegraph) | | amazon-q / kiro-cli | Autenticazione AWS SSO, nessun URL personalizzato | | cowork | Anthropic Desktop, nessun endpoint configurabile | Consultare `_tasks/features-v3.8.6/refactorpages/_orchestration/_plan11-mitm-backlog.md` per il riferimento incrociato completo. --- ## 5. API di rilevamento in batch Il rilevamento di tutti gli strumenti viene aggregato tramite un unico endpoint: **`GET /api/cli-tools/all-statuses`** - Autenticazione: `requireCliToolsAuth(request)` (come per le altre route `/api/cli-tools/`) - Restituisce: `Record` (tipo: `src/shared/types/cliBatchStatus.ts`) - Strategia: `Promise.all` su tutti gli strumenti, timeout di 5s per strumento - Cache: LRU in memoria indicizzata in base al valore `mtime` del file di configurazione. La cache viene invalidata quando `mtime` cambia. Viene reimpostata al riavvio del server. Struttura della risposta per ogni strumento: ```ts interface ToolBatchStatus { detection: { installed: boolean; runnable: boolean; version?: string; command?: string; commandPath?: string; reason?: string; }; config: { status: "configured" | "not_configured" | "not_installed" | "unknown" | "other"; endpoint?: string | null; lastConfiguredAt?: string | null; }; error?: string; // sanificato, senza tracce dello stack } ``` --- ## 6. Gestori delle impostazioni per i nuovi strumenti I nuovi strumenti con `configType: "custom"` dispongono di route API dedicate per le impostazioni: | Route | Strumento | | ------------------------------------------- | ------------------------------------------------------------------------------- | | `POST /api/cli-tools/forge-settings` | ForgeCode (.forge.toml) | | `POST /api/cli-tools/jcode-settings` | jcode (flag --base-url) | | `POST /api/cli-tools/deepseek-tui-settings` | DeepSeek TUI (OPENAI_BASE_URL, legacy) | | `POST /api/cli-tools/codewhale-settings` | CodeWhale (OPENAI_BASE_URL, principale + sincronizzazione legacy `~/.deepseek`) | | `POST /api/cli-tools/smelt-settings` | Smelt | | `POST /api/cli-tools/pi-settings` | Agente di programmazione Pi | | `POST /api/cli-tools/grok-build-settings` | Grok Build (~/.grok/config.toml, `[model.omniroute]`) | | `POST /api/cli-tools/qwen-settings` | Qwen Code (`~/.qwen/settings.json` + chiave `.env` dedicata) | Tutte le route utilizzano `sanitizeErrorMessage()` per le risposte di errore (Regola ferrea n. 12). --- ## 7. Architettura delle pagine della dashboard ### CLI Code (`/dashboard/cli-code`) - `src/app/(dashboard)/dashboard/cli-code/page.tsx` — componente server - `src/app/(dashboard)/dashboard/cli-code/CliCodePageClient.tsx` — griglia client - `src/app/(dashboard)/dashboard/cli-code/[id]/page.tsx` — pagina dei dettagli dello strumento - `src/app/(dashboard)/dashboard/cli-code/components/` — 12 schede specializzate per gli strumenti + `ToolDetailClient.tsx` ### Agenti CLI (`/dashboard/cli-agents`) - `src/app/(dashboard)/dashboard/cli-agents/page.tsx` — componente server - `src/app/(dashboard)/dashboard/cli-agents/CliAgentsPageClient.tsx` — griglia client - `src/app/(dashboard)/dashboard/cli-agents/[id]/page.tsx` — riutilizza `ToolDetailClient` ### Agenti ACP (`/dashboard/acp-agents`) - `src/app/(dashboard)/dashboard/acp-agents/page.tsx` — componente server (spostato da `agents/`) ### Componenti UI condivisi (`src/shared/components/cli/`) | File | Scopo | | ----------------------- | ---------------------------------------------------------------------- | | `CliToolCard.tsx` | Scheda di stato intelligente (rilevamento + configurazione + endpoint) | | `CliConceptCard.tsx` | Scheda esplicativa dei concetti specifica per pagina | | `CliComparisonCard.tsx` | Confronto a tre colonne tra i tipi di CLI | | `BaseUrlSelect.tsx` | Menu a discesa degli endpoint (locale/cloud/personalizzato) | | `ApiKeySelect.tsx` | Selettore della chiave API | | `ManualConfigModal.tsx` | Finestra modale con frammento di configurazione copiabile | ### Hook condiviso (`src/shared/hooks/cli/`) | File | Scopo | | ------------------------- | --------------------------------------------------------------------------------------- | | `useToolBatchStatuses.ts` | Recupera `/api/cli-tools/all-statuses` e gestisce lo stato di caricamento/aggiornamento | --- ## 8. i18n Nuovi namespace aggiunti nel piano 14 F9: | Namespace | Scopo | | ----------- | ------------------------------------------------------------------------------------------------------------- | | `cliCommon` | Stringhe condivise (etichette delle schede, testi di concetti/confronti, etichette delle pagine di dettaglio) | | `cliCode` | Stringhe della pagina CLI Code | | `cliAgents` | Stringhe della pagina CLI Agents | | `acpAgents` | Stringhe della pagina ACP Agents | Sono fornite traduzioni complete in PT-BR e EN. Le altre 39 impostazioni locali utilizzano automaticamente EN come fallback tramite l'unione a livello di namespace in `src/i18n/request.ts`. --- ## 9. Avvio rapido ### Passaggio 1 — Ottieni una chiave API OmniRoute 1. Apri `/dashboard/api-manager` → **Crea chiave API** 2. Assegnale un nome (ad es. `cli-tools`) e seleziona tutte le autorizzazioni 3. Copia la chiave: ti servirà per ogni CLI indicata di seguito > La chiave ha questo aspetto: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` --- ### Passaggio 2 — Installa gli strumenti CLI Tutti gli strumenti basati su npm richiedono Node.js 22.22.2+ o 24.x: ```bash # Claude Code (Anthropic) npm install -g @anthropic-ai/claude-code # OpenAI Codex npm install -g @openai/codex # OpenCode npm install -g opencode-ai # Cline npm install -g cline # KiloCode npm install -g kilocode # Qwen Code npm install -g @qwen-code/qwen-code # Google Gemini CLI (avviabile tramite `omniroute run gemini` → interfaccia /v1beta) npm install -g @google/gemini-cli # Aider pip install aider-chat # Smelt cargo install smelt # Basato su Rust # Agente di programmazione Pi # consulta https://github.com/zechnerj/pi-coding-agent per l'installazione # jcode # consulta https://github.com/1jehuang/jcode per l'installazione ``` --- ### Passaggio 3 — Configura tramite la dashboard 1. Vai a `http://localhost:20128/dashboard/cli-code` 2. Trova il tuo strumento nella griglia 3. Fai clic sulla scheda per aprire la pagina dei dettagli dello strumento 4. Seleziona la chiave API e l'URL di base 5. Fai clic su **Applica configurazione** oppure copia il frammento di configurazione manuale --- ### Passaggio 4 — Imposta le variabili di ambiente globali ```bash # Endpoint universale OmniRoute export OPENAI_BASE_URL="http://localhost:20128/v1" export OPENAI_API_KEY="sk-your-omniroute-key" export ANTHROPIC_BASE_URL="http://localhost:20128" export ANTHROPIC_AUTH_TOKEN="sk-your-omniroute-key" # Gemini CLI legge GOOGLE_GEMINI_BASE_URL dalla RADICE (il relativo SDK aggiunge autonomamente /v1beta/...) export GOOGLE_GEMINI_BASE_URL="http://localhost:20128" export GEMINI_API_KEY="sk-your-omniroute-key" ``` > Per un **server remoto**, sostituisci `localhost:20128` con l'indirizzo IP o il dominio del server, > ad es. `http://:20128`. --- ### Passaggio 4 — Configura ogni strumento #### Claude Code ```bash # Crea ~/.claude/settings.json: mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF { "env": { "ANTHROPIC_BASE_URL": "http://localhost:20128", "ANTHROPIC_AUTH_TOKEN": "sk-your-omniroute-key" } } EOF ``` Usa la radice unificata del gateway Anthropic per Claude Code. Non aggiungere `/v1` qui. **Test:** `claude "say hello"` --- #### OpenAI Codex Il Codex moderno (v0.137+) legge esclusivamente `~/.codex/config.toml`: il vecchio `config.yaml` appartiene alla CLI npm precedente e viene ignorato senza alcun avviso. La chiave API rimane nella variabile di ambiente `OMNIROUTE_API_KEY` (`env_key`) e non viene mai inserita nel file: ```bash mkdir -p ~/.codex && cat > ~/.codex/config.toml << EOF model_provider = "omniroute" [model_providers.omniroute] name = "OmniRoute" base_url = "http://localhost:20128/v1" env_key = "OMNIROUTE_API_KEY" requires_openai_auth = false EOF export OMNIROUTE_API_KEY="sk-your-omniroute-key" ``` Riferimento completo (profili, `wire_api`, finestre di contesto): [CODEX-CLI-CONFIGURATION.md](../guides/CODEX-CLI-CONFIGURATION.md). **Test:** `codex "what is 2+2?"` --- #### OpenCode ```bash mkdir -p ~/.config/opencode && cat > ~/.config/opencode/opencode.json << EOF { "\$schema": "https://opencode.ai/config.json", "provider": { "omniroute": { "npm": "@ai-sdk/openai-compatible", "name": "OmniRoute", "options": { "baseURL": "http://localhost:20128/v1", "apiKey": "sk-your-omniroute-key" }, "models": { "claude-sonnet-4-5": { "name": "claude-sonnet-4-5" }, "claude-sonnet-4-5-thinking": { "name": "claude-sonnet-4-5-thinking" }, "gemini-3-flash": { "name": "gemini-3-flash" } } } } } EOF ``` **Test:** `opencode` > Usa `opencode run "your prompt" --model omniroute/claude-sonnet-4-5-thinking --variant high` > per inviare varianti con ragionamento. --- #### Cline (CLI o VS Code) **Modalità CLI:** ```bash mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF { "apiProvider": "openai", "openAiBaseUrl": "http://localhost:20128/v1", "openAiApiKey": "sk-your-omniroute-key" } EOF ``` **Modalità VS Code:** Impostazioni dell'estensione Cline → Provider API: `OpenAI Compatible` → URL di base: `http://localhost:20128/v1` In alternativa, usa la dashboard di OmniRoute → **Strumenti CLI → Cline → Applica configurazione**. --- #### KiloCode (CLI o VS Code) **Modalità CLI:** ```bash kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key ``` **Impostazioni di VS Code:** ```json { "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", "kilo-code.apiKey": "sk-your-omniroute-key" } ``` In alternativa, usa la dashboard di OmniRoute → **Strumenti CLI → KiloCode → Applica configurazione**. --- #### Continue (estensione VS Code) Modifica `~/.continue/config.yaml`: ```yaml models: - name: OmniRoute provider: openai model: auto apiBase: http://localhost:20128/v1 apiKey: sk-your-omniroute-key default: true ``` Riavvia VS Code dopo la modifica. --- #### VS Code Insiders (`chatLanguageModels.json`) Usa questa opzione quando VS Code Insiders è configurato per modelli con endpoint personalizzati e desideri che OmniRoute funzioni senza un campo di intestazione personalizzato. **Posizione consigliata:** - Linux: `~/.config/Code - Insiders/User/chatLanguageModels.json` - Windows: `%APPDATA%/Code - Insiders/User/chatLanguageModels.json` **Esempio di utilizzo dell'alias OmniRoute con token:** ```json [ { "vendor": "customendpoint", "id": "auto", "name": "OmniRoute Auto", "family": "gpt-4", "version": "1.0.0", "url": "http://localhost:20128/api/v1/vscode/sk-your-omniroute-key/chat/completions", "modelsUrl": "http://localhost:20128/api/v1/vscode/sk-your-omniroute-key/models", "requestFormat": "openai-chat-completions", "contextWindow": 256000, "maxOutputTokens": 32768, "auth": { "type": "none" } } ] ``` **Note:** - Sostituisci `sk-your-omniroute-key` con una chiave API creata in OmniRoute. - Il campo `url` deve puntare a `/api/v1/vscode/{token}/chat/completions`. - Il campo `modelsUrl` deve puntare a `/api/v1/vscode/{token}/models`. - Quando il client supporta header personalizzati, preferisci il normale flusso `/v1` con header Bearer. - I token incorporati nell'URL costituiscono una soluzione di compatibilità alternativa e potrebbero comparire nei log dell'editor o nella cronologia del proxy. --- #### Kiro CLI (Amazon) ```bash # Accedi al tuo account AWS/Kiro: kiro-cli login # La CLI utilizza la propria autenticazione: OmniRoute non è necessario come backend per Kiro CLI. # Usa kiro-cli insieme a OmniRoute per gli altri strumenti. kiro-cli status ``` Per l'app desktop **Kiro IDE**, utilizza l'endpoint MITM esposto da OmniRoute in `/dashboard/cli-tools → Kiro`. --- ## 10. CLI interna di OmniRoute Il binario `omniroute` fornisce comandi per il ciclo di vita del server, la configurazione, la diagnostica e la gestione dei provider. Punto di ingresso: `bin/omniroute.mjs`. ```bash omniroute # Avvia il server (porta predefinita 20128) omniroute setup # Procedura guidata di configurazione interattiva omniroute doctor # Controlla configurazione, DB, porte e runtime omniroute providers list # Connessioni ai provider configurate omniroute providers test-all # Verifica tutte le connessioni attive omniroute reset-password # Reimposta la password dell'amministratore omniroute logs # Trasmette i log delle richieste omniroute health # Stato dettagliato (circuit breaker, cache, memoria) omniroute --version # Mostra la versione omniroute --help # Mostra tutti i comandi ``` ### Configurazione e inizializzazione ```bash omniroute setup # Procedura guidata di configurazione interattiva omniroute setup --non-interactive # Modalità CI/automazione (legge variabili d'ambiente + flag) omniroute setup --password '' # Imposta direttamente la password dell'amministratore omniroute setup --add-provider \ --provider openai \ --api-key '' \ --test-provider # Aggiunge e verifica un provider in un'unica operazione ``` Variabili d'ambiente riconosciute per la configurazione non interattiva: | Variabile | Scopo | | ------------------- | ------------------------------------------------------------------------------- | | `OMNIROUTE_API_KEY` | Chiave API del provider (associata a `--api-key` tramite `.env()` di Commander) | | `DATA_DIR` | Sostituisce la directory dei dati di OmniRoute | Tutti gli altri input non interattivi vengono passati come flag, non come variabili d'ambiente: `--password`, `--provider`, `--provider-name`, `--provider-base-url`, `--default-model` (vedere le opzioni di `omniroute setup` sopra). ### Diagnostica ```bash omniroute doctor # Controlla configurazione, DB, porte, runtime, memoria e operatività omniroute doctor --json # JSON leggibile dalle macchine omniroute doctor --no-liveness # Ignora il controllo di integrità HTTP omniroute doctor --host 0.0.0.0 # Sostituisce l'host per il controllo di operatività omniroute doctor --liveness-url # Sostituisce l'URL completo dell'endpoint di integrità ``` Il comando doctor esegue questi controlli: `Config`, `Database`, `Storage/encryption`, `Port availability`, `Node runtime`, `Native binary` (better-sqlite3), `Memory` e `Server liveness`. Termina con un codice diverso da zero se uno dei controlli restituisce `fail`. ### Gestione dei provider ```bash omniroute providers available # Catalogo dei provider OmniRoute omniroute providers available --search openai # Filtra il catalogo per ID/nome/alias/categoria omniroute providers available --category api-key # Filtra per categoria (api-key, oauth, free, ...) omniroute providers available --json # JSON leggibile dalle macchine omniroute providers list # Connessioni ai provider configurate omniroute providers list --json omniroute providers test # Verifica una connessione configurata omniroute providers test-all # Verifica tutte le connessioni attive omniroute providers validate # Convalida strutturale esclusivamente locale omniroute providers add --credential-env PROVIDER_KEY omniroute providers import ./providers.json --dry-run --json omniroute providers auth # Flusso OAuth esistente omniroute providers edit --default-model omniroute providers remove --yes ``` `providers add/import/auth/edit/remove` utilizzano principalmente l'API e funzionano quindi con il contesto attivo locale o remoto. Per l'inserimento delle credenziali è consigliabile utilizzare `--credential-stdin` o `--credential-env`; `--dry-run --json` riporta solamente la presenza/struttura con i dati sensibili oscurati. `providers available` legge il catalogo di OmniRoute; `providers list/test/test-all/validate` mantengono il loro comportamento SQLite locale e non richiedono che il server sia in esecuzione. Per un nodo personalizzato compatibile con OpenAI o Anthropic, associa le credenziali all'ID del nodo restituito da `omniroute nodes add`, utilizzando `omniroute keys add "$NODE_ID" --stdin`. Ciò richiede un server in esecuzione e l'autenticazione di gestione per il contesto attivo. La CLI utilizza `POST /api/providers`, che convalida il nodo e copia le impostazioni del relativo endpoint nella connessione. Un nodo mancante, un errore di autorizzazione o un server non disponibile restituisce un errore senza creare credenziali locali di ripiego. `nodes add --base-url` imposta l'endpoint del nodo; è distinto dall'indirizzo del server in `OMNIROUTE_BASE_URL`. Per i file OpenAPI, utilizza `omniroute openapi dump --format json --out ./openapi.json`; l'opzione globale `--output` seleziona la formattazione di visualizzazione della CLI, non il nome di un file di destinazione. ### Ripristino e reimpostazione ```bash omniroute reset-password # Reimposta la password dell'amministratore (anche: omniroute-reset-password) omniroute reset-encrypted-columns # Mostra un avviso + una simulazione per la reimpostazione delle credenziali crittografate omniroute reset-encrypted-columns --force # Imposta effettivamente a null le credenziali crittografate in SQLite ``` ### Esportazione delle credenziali (⚠ maneggiare con cautela) ```bash omniroute auth export # Mostra un avviso + richiesta di conferma — nessun accesso al DB omniroute auth export --force # Esporta le credenziali DECRITTOGRAFATE di TUTTE le connessioni su stdout come JSON omniroute auth export --force --id # Esporta solo la connessione corrispondente omniroute auth export --force --format env # Genera righe OMNIROUTE__= omniroute auth export --force --out creds.json # Scrive in un file (creato con autorizzazioni 0600) ``` `auth export` è **solo locale** (lettura diretta di SQLite, nessuna route HTTP) e stampa/scrive intenzionalmente i valori **in chiaro** di `apiKey`/`accessToken`/`refreshToken`/`idToken`: questa è una funzionalità, non un bug. Nulla viene letto dal database e nulla viene decifrato senza `--force`. Un banner di avviso viene sempre stampato su stderr prima che vengano emessi dati in chiaro. Richiede che `STORAGE_ENCRYPTION_KEY` sia impostata. Un campo che non può essere decifrato (chiave obsoleta, testo cifrato danneggiato) viene segnalato come `DecryptFailed: true`, anziché interrompere l'intera esportazione o esporre l'errore sottostante. ### Altri sottocomandi Questi presuppongono che sia in esecuzione un server OmniRoute, salvo diversa indicazione: ```bash omniroute status # Stato completo del runtime omniroute logs # Trasmette i log delle richieste (--json, --search, --follow) omniroute config list # Mostra gli strumenti CLI configurati omniroute provider list # Elenca i provider disponibili (alias di providers list) omniroute provider add # Registra OmniRoute come provider in uno strumento omniroute keys add | list | remove # Gestisce le chiavi API omniroute models [provider] # Elenca i modelli (--json, --search) omniroute combo list | switch | create | delete omniroute backup # Crea uno snapshot della configurazione e del DB omniroute restore # Ripristina da uno snapshot precedente omniroute health # Stato dettagliato (circuit breaker, cache, memoria) omniroute quota # Utilizzo della quota dei provider omniroute cache # Stato della cache omniroute cache clear # Svuota le cache semantica e delle firme omniroute mcp status | restart # Stato / riavvio del server MCP omniroute a2a status | card # Stato del server A2A / scheda dell'agente omniroute tunnel list | create | stop # Gestisce i tunnel (cloudflare/tailscale/ngrok) omniroute env show | get | set # Visualizza / imposta le variabili d'ambiente (temporanee) omniroute test # Test rapido della connettività dei provider omniroute update # Verifica la disponibilità di aggiornamenti omniroute completion # Genera il completamento della shell ``` ### Flag comuni | Flag | Descrizione | | ------------------- | ------------------------------------------------------------- | | `--no-open` | Non apre automaticamente il browser all'avvio | | `--port ` | Sostituisce la porta API (predefinita: 20128) | | `--mcp` | Esegue come server MCP tramite stdio (per gli IDE) | | `--non-interactive` | Modalità CI (nessuna richiesta; legge da ambiente/flag) | | `--json` | Output JSON leggibile dalle macchine (doctor, provider, ecc.) | | `--help`, `-h` | Mostra la guida specifica del comando | | `--version`, `-v` | Stampa la versione installata | --- ## Endpoint API disponibili | Endpoint | Descrizione | Da usare per | | -------------------------- | -------------------------------- | ------------------------------------------ | | `/v1/chat/completions` | Chat standard (tutti i provider) | Tutti gli strumenti moderni | | `/v1/responses` | API Responses (formato OpenAI) | Codex, flussi di lavoro agentici | | `/v1/completions` | Completamenti di testo legacy | Strumenti meno recenti che usano `prompt:` | | `/v1/embeddings` | Embedding di testo | RAG, ricerca | | `/v1/images/generations` | Generazione di immagini | GPT-Image, Flux, ecc. | | `/v1/audio/speech` | Sintesi vocale | ElevenLabs, OpenAI TTS | | `/v1/audio/transcriptions` | Trascrizione vocale | Deepgram, AssemblyAI | Esempi pronti da incollare con un URL OmniRoute contenente un token: ```txt Esempio di token: sk-a3ab3c080beaee3a-69f4a4-070d71af Base OpenAI standard: http://localhost:20128/v1 Modelli VS Code: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/models Chat VS Code: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/chat/completions Risposte VS Code: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/responses Tag Ollama: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/api/tags Chat Ollama: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/api/chat ``` --- ## Risoluzione dei problemi | Errore | Causa | Soluzione | | ------------------------------------------------------- | -------------------------------------- | ----------------------------------------------------------- | | `Connection refused` | OmniRoute non è in esecuzione | `omniroute serve` | | `401 Unauthorized` | Chiave API errata | Controlla in `/dashboard/api-manager` | | `No combo configured` | Nessuna combinazione di routing attiva | Configurala in `/dashboard/combos` | | La CLI mostra "not installed" | Il file binario non è nel PATH | Controlla `which ` | | La dashboard mostra "not detected" dopo l'installazione | Cache obsoleta | Fai clic su "⟳ Aggiorna rilevamento" nella dashboard | | Vecchio link `/dashboard/cli-tools` | Segnalibro precedente alla v3.8.6 | Reindirizzamento automatico a `/dashboard/cli-code` (308) | | Vecchio link `/dashboard/agents` | Segnalibro precedente alla v3.8.6 | Reindirizzamento automatico a `/dashboard/acp-agents` (308) | ## Gestire i criteri delle chiavi di inferenza con la CLI OmniRoute Usa un contesto di gestione autenticato (consulta [Modalità remota](../guides/REMOTE-MODE.md)) per esaminare o aggiornare una chiave di inferenza esistente tramite il relativo ID: ```bash omniroute --output json keys policy show KEY_ID omniroute keys policy set KEY_ID --unrestricted omniroute --output json keys policy show KEY_ID ``` `--unrestricted` è un alias di `--model-access-mode all`. L'aggiornamento cancella l'elenco dei modelli consentiti. Mantiene ambiti, regole di connessione, modelli bloccati, limiti di frequenza e limiti di costo, quindi questi altri controlli possono comunque negare una richiesta. Anche `--allowed-models ""` seleziona `all`; combinalo con `--model-access-mode restricted` per mantenere una chiave con restrizioni senza modelli consentiti. Un elenco non vuoto separato da virgole seleziona `restricted`, a meno che non sia specificato esplicitamente. La combinazione contraddittoria di `all` e di un elenco non vuoto di modelli consentiti viene rifiutata prima dell'invio di una richiesta. `--rate-limit 30` imposta le richieste al minuto e mantiene le regole per le altre finestre temporali. `--max-cost 5` abilita il limite giornaliero in USD senza modificare quello settimanale; `--max-cost 0` rimuove il limite giornaliero e mantiene l'impostazione esistente del limite di utilizzo e il limite settimanale. I campi dei criteri omessi rimangono invariati. Le modifiche ai limiti di frequenza leggono prima i criteri correnti; evita modifiche simultanee all'array dei limiti di frequenza della stessa chiave. I comandi dei criteri usano richieste autenticate `GET`/`PATCH /api/keys/{id}` e rispettano il contesto attivo e l'opzione globale `--api-key`. L'output JSON contiene solo i campi dei criteri, senza la chiave memorizzata né la sua rappresentazione mascherata. Una credenziale destinata esclusivamente all'inferenza non può autorizzare modifiche di gestione. Una risposta 401/403 richiede di controllare la credenziale e il contesto di gestione; non dimostra un errore del token CLI locale o del salt. Consulta [Token CLI](../security/CLI_TOKEN.md) per il contratto separato di autenticazione locale.