Documentazione

opencode

opencode crea i propri provider con Vercel AI SDK, quindi per indirizzarlo a un nuovo endpoint basta un blocco che specifichi un pacchetto npm e un baseURL. Il pacchetto scelto determina quale dei due formati di protocollo usa.

Un blocco provider in opencode.json — @ai-sdk/openai-compatible per i completamenti chat, @ai-sdk/openai quando vuoi la superficie /v1/responses.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "kunavo": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Kunavo",
      "options": {
        "baseURL": "https://api.kunavo.com/v1",
        "apiKey": "{env:KUNAVO_API_KEY}"
      },
      "models": {
        "claude-sonnet-5": {
          "name": "Claude Sonnet 5",
          "limit": { "context": 200000, "output": 64000 }
        },
        "claude-haiku-4-5": { "name": "Claude Haiku 4.5" }
      }
    }
  }
}

Testato il 2026-10-10 con opencode 1.18.35: un vero compito di programmazione è stato portato a termine con claude-sonnet-5 e il blocco provider qui sopra. I modelli GPT non sono ancora affidabili in opencode: opencode invia un limite di output con ogni richiesta e, con quel limite, il fornitore dietro i nostri modelli GPT a volte omette dalla risposta la chiamata allo strumento del modello, così un turno finisce senza la sua modifica. Usa un modello Claude in opencode finché questa nota non viene rimossa.

Il campo npm seleziona il formato di protocollo. @ai-sdk/openai-compatible usa /v1/chat/completions; @ai-sdk/openai usa /v1/responses. Kunavo supporta entrambi, quindi funzionano tutti e due: usa il pacchetto Responses se vuoi che gli elementi di ragionamento vengano mantenuti nella famiglia GPT; per tutto il resto usa il pacchetto chat completions.

"apiKey": "{env:KUNAVO_API_KEY}" legge la chiave dall’ambiente al caricamento. opencode.json è un file che finisce nei repository: una chiave letterale al suo interno non resta segreta.

Imposta limit.context e limit.output per ciascun modello. opencode tiene traccia del contesto rimanente usando quei valori, quindi un modello senza tali impostazioni viene conteggiato secondo un valore predefinito che non corrisponde ai suoi limiti.

Non hai ancora una chiave? Crea un account Kunavo, genera una chiave (inizia con sk-kn-) e aggiungi credito da $10: le chiamate vengono pagate con quel saldo e le chiamate non riuscite non vengono addebitate. La dashboard si apre quindi sulla configurazione opencode.

Passo dopo passo

Crea una chiave su /app/keys e copiala: viene mostrata una sola volta.
Esportala: export KUNAVO_API_KEY=sk-kn-...
Aggiungi il blocco provider a opencode.json: quello globale in ~/.config/opencode/opencode.json per tutti i progetti, oppure quello nella radice del progetto per questo solo repository.
Avvia opencode e seleziona il modello dall’elenco; il provider apparirà sotto il nome name che gli hai assegnato.
Per aggiungere un modello in seguito, aggiungi un’altra chiave sotto models: l’ID è quello trasmesso sul protocollo, mentre name è solo un’etichetta.

Verificato rispetto a documentazione dei provider di opencode il 6 settembre 2026. Le impostazioni di terze parti cambiano; se il nome di un campo qui non corrisponde più a quello visualizzato, fa fede quella pagina, non questa.

Verifica prima di eseguire il debug del client

Una sola richiesta stabilisce se il problema riguarda l'endpoint, la chiave o il file di configurazione. Se restituisce JSON, lo stesso base URL e la stessa chiave funzionano in opencode.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

Quale model id inserire nel campo

Ogni modello di testo è raggiungibile come model id: l'elenco aggiornato è GET /v1/models e il catalogo con i prezzi è nella pagina dei modelli. Le tariffe sono in USD per 1M di token, input / output.

ID del modello	Kunavo ingresso / uscita	Dove si inserisce in opencode
`claude-sonnet-5`	$1.40 / $7.00	il modello predefinito per lo sviluppo
`claude-opus-5`	$3.50 / $17.50	modalità di pianificazione, in cui il piano guida tutto ciò che segue
`claude-haiku-4-5`	$0.70 / $3.50	lavoro di sub-agenti e ricerca, in cui il numero di richieste è elevato
`gpt-5-6-sol`	$2.00 / $12.00	usalo con @ai-sdk/openai per mantenere gli elementi di ragionamento durante l’intero scambio

La fatturazione è per token, usando un saldo prepagato senza canone mensile: vedi billing. In presenza di contesto ripetuto, che costituisce la maggior parte di ciò che invia un editor o un client di chat, prompt caching incide sulla spesa più della scelta del modello.

Domande frequenti

Come si aggiunge un provider personalizzato a opencode?

Aggiungi un blocco sotto «provider» in opencode.json specificando un pacchetto npm, un nome visualizzato, options.baseURL, options.apiKey e una mappa models. Usa @ai-sdk/openai-compatible per un endpoint che espone /v1/chat/completions e @ai-sdk/openai per uno che espone /v1/responses. Il provider apparirà quindi nell’elenco dei modelli di opencode con il nome che gli hai assegnato.

Come si mantiene la chiave API fuori da opencode.json?

Usa la sintassi di interpolazione {env:VAR_NAME} in options.apiKey, per esempio "apiKey": "{env:KUNAVO_API_KEY}", ed esporta la variabile nella shell. opencode la risolve quando carica la configurazione, così il file può essere salvato nel repository del progetto configurato senza esporre la chiave.

Qual è la differenza tra @ai-sdk/openai e @ai-sdk/openai-compatible in opencode?

Selezionano endpoint diversi sullo stesso URL di base. @ai-sdk/openai-compatible chiama /chat/completions, implementato da quasi tutti i gateway; @ai-sdk/openai chiama /responses, la più recente interfaccia OpenAI. Scegli il pacchetto effettivamente supportato dal tuo endpoint: usare quello sbagliato restituisce un 404 da un URL di base altrimenti corretto.

Perché opencode esaurisce il contesto prima del previsto?

Perché alla voce del modello manca il blocco limit, quindi opencode lo conteggia usando un valore predefinito anziché la finestra effettiva del modello. Aggiungi "limit": { "context": <window>, "output": <max output> } al modello in opencode.json, usando i valori del catalogo del provider: così l’indicatore del contesto e i punti di compattazione corrispondono alla realtà.