Documentazione

goose

goose separa l’endpoint in due parti: un URL Host e un percorso di richiesta che aggiunge autonomamente. Inserisci la sola origine e lascia invariato il percorso: il provider OpenAI integrato potrà così comunicare con Claude e GPT usando un’unica chiave.

Settings → Models → Configure providers → OpenAI: Host URL richiede l'origine senza percorso, perché goose aggiunge autonomamente il percorso della richiesta (v1/chat/completions).

Configura i provider → OpenAI oppure l'ambiente

# goose Desktop → Settings → Models → Configure providers → OpenAI
API Key           sk-kn-...
Host URL          https://api.kunavo.com
Organization ID   (leave blank)
Project           (leave blank)

# …or as environment variables, which goose CLI reads too:
OPENAI_API_KEY=sk-kn-...
OPENAI_HOST=https://api.kunavo.com

# OPENAI_BASE_PATH is left unset on purpose. Its default is
# v1/chat/completions, which is the path Kunavo serves — that default is
# exactly why Host URL above carries no /v1.

L’URL Host non deve includere /v1. goose documenta OPENAI_BASE_PATH come «percorso di richiesta aggiunto all’host (il valore predefinito è v1/chat/completions)» e indica agli utenti di proxy di impostare OPENAI_HOST sulla «radice del proxy (senza percorso finale)». Questa combinazione chiarisce come configurarlo: inserisci il campo dell’origine e il /v1 viene aggiunto dal percorso predefinito. Inserire https://api.kunavo.com/v1 richiede /v1/v1/chat/completions e la stessa pagina specifica che un 404 indica un percorso errato, non una chiave errata.

Questa configurazione è stata ricavata dalla documentazione ufficiale di goose nella data indicata qui sotto. Kunavo non ha eseguito goose sul proprio endpoint: né una sessione, né un turno in streaming, né uno scambio completo con strumenti. Una pagina di configurazione pubblicata non equivale a un test e queste informazioni non vanno interpretate come tali. La curl qui sotto è la parte che puoi verificare in dieci secondi; il comportamento del client dipende da te e goose.

Kunavo non fornisce modelli per embedding, sintesi vocale o trascrizione vocale, quindi questo endpoint risponde alle richieste di completamento chat e a nient’altro. Qualsiasi parte della configurazione di goose che trascrive audio o crea un indice vettoriale continua a usare la chiave del provider già configurato: indirizzare qui il provider OpenAI non sposta quelle chiamate.

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 goose.

Passo dopo passo

Crea una chiave su /app/keys e copiala: viene mostrata una sola volta.
In goose Desktop: barra laterale → Impostazioni → Modelli → Configura provider → OpenAI. Nella CLI: goose configure → Configura provider → OpenAI.
Compila Chiave API e URL Host. Lascia vuoti ID organizzazione e Progetto: goose li documenta per il monitoraggio dell’utilizzo e la gestione delle risorse negli account OpenAI, ma Kunavo non ha campi equivalenti da inserire. Fai clic su Invia.
Scegli il modello. La nota di goose specifica chiaramente che goose configure «non supporta l’inserimento di nomi di modelli personalizzati»: se l’ID desiderato non compare nell’elenco restituito, inseriscilo in goose Desktop oppure imposta GOOSE_MODEL in config.yaml, che ha la precedenza sul file per quel processo.
Avvia una sessione e assegnale un’attività che coinvolga un file. goose si affida alle chiamate agli strumenti per quasi tutte le operazioni. La pagina del provider avverte che un modello senza supporto per le chiamate agli strumenti «può eseguire solo completamenti chat» e che, in tal caso, le estensioni devono essere disattivate. Pertanto, una prima esecuzione che legge e modifica qualcosa dà più informazioni di un semplice saluto.

Verificato rispetto a la pagina di goose Configura provider LLM il 29 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 goose.

# 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 goose
`claude-sonnet-5`	$1.40 / $7.00	il modello di lavoro predefinito per le sessioni che modificano file
`claude-opus-5`	$3.50 / $17.50	pianificare una modifica che sarebbe costosa se andasse male
`claude-haiku-4-5`	$0.70 / $3.50	turni economici: triage, riepiloghi, il ciclo che gira tutto il giorno
`gpt-5-6-sol`	$2.00 / $12.00	un secondo parere da un’altra famiglia, con la stessa chiave e lo stesso URL Host

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.

L’altra opzione: il file provider di Kunavo

goose carica anche definizioni di provider da file JSON nella directory custom_providers. Un provider aggiunto in questo modo compare con una voce dedicata nel selettore, una chiave propria e un elenco di modelli salvato, anziché sovraccaricare la voce chiamata OpenAI. Kunavo ne pubblica uno su kunavo.com/goose/kunavo.json. Il file viene generato dal catalogo attivo, quindi l’elenco comprende i modelli forniti oggi da Kunavo e specifica il nome della variabile della chiave, mai la chiave stessa:

terminal

# macOS / Linux — goose reads every JSON file in this directory
mkdir -p ~/.config/goose/custom_providers
curl -fsSL https://kunavo.com/goose/kunavo.json \
  -o ~/.config/goose/custom_providers/kunavo.json

# The file names the variable; the key itself never goes in the file
export KUNAVO_API_KEY=sk-kn-...
goose session start --provider kunavo

Su Windows la directory è %APPDATA%\Block\goose\config\custom_providers\. In goose Desktop, il provider compare quindi in Configura provider come Kunavo, dove la chiave può essere salvata nel portachiavi invece che nell’ambiente.

Endpoint. Il file imposta base_url su https://api.kunavo.com/v1. La documentazione di goose non specifica se questo campo richieda la base /v1 o l’intero /v1/chat/completions mostrato nell’esempio; il codice sorgente chiarisce che derive_base_path li trasforma entrambi nello stesso percorso v1/chat/completions.
Gli ID GPT usano l’API Responses. goose invia gli ID modello che iniziano con gpt-5 o gpt-6 a /v1/responses, mentre tutti gli altri vengono inviati a /v1/chat/completions. Kunavo supporta entrambi, quindi gli ID Claude e GPT nel file funzionano con un’unica chiave.
Sono elencati solo i modelli che supportano le chiamate agli strumenti. goose si affida agli strumenti in quasi tutti i turni, quindi i modelli per immagini, video e audio non sono inclusi nel file, anche se la stessa chiave consente di usarli.

Vale la stessa precisazione del resto della pagina: queste informazioni provengono dalla documentazione e dal codice sorgente di goose; la configurazione non è stata eseguita. Preferisci configurare il provider manualmente? Configura provider → Aggiungi provider personalizzato richiede gli stessi dati: tipo OpenAI Compatible, URL API https://api.kunavo.com/v1, la tua chiave sk-kn- e un elenco di modelli separati da virgole.

Domande frequenti

Come indirizzo goose a un’API personalizzata compatibile con OpenAI?

Usa il provider OpenAI integrato e indicagli un host. In goose Desktop si configura da Impostazioni → Modelli → Configura provider → OpenAI, dove i campi sono Chiave API, URL Host, ID organizzazione e Progetto; nella CLI si usa `goose configure` → Configura provider → OpenAI, che richiede gli stessi valori. Le variabili d’ambiente corrispondenti sono OPENAI_API_KEY e OPENAI_HOST. Se ti servono più endpoint contemporaneamente, il flusso Aggiungi provider personalizzato di goose assegna a ciascuno una voce dedicata nell’elenco dei provider.

L’URL Host di goose deve terminare con /v1?

No: aggiungerlo interrompe la richiesta. goose documenta OPENAI_BASE_PATH come il percorso di richiesta aggiunto all’host, con valore predefinito v1/chat/completions, e indica agli utenti di proxy di impostare OPENAI_HOST sulla radice del proxy senza un percorso finale. Pertanto, il campo deve contenere la sola origine — https://api.kunavo.com — e /v1 viene aggiunto dal percorso predefinito. Se l’host termina con /v1, la richiesta diventa /v1/v1/chat/completions e restituisce 404 invece di un errore di autenticazione.

Perché goose restituisce 404 dopo che imposto un host personalizzato?

Secondo la documentazione di goose, un 404 di solito indica che il percorso base non è corretto per quell’endpoint: la maggior parte dei proxy serve v1/chat/completions, alcuni servono chat/completions senza v1 e il valore impostato deve corrispondere. Kunavo serve v1/chat/completions, il valore predefinito di goose; quindi, se Kunavo restituisce 404, spesso significa che hai inserito /v1 anche nell’host e il percorso è raddoppiato. Un 401 che indica che non è stata fornita alcuna chiave API è un problema diverso: goose documenta che una chiave inserita in config.yaml viene ignorata.

goose può usare modelli Claude tramite un endpoint compatibile con OpenAI?

Sì. Il tipo di provider indica un protocollo di comunicazione, non un fornitore: goose invia all’host configurato una richiesta di completamento chat nel formato OpenAI e inoltra direttamente l’ID del modello, quindi un ID di Claude viene risolto da quell’endpoint e non all’interno di goose. Tieni presente che goose fa ampio uso delle chiamate agli strumenti e la pagina del provider specifica che un modello senza supporto per queste chiamate può eseguire solo completamenti chat, con le estensioni disattivate; scegli quindi ID che supportano gli strumenti.

Kunavo ha testato questa configurazione?

No. È stata verificata la documentazione di goose (21 e 29 settembre 2026), da cui sono ripresi i nomi e l’ordine dei campi e la regola host più percorso, e, per il file del provider, il codice sorgente dei provider di goose (29 settembre). Kunavo non ha eseguito una sessione goose sul proprio endpoint e non garantisce il comportamento di streaming, gli scambi con strumenti o il comportamento delle estensioni in questo client. L’unica cosa che puoi verificare separatamente è se endpoint e chiave funzionano: il comando curl in questa pagina lo consente.

Esiste un file provider Kunavo già pronto per goose?

Sì: https://kunavo.com/goose/kunavo.json. Salvalo nella directory custom_providers di goose (~/.config/goose/custom_providers/ su macOS e Linux, %APPDATA%\Block\goose\config\custom_providers\ su Windows), imposta KUNAVO_API_KEY e Kunavo apparirà nell’elenco dei provider con gli ID dei modelli già compilati. Il file viene generato dal catalogo attivo, quindi elenca solo i modelli attualmente forniti da Kunavo e non contiene alcuna chiave.