Installazione di goose e configurazione di un Provider personalizzato

goose è un assistente AI generico che viene eseguito sul tuo computer. Oltre al codice, può occuparsi di ricerche, scrittura, automazione e organizzazione dei dati. Puoi usarlo tramite l’applicazione desktop, il terminale o un’interfaccia API; la versione desktop e quella per terminale condividono la stessa configurazione dei modelli. È adatto alle attività di programmazione ripetitive e può collegarsi anche a GitHub, database e file.

Preparazione all’installazione

goose offre due modalità di installazione: Desktop e CLI. Desktop è l’applicazione con interfaccia grafica, mentre CLI è la versione utilizzabile digitando comandi nel terminale. Entrambe condividono la configurazione principale, inclusi Provider e modelli. Un Provider può essere considerato come la configurazione di connessione che indica a goose quale servizio di modelli utilizzare.

Vuoi una finestra

goose Desktop

Scarica lo zip su macOS
Oppure usa brew cask
Su Linux usa il pacchetto di installazione

Solo terminale

goose CLI

download_cli.sh
Oppure Homebrew CLI
Poi goose session

Windows

Scegli prima l'ambiente

Git Bash o MSYS2
Puoi usare anche PowerShell
Se il comando non viene trovato, aggiungilo a PATH

Su macOS puoi usare il download diretto o Homebrew. Per la versione desktop su Linux, usa il pacchetto della distribuzione. Su Windows, verifica prima gli ambienti per terminale indicati.

Prima di iniziare, procurati l’ID del modello presente nell’elenco attuale dei modelli. L’ID del modello è il nome usato dal servizio per identificare uno specifico modello e deve essere copiato per intero.

Installazione e primo avvio

Se vuoi un’interfaccia grafica

Per macOS sono indicate due modalità di installazione:

Scarica l’applicazione dalla pagina di installazione. Sono disponibili le versioni macOS Silicon e macOS Intel. Dopo il download, estrai il file zip ed esegui l’applicazione contenuta al suo interno.
In alternativa, usa Homebrew:

brew install --cask block-goose

Il comando scarica la stessa applicazione e può gestire anche gli aggiornamenti.

Se utilizzi un Apple Mac M3 e dopo l’apertura non compare alcuna finestra, verifica che ~/.config sia leggibile e scrivibile. goose usa questa directory per scrivere i log.

Per la versione desktop di Linux, scarica il pacchetto dalla pagina di installazione. Sono disponibili DEB (Ubuntu/Debian), RPM (RHEL/Fedora) e Flatpak. Su Debian o Ubuntu, scarica il file DEB, apri la directory in cui è stato salvato, esegui sudo dpkg -i (filename).deb, quindi apri goose dal menu delle applicazioni. Sostituisci (filename) con il nome effettivo del file.

Per la versione desktop di Windows, scarica il file dalla pagina di installazione, estrai lo zip ed esegui l’applicazione contenuta al suo interno.

Se ti serve solo il terminale

Su macOS e Linux esegui:

curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash

Se non vuoi eseguire la configurazione interattiva durante l’installazione, aggiungi CONFIGURE=false all’inizio:

curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | CONFIGURE=false bash

Su macOS puoi anche eseguire:

brew install block-goose-cli

Per aggiornare una CLI già installata, usa:

goose update

Su Windows è richiesto uno dei seguenti tre ambienti: Git Bash, incluso in Git for Windows e indicato come opzione consigliata, MSYS2 oppure PowerShell, incluso in Windows 10/11. Con Git Bash e MSYS2 usa lo stesso comando download_cli.sh riportato sopra. Con PowerShell, scarica prima lo script e poi eseguilo:

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/aaif-goose/goose/main/download_cli.ps1" -OutFile "download_cli.ps1"
.\download_cli.ps1

Se viene segnalato che goose non è presente in PATH, segui le indicazioni della pagina di installazione per aggiungere ~/.local/bin o %USERPROFILE%\.local\bin alla configurazione della shell corrente, quindi riapri il terminale. PATH è l’insieme di directory in cui il terminale cerca i programmi. Se la directory non è inclusa, potresti non riuscire ad avviare il programma digitandone direttamente il nome, anche se è già installato.

Al 2026-10-09, la versione della CLI è la 1.54.0. Per impostazione predefinita, lo script di installazione colloca il programma in ~/.local/bin. Puoi modificare questa directory con la variabile d’ambiente GOOSE_BIN_DIR. Dopo la modifica, lo script non aggiorna automaticamente la configurazione della shell e il terminale segnala che la directory non è presente in PATH. Aggiungi la directory a PATH oppure avvia il programma usando il percorso completo.

Al primo utilizzo, goose chiede di configurare un Provider. Puoi saltare i fornitori integrati e aggiungere un Provider personalizzato seguendo la sezione successiva. Nel terminale, apri la directory in cui vuoi lavorare ed esegui:

goose session

Ottenere i parametri di connessione da OmniProxy

Recupera dal tuo OmniProxy l’indirizzo, la chiave e il nome del modello. Nell’esempio per un Provider personalizzato, base_url termina con /v1/chat/completions, quindi anche qui viene usato lo stesso formato:

API URL:  https://your-omniproxy-origin.example/v1/chat/completions
API Key:  <YOUR_OMNIPROXY_API_KEY>
Models:   copia gli ID completi dall'elenco attuale dei modelli di OmniProxy, separandoli con virgole inglesi

Copia per intero il nome del modello dall’elenco attuale di OmniProxy, conservando anche le barre. Al 2026-10-09, i due ID di riferimento presenti nella documentazione dei fornitori sono grok-4.7 per Grok e gpt-6-luna nella documentazione OpenAI. gpt-6-luna supporta Chat Completions; in Chat Completions, le chiamate di funzione sono supportate solo quando reasoning_effort è impostato su none. Non copiare nomi che non compaiono nell’elenco.

Compilazione della configurazione dello strumento

Un Provider personalizzato usa un formato compatibile con OpenAI, Anthropic o Ollama. Un formato compatibile indica che lo strumento invia le richieste seguendo un’interfaccia comune. Per collegare OmniProxy, seleziona OpenAI Compatible.

Versione desktop

Fai clic sul pulsante in alto a sinistra per aprire la barra laterale.
Fai clic su Settings.
Fai clic su Models.
Fai clic su Configure providers.
Fai clic su Add Custom Provider nella parte inferiore della finestra.
In Provider Type seleziona OpenAI Compatible. In Display Name puoi inserire OmniProxy. In API URL inserisci l’indirizzo indicato nella sezione precedente. Se è necessaria una chiave, seleziona l’opzione che richiede un’API Key e inserisci la chiave di OmniProxy. In Available Models inserisci i nomi dei modelli, separandoli con virgole inglesi.
Fai clic su Create Provider.

Attualmente la versione desktop non consente di definire intestazioni di richiesta personalizzate in questa finestra. Se ti servono intestazioni, modifica il file di configurazione dopo aver creato il Provider.

Terminale

Esegui:

goose configure

Seleziona Custom Providers, quindi Add A Custom Provider. In API Type seleziona OpenAI Compatible e segui le richieste per inserire nome, API URL, necessità della chiave, nomi dei modelli e supporto delle risposte in streaming.

Durante la configurazione manuale su Windows, se il portachiavi restituisce un errore, quando viene chiesto se salvare la chiave nel keyring scegli di non salvarla e usa invece una variabile d’ambiente. Quindi esegui nuovamente goose configure. Il portachiavi è un piccolo archivio protetto usato dal sistema per conservare le chiavi.

File di configurazione

Le directory indicate sono:

macOS e Linux: ~/.config/goose/custom_providers/
Windows: %APPDATA%\Block\goose\config\custom_providers\

Puoi creare il file seguendo questo esempio. Sostituisci nome, indirizzo e modelli con i tuoi valori. Conserva la chiave nella variabile d’ambiente indicata da api_key_env e non scrivere la chiave reale nel file:

{
  "name": "omniproxy",
  "engine": "openai",
  "display_name": "OmniProxy",
  "api_key_env": "OMNIPROXY_API_KEY",
  "base_url": "https://your-omniproxy-origin.example/v1/chat/completions",
  "models": [
    { "name": "grok-4.7", "context_limit": 128000 },
    { "name": "gpt-6-luna", "context_limit": 128000 }
  ],
  "supports_streaming": true,
  "requires_auth": true
}

Per context_limit, mantieni un valore numerico come nell’esempio. Il contesto effettivo dipende dal modello e da OmniProxy: non considerare il valore di esempio come il limite ufficiale del modello. Prima dell’uso, esegui:

export OMNIPROXY_API_KEY="<YOUR_OMNIPROXY_API_KEY>"

Dopo essere entrato nella directory di lavoro, esegui:

goose session --provider omniproxy --model grok-4.7

Sostituisci il valore di --model con l’ID completo presente nell’elenco. goose session non dispone del sottocomando start. Puoi specificare --provider e --model anche tramite le variabili d’ambiente GOOSE_PROVIDER e GOOSE_MODEL. Anche quando il gateway non verifica la chiave, OMNIPROXY_API_KEY deve comunque contenere un valore, che può essere una stringa segnaposto usata solo localmente. Al 2026-10-09, con questa configurazione è stato possibile leggere il file.

Finestra

Settings

Settings nella barra laterale
Pagina Models
Add Custom Provider

Terminale

goose configure

Seleziona Custom Providers
Poi seleziona l'aggiunta
Come tipo scegli OpenAI Compatible

File

custom_providers

Su macOS e Linux si trova in ~/.config
Su Windows si trova in APPDATA
Imposta base_url come nell'esempio ufficiale

I tre metodi creano lo stesso tipo di configurazione. Seleziona OpenAI Compatible come tipo di Provider.

Verifica con un’attività reale

Apri una directory contenente un normale file ed esegui goose session come indicato nella sezione precedente. Chiedi a goose di leggere la prima riga del file specificato. Deve restituire il contenuto del file, non limitarsi a indicare che la configurazione è stata salvata.

Per leggere file o eseguire comandi, la sessione richiede l’estensione Developer. L’estensione Developer è il modulo che consente a goose di gestire file e comandi locali. In genere è inclusa nella configurazione predefinita. Se goose risponde di non disporre di strumenti per i file, aggiungi al comando:

--with-builtin developer

Non aggiungere contemporaneamente --no-profile, perché questo parametro disattiva le estensioni predefinite.

Il 2026-10-09, usando goose 1.54.0, è stato possibile leggere la prima riga del file specificato. La prima risposta può richiedere circa un minuto.

Controlla quindi nei registri delle chiamate di OmniProxy l’origine e il nome del modello.

Avvio

Puoi entrare nella sessione

goose session
Il Provider è quello appena aggiunto
Il nome del modello è nell'elenco

Attività

Ha davvero eseguito l'azione

Ad esempio, elenca la directory corrente
Controlla la risposta
Non limitarti a verificare che il salvataggio sia riuscito

Registri

Visibile dal gateway

Usa l'esempio nella documentazione per l'indirizzo
Non scrivere la chiave nel repository
L'ID del modello corrisponde all'elenco

Dopo aver salvato il Provider, verifica la configurazione con una sessione reale.

Errori comuni

Comando goose non trovato: aggiungi la directory di installazione a PATH seguendo la pagina di installazione, quindi riapri il terminale.
Nessuna finestra nella versione desktop su M3: verifica i permessi di lettura e scrittura di ~/.config.
Errore del portachiavi: non salvare la chiave nel keyring e usa invece una variabile d’ambiente.
Il modello non è nell’elenco: nella versione desktop puoi selezionare Use custom model e inserire manualmente il nome del modello. goose configure non consente di inserire un nome di modello personalizzato; per il terminale, usa la versione desktop oppure modifica direttamente GOOSE_MODEL nella configurazione.
Impossibile collegarsi all’indirizzo: verifica che API URL termini con /v1/chat/completions, come nell’esempio, e che OmniProxy sia in esecuzione.
goose segnala di non poter leggere il file: aggiungi l’estensione Developer e non usare --no-profile.
Viene restituito unsupported Responses role: system: in genere l’indirizzo è corretto. Prova un altro ID completo presente nell’elenco dei modelli.

Riferimenti ufficiali

Per l’installazione, consulta Install goose. Per i Provider personalizzati, consulta goose providers. Gli ID dei modelli usati negli esempi sono disponibili nella pagina dei modelli xAI e in GPT-6 Luna.

Sostituisci ogni segnaposto con valori dalla tua configurazione OmniProxy personale. Non pubblicare mai una chiave reale.

Un risultato salvato o HTTP 200 da soli non provano la piena compatibilità con l'Agente. Controlla l'origine e il modello nel registro delle chiamate di OmniProxy.

Fonti ufficiali · goose ↗