OmniRoute/docs/i18n/it/docs/frameworks/OPENCODE.md

OpenCode Integration (Italiano)

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

---

Stato: Generalmente disponibile. Destinatari: Operatori che collegano OpenCode a un'installazione OmniRoute. Fonte di verità (schema di configurazione): src/shared/services/opencodeConfig.ts Fonte di verità (pacchetto npm): @omniroute/opencode-provider/ (workspace pubblicabile)

OpenCode è un client IA agentico per CLI/desktop. Legge il proprio catalogo di provider da ~/.config/opencode/opencode.json (o opencode.jsonc) e segue lo schema disponibile all'indirizzo https://opencode.ai/config.json. OmniRoute si presenta a OpenCode come uno di questi provider: ogni richiesta passa attraverso l'interfaccia /v1 standard di OmniRoute compatibile con OpenAI, consentendo a OpenCode di usufruire automaticamente del routing Auto-Combo, dei circuit breaker, delle policy delle chiavi, dell'osservabilità e così via.

Sono disponibili due percorsi di integrazione supportati. Scegline uno: generano la stessa configurazione.

---

Percorso 1 — Generatore CLI (senza installazione npm)

Consigliato per gli utenti finali. Incluso con OmniRoute. Scrive direttamente in opencode.json.

# Dopo aver installato OmniRoute (npm i -g @omniroute/cli o clone locale)
omniroute config opencode \
  --base-url http://localhost:20128 \
  --api-key "$OMNIROUTE_API_KEY"

Dietro le quinte, la CLI chiama mergeOpenCodeConfigText() (src/shared/services/opencodeConfig.ts:104), quindi un file opencode.json esistente mantiene gli altri provider e i commenti. La voce OmniRoute viene aggiunta o sostituita atomicamente.

File risultante (catalogo dei modelli predefinito):

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "omniroute": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "OmniRoute",
      "options": {
        "baseURL": "http://localhost:20128/v1",
        "apiKey": "<your-key>",
      },
      "models": {
        "claude-opus-4-5-thinking": { "name": "claude-opus-4-5-thinking" },
        "claude-sonnet-4-5-thinking": { "name": "claude-sonnet-4-5-thinking" },
        "gemini-3.1-pro-high": { "name": "gemini-3.1-pro-high" },
        "gemini-3-flash": { "name": "gemini-3-flash" },
      },
    },
  },
}

---

Percorso 2 — Pacchetto npm @omniroute/opencode-provider

Consigliato quando si automatizza la configurazione da Node/TS (pipeline CI, monorepo, flussi di installazione personalizzati).

npm install --save-dev @omniroute/opencode-provider

import { writeFileSync } from "node:fs";
import { buildOmniRouteOpenCodeConfig } from "@omniroute/opencode-provider";

const config = buildOmniRouteOpenCodeConfig({
  baseURL: "http://localhost:20128",
  apiKey: process.env.OMNIROUTE_API_KEY ?? "sk_omniroute",
  // Facoltativo: sostituisce il catalogo dei modelli esposto a OpenCode
  models: ["auto", "claude-opus-4-7", "gpt-5.5"],
  modelLabels: { auto: "Auto-Combo" },
});

writeFileSync("opencode.json", JSON.stringify(config, null, 2));

Per un'unione non distruttiva con un file esistente, replica mergeOpenCodeConfigText() da opencodeConfig.ts oppure chiama il generatore CLI.

Consulta il README del pacchetto per l'API completa.

---

Cosa fa effettivamente il runtime

Entrambi i percorsi producono lo stesso provider.omniroute.npm: "@ai-sdk/openai-compatible". Durante l'esecuzione, OpenCode carica @ai-sdk/openai-compatible (già una dipendenza transitiva di OpenCode) e lo configura con baseURL + apiKey. Da quel momento:

Interfaccia utente/agente OpenCode
   → @ai-sdk/openai-compatible
      → HTTP POST {baseURL}/chat/completions          (interfaccia OpenAI di OmniRoute)
         → gestore OmniRoute /v1/chat/completions     (open-sse/handlers/chatCore.ts)
            → routing combinato / Auto-Combo / esecutore
               → provider upstream

Il plugin non interagisce mai direttamente con HTTP. Genera soltanto la configurazione.

---

Valori predefiniti del catalogo dei modelli

export const OMNIROUTE_DEFAULT_OPENCODE_MODELS = [
  "claude-opus-4-5-thinking",
  "claude-sonnet-4-5-thinking",
  "gemini-3.1-pro-high",
  "gemini-3-flash",
] as const;

Puoi sovrascriverli tramite models: [...]. Aggiunte consigliate:

• "auto" — rende disponibile Auto-Combo di OmniRoute, il router senza configurazione. Consente a OpenCode di scegliere "il miglior modello disponibile" senza dover codificare il catalogo in modo rigido.
• "<combo-name>" — qualsiasi combo definita nella dashboard; OmniRoute la risolve in modo trasparente.

---

Normalizzazione degli URL

La funzione helper accetta entrambe le forme e genera esattamente un solo /v1:

Input	Output (options.baseURL)
http://localhost:20128	http://localhost:20128/v1
http://localhost:20128/	http://localhost:20128/v1
http://localhost:20128/v1	http://localhost:20128/v1
http://localhost:20128/v1///	http://localhost:20128/v1

Questa deduplicazione risolve il problema più comune riscontrato nelle configurazioni meno recenti. Se disponi di un file opencode.json precedente alla v3.8.0 che punta a /v1/v1/..., esegui nuovamente il generatore oppure richiama createOmniRouteProvider.

---

Modalità di autenticazione

Impostazione di OmniRoute	Valore apiKey consigliato
REQUIRE_API_KEY=false (predefinito in locale)	sk_omniroute (segnaposto letterale)
REQUIRE_API_KEY=true	Una vera chiave API per utente da Dashboard → API Keys.

Per i client in stile Anthropic che inviano x-api-key + anthropic-version, extractApiKey di OmniRoute accetta anche la chiave proveniente da x-api-key. OpenCode utilizza l'interfaccia OpenAI, quindi invierà sempre Authorization: Bearer ${apiKey} — in questo caso non si applica alcuna gestione speciale per Anthropic.

---

Risoluzione dei problemi

Sintomo	Causa	Soluzione
404 per ogni richiesta con URL contenente /v1/v1/	Configurazione obsoleta di un plugin precedente alla v3.8 che aggiungeva due volte il suffisso /v1.	Rigenera tramite il Percorso 1 o 2.
401 Invalid API key	OmniRoute ha REQUIRE_API_KEY=true e la chiave è sconosciuta.	Crea la chiave nella dashboard oppure imposta REQUIRE_API_KEY=false (solo in locale) e usa sk_omniroute.
Elenco dei modelli vuoto nell'interfaccia di OpenCode	Tutti e 4 i modelli predefiniti sono nascosti nelle impostazioni di visibilità dei provider di OmniRoute.	Passa models: ["auto", ...] per rendere disponibili quelli che hai abilitato.
Errore 500 di OpenCode con cannot read property 'models'	Le versioni meno recenti di OpenCode (< 0.1.x) non accettavano models inline.	Aggiorna OpenCode a una versione conforme allo schema v1 (opencode.ai/config.json).

---

Vedi anche

• Riferimento API — documentazione completa dell'API REST di OmniRoute
• Auto-Combo — cosa significa model: "auto"
• @omniroute/opencode-provider README
• Codice sorgente: src/shared/services/opencodeConfig.ts, src/lib/cli-helper/config-generator/opencode.ts, @omniroute/opencode-provider/src/index.ts