Guida all'agente di coding goose: installazione, fonti dei modelli, configurazione API e costi

goose è un agente AI di programmazione open source (Apache-2.0) che può leggere file, modificarli ed eseguire comandi nel terminale o nell'app desktop. Per iniziare bastano tre passaggi: installarlo, scegliere una fonte di modelli (provider) e aprire una sessione di lavoro affidandogli un'attività. È gratuito; il costo deriva dal modello collegato. Questa guida, basata sulla documentazione ufficiale del 1 ottobre 2026, illustra l'installazione, i tre percorsi di pagamento, il collegamento a un endpoint compatibile con OpenAI (inclusa la trappola più comune di /v1) e le operazioni più utilizzate. L'ultima versione è la v1.52.0, pubblicata il 23 settembre 2026.

Prima chiariamo i nomi. Questa pagina parla dell'agente di coding disponibile su goose-docs.ai, il cui repository è aaif-goose/goose, originariamente chiamato block/goose e trasferito nell'aprile 2026 alla Agentic AI Foundation della Linux Foundation. Non è goose.ai: quello è un altro servizio di inferenza gestito e i suoi prezzi non hanno relazione con questo progetto. goose al momento non dispone di un'interfaccia in cinese tradizionale; i nomi dei menu riportati di seguito restano quindi in inglese.

installazione

Ufficialmente sono disponibili una versione desktop (goose Desktop) e una versione a riga di comando (goose CLI); entrambe leggono la stessa configurazione.

# goose Desktop(macOS)
brew install --cask block-goose

# goose CLI（macOS / Linux / Windows 的 Git Bash）
curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash

# 只安裝、先不進入設定
curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | CONFIGURE=false bash

# 或用 Homebrew 裝 CLI
brew install block-goose-cli

Su Windows puoi scaricare la versione desktop dal sito ufficiale; per la CLI è consigliato eseguire la stessa riga di installazione in Git Bash (va bene anche PowerShell). Il nome del pacchetto Homebrew è ancora block-goose: è il risultato del fatto che la ridenominazione non è stata trasferita completamente al pacchetto di installazione e non significa che il progetto sia ancora nelle mani di Block.

Primo avvio: scegli la fonte del modello

Al primo avvio di goose Desktop compare una schermata di benvenuto; la CLI entra automaticamente in modalità di configurazione (per modificarla in seguito puoi eseguire goose configure). La pagina di installazione elenca tre opzioni:

• OpenRouter Login — accedi con un account OpenRouter e configura automaticamente il modello.
• Tetrate Agent Router Service Login — accedi con Tetrate; la documentazione dichiara che la prima autenticazione automatica tramite goose assegna $10 di credito gratuito, sia ai nuovi utenti sia a quelli esistenti.
• Manual Configuration — scegli personalmente il provider e inserisci la chiave. Per collegare un endpoint compatibile con OpenAI (come Kunavo), scegli questa opzione.

Tre percorsi di pagamento: scegli quello giusto prima della configurazione

La descrizione del percorso ACP proviene dalla documentazione dei provider ACP di goose, che ricorda anche che l'ID di sessione ACP è diverso da quello di goose e che i campi di telemetria potrebbero non corrispondere. Se hai già un abbonamento e vuoi soltanto evitare i costi API, inizia da qui.

Collegare un endpoint compatibile con OpenAI: Host URL senza /v1

Questo è il punto in cui la maggior parte delle persone si blocca. goose non accetta un unico base URL completo, ma lo divide in “host” e “percorso”. Secondo la documentazione dei provider, OPENAI_HOST è l'“URL dell'endpoint personalizzato (predefinito api.openai.com)”, mentre OPENAI_BASE_PATH è il “percorso della richiesta aggiunto dopo l'host (predefinito v1/chat/completions)”; quando colleghi un proxy, devi impostare OPENAI_HOST sull'“indirizzo radice del proxy (senza percorso)”. Con Kunavo:

# goose Desktop → Settings → Models → Configure providers → OpenAI
API Key           sk-kn-...
Host URL          https://api.kunavo.com      ← 只寫網域，不加 /v1
Organization ID   （留空）
Project           （留空）

# 或用環境變數（CLI 也讀）
export OPENAI_API_KEY=sk-kn-...
export OPENAI_HOST=https://api.kunavo.com
# OPENAI_BASE_PATH 不要設：預設就是 v1/chat/completions

In goose Desktop si trova in Settings → Models → Configure providers → OpenAI; nella CLI è goose configure → Configure Providers → OpenAI. Organization ID e Project servono per gli account OpenAI proprietari e possono essere lasciati vuoti. Se Host URL è impostato su https://api.kunavo.com/v1, la richiesta diventa /v1/v1/chat/completions; la documentazione stessa afferma che “404 di solito significa che OPENAI_BASE_PATH non è corretto per il tuo proxy”: è un errore di percorso, non di chiave. Al contrario, se compare 401 “No api key passed in”, la chiave non è stata letta, ad esempio perché è stata inserita in config.yaml (goose la ignora).

Un'altra strada più pulita consiste nel renderlo un provider indipendente nell'elenco. goose legge i file di definizione JSON dalla cartella custom_providers; Kunavo fornisce un file generato dal listino prezzi aggiornato, che contiene solo i modelli che supportano le chiamate agli strumenti e indica soltanto il nome della variabile della chiave, senza includere la chiave:

# macOS / Linux:goose 會讀這個資料夾裡所有 JSON
mkdir -p ~/.config/goose/custom_providers
curl -fsSL https://kunavo.com/goose/kunavo.json \
  -o ~/.config/goose/custom_providers/kunavo.json

# 檔案裡只有變數名稱，金鑰另外設定
export KUNAVO_API_KEY=sk-kn-...
goose session start --provider kunavo

Su Windows la cartella è %APPDATA%\Block\goose\config\custom_providers\. Dopo averlo inserito, in goose Desktop Configure providers mostrerà Kunavo; la chiave può essere salvata nel portachiavi di sistema anziché in una variabile d'ambiente. Secondo il codice sorgente di goose, i modelli con ID che iniziano con gpt-5 o gpt-6 usano /v1/responses, mentre gli altri usano /v1/chat/completions; Kunavo offre entrambi. Puoi anche crearlo manualmente: Configure providers → Add Custom Provider, scegli il tipo OpenAI Compatible e inserisci https://api.kunavo.com/v1 come URL API. La pagina di configurazione completa in inglese è la guida all'integrazione di goose.

Una precisazione importante: la configurazione sopra è stata ricavata dalla documentazione e dal codice sorgente di goose; Kunavo non ha eseguito goose sul proprio endpoint: non sono state eseguite sessioni, streaming o scambi di chiamate agli strumenti. Mantieni il percorso che funziona già per te e prova prima con un'attività semplice che legga e scriva file.

Operazioni comuni

• Aprire una sessione:goose session (puoi assegnarle il nome -n 名稱), poi riprenderla con goose session --resume -n 名稱; goose session list elenca la cronologia.
• Cambiare modalità di autorizzazione: all'interno della sessione inserisci /mode e scegli tra auto, approve, chat e smart_approve. Per fare in modo che chieda conferma prima di ogni passaggio, usa approve.
• Scegliere il modello: goose configure non consente di inserire un nome modello personalizzato; per gli ID non presenti nell'elenco, inseriscili in goose Desktop oppure imposta GOOSE_MODEL in config.yaml.
• File di istruzioni del progetto: per impostazione predefinita goose legge .goosehints e AGENTS.md (controllato da CONTEXT_FILE_NAMES); inserisci lì le regole del progetto, così potranno essere trasferite anche passando a un altro agente.
• Non scegliere modelli che non supportano le chiamate agli strumenti: la documentazione afferma che tali modelli “possono solo completare chat” e che anche le estensioni devono essere disattivate.

Quanto costa circa una sessione di lavoro

Di seguito trovi un calcolo illustrativo dei token, non il costo effettivo di un'attività né un limite di fatturazione. Supponiamo che una sessione di lavoro dell'agente invii complessivamente 400.000 token di input non memorizzati nella cache e riceva 25.000 token di output durante più turni (l'agente reinvia il contesto a ogni turno, quindi l'input è particolarmente elevato). I prezzi unitari sono quelli aggiornati per milione di token riportati nel listino prezzi di Kunavo.

Informazioni sulla cache: la documentazione di goose afferma che, quando si usa Claude tramite i provider Anthropic, Amazon Bedrock, Databricks, OpenRouter e LiteLLM, viene aggiunto automaticamente il cache_control di Anthropic. Claude utilizzato tramite il provider OpenAI generico non è incluso nell'elenco, quindi goose non aggiunge questi contrassegni; perciò la tabella precedente presume l'assenza di sconti per la cache, una stima prudenziale. Gli importi del listino Kunavo sono minimi di fatturazione, non massimali: quando l'upstream restituisce un costo, l'addebito è il maggiore tra «importo del listino» e «costo upstream × maggiorazione applicabile».

Pagare da Taiwan

Kunavo è prepagato e addebita in base ai token, senza canone mensile. La ricarica minima è $10; al checkout Stripe sono disponibili carte di credito (Visa, Mastercard, American Express, JCB, UnionPay), Apple Pay, Google Pay e Link. Per i dettagli consulta le informazioni sulla fatturazione; quando sei pronto, puoi creare un account e generare una chiave. Per confrontare altri agenti, consulta goose alternatives e goose vs Claude Code in inglese.

Domande frequenti

Verificato il 1° ottobre 2026: documentazione di goose relativa a installazione, provider, provider ACP, comandi CLI e variabili d'ambiente (ramo main di aaif-goose/goose), oltre alla versione e allo stato di archiviazione del repository tramite l'API di GitHub. Kunavo non ha eseguito goose sui propri endpoint; i prezzi provengono dal listino in tempo reale e tutti gli esempi monetari servono esclusivamente a illustrare l'aritmetica dei token.