Installation de goose et configuration d’un Provider personnalisé

goose est un assistant IA polyvalent qui s’exécute sur votre ordinateur. En plus du code, il peut effectuer des recherches, rédiger, automatiser des tâches et organiser des données. Vous pouvez l’utiliser depuis l’application de bureau, le terminal ou une interface de programmation. Les versions Desktop et CLI partagent la même configuration de modèles. Il convient aux tâches de programmation répétitives et peut également se connecter à GitHub, à des bases de données et à des fichiers.

Préparation avant l’installation

goose propose deux modes d’installation : Desktop et CLI. Desktop est l’application de bureau avec une interface graphique, tandis que CLI s’utilise en saisissant des commandes dans un terminal. Les deux versions partagent la configuration principale, notamment le Provider et les modèles. Un Provider peut être considéré comme la configuration de connexion qui indique à goose quel service de modèles utiliser.

Pour une interface graphique

goose Desktop

Sous macOS, télécharger le zip
Ou utiliser brew cask
Sous Linux, utiliser le paquet d’installation

Pour le terminal uniquement

goose CLI

download_cli.sh
Ou Homebrew CLI
Puis exécuter goose session

Windows

Choisir d’abord l’environnement

Git Bash ou MSYS2
PowerShell peut aussi être utilisé
Ajouter le répertoire à PATH si la commande est introuvable

Sous macOS, vous pouvez utiliser un téléchargement ou Homebrew. Sous Linux, la version de bureau utilise le paquet correspondant à la distribution. Sous Windows, vérifiez d’abord les environnements de terminal indiqués.

Avant de commencer, préparez l’ID du modèle figurant dans la liste actuelle des modèles. L’ID du modèle est le nom utilisé par le service pour identifier un modèle précis. Vous devez le copier intégralement lors de la configuration.

Installation et premier lancement

Pour utiliser une interface graphique

Deux méthodes d’installation sont proposées sous macOS :

Téléchargez l’application depuis la page d’installation. Cette page propose des versions macOS Silicon et macOS Intel. Après le téléchargement, décompressez le fichier zip, puis lancez l’application qu’il contient.
Vous pouvez aussi utiliser Homebrew :

brew install --cask block-goose

Cette commande télécharge la même application et peut également gérer les mises à jour.

Sur un Apple Mac M3, si aucune fenêtre n’apparaît après le lancement, vérifiez que ~/.config est accessible en lecture et en écriture. goose utilise ce répertoire pour enregistrer ses journaux.

Sous Linux, téléchargez la version de bureau depuis la page d’installation. Les formats proposés sont DEB pour Ubuntu/Debian, RPM pour RHEL/Fedora et Flatpak. Sous Debian ou Ubuntu, procédez comme suit : téléchargez le fichier DEB, ouvrez le répertoire dans lequel il est enregistré, exécutez sudo dpkg -i (filename).deb, puis ouvrez goose depuis le menu des applications. Remplacez (filename) par le véritable nom du fichier.

Sous Windows, téléchargez la version de bureau depuis la page d’installation, décompressez le fichier zip, puis lancez l’application qu’il contient.

Pour utiliser uniquement le terminal

Sous macOS et Linux, exécutez :

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

Pour éviter la configuration interactive pendant l’installation, ajoutez CONFIGURE=false au début :

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

Sous macOS, vous pouvez aussi exécuter :

brew install block-goose-cli

Pour mettre à jour une installation existante de la CLI, utilisez :

goose update

Sous Windows, l’un des trois environnements suivants est requis : Git Bash, fourni avec Git for Windows et indiqué comme recommandé, MSYS2, ou PowerShell inclus avec Windows 10/11. Dans Git Bash et MSYS2, utilisez la même commande download_cli.sh que ci-dessus. Dans PowerShell, téléchargez d’abord le script, puis exécutez-le :

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

Si un message indique que goose ne figure pas dans le PATH, ajoutez ~/.local/bin ou %USERPROFILE%\.local\bin à la configuration du shell actuel, comme indiqué sur la page d’installation, puis rouvrez le terminal. Le PATH est un ensemble de répertoires dans lesquels le terminal recherche les programmes. Si le répertoire n’y figure pas, un programme déjà installé peut ne pas pouvoir être lancé directement en saisissant son nom.

Au 2026-10-09, la version de la CLI est la 1.54.0. Par défaut, le script d’installation place le programme dans ~/.local/bin. La variable d’environnement GOOSE_BIN_DIR permet de modifier ce répertoire. Si vous le changez, le script ne mettra pas automatiquement à jour la configuration du shell et le terminal indiquera que ce répertoire ne figure pas dans le PATH. Ajoutez-le au PATH ou lancez le programme avec son chemin complet.

Lors de la première utilisation, goose vous demande de configurer un Provider. Vous pouvez ignorer les fournisseurs intégrés et ajouter un Provider personnalisé comme décrit dans la section suivante. Dans le terminal, ouvrez le répertoire dans lequel vous souhaitez travailler, puis exécutez :

goose session

Obtention des paramètres de connexion depuis OmniProxy

Préparez l’adresse, la clé et le nom du modèle depuis votre propre OmniProxy. Dans l’exemple de Provider personnalisé, base_url se termine par /v1/chat/completions. Utilisez donc le même format ici :

API URL:  https://your-omniproxy-origin.example/v1/chat/completions
API Key:  <YOUR_OMNIPROXY_API_KEY>
Models:   copiez les ID complets depuis la liste actuelle des modèles OmniProxy et séparez-les par des virgules anglaises

Copiez le nom complet du modèle depuis la liste actuelle d’OmniProxy, en conservant également les barres obliques. Au 2026-10-09, les deux ID de référence figurant dans la documentation des fournisseurs sont grok-4.7 pour Grok et gpt-6-luna dans la documentation OpenAI. gpt-6-luna prend en charge Chat Completions. Dans Chat Completions, l’appel de fonctions n’est pris en charge que lorsque reasoning_effort vaut none. Ne recopiez pas un nom qui ne figure pas dans la liste.

Saisie de la configuration dans l’outil

Un Provider personnalisé utilise un format compatible avec OpenAI, Anthropic ou Ollama. Un format compatible signifie que l’outil envoie ses requêtes conformément à une interface commune donnée. Pour connecter OmniProxy, choisissez OpenAI Compatible.

Version de bureau

Cliquez sur le bouton en haut à gauche pour ouvrir la barre latérale.
Cliquez sur Settings.
Cliquez sur Models.
Cliquez sur Configure providers.
Cliquez sur Add Custom Provider en bas de la fenêtre.
Pour Provider Type, choisissez OpenAI Compatible. Vous pouvez saisir OmniProxy dans Display Name. Dans API URL, saisissez l’adresse indiquée dans la section précédente. Si une clé est requise, cochez l’option exigeant une API Key, puis saisissez la clé OmniProxy. Dans Available Models, saisissez les noms des modèles en les séparant par des virgules anglaises.
Cliquez sur Create Provider.

La version de bureau ne permet actuellement pas de définir des en-têtes de requête personnalisés dans cette fenêtre. Si des en-têtes sont nécessaires, modifiez le fichier de configuration après avoir créé le Provider.

Terminal

Exécutez :

goose configure

Choisissez Custom Providers, puis Add A Custom Provider. Pour API Type, choisissez OpenAI Compatible, puis suivez les invites pour saisir le nom, l’API URL, indiquer si une clé est requise, renseigner les noms des modèles et préciser si les réponses en streaming sont prises en charge.

Sous Windows, si le trousseau de clés renvoie une erreur pendant la configuration manuelle, choisissez de ne pas enregistrer la clé dans le keyring lorsque l’outil vous le demande, puis utilisez une variable d’environnement. Relancez ensuite goose configure. Le trousseau de clés est un petit espace de stockage sécurisé utilisé par le système pour conserver les clés.

Fichier de configuration

Les répertoires indiqués sont les suivants :

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

Vous pouvez créer le fichier à partir de l’exemple fourni. Remplacez le nom, l’adresse et les modèles par vos propres valeurs. Stockez la clé dans la variable d’environnement indiquée par api_key_env et n’inscrivez pas la véritable clé dans le fichier :

{
  "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
}

Pour context_limit, conservez une valeur numérique comme dans l’exemple. La taille réelle du contexte dépend du modèle et d’OmniProxy. Ne considérez pas la valeur de cet exemple comme la limite officielle du modèle. Avant l’utilisation, exécutez :

export OMNIPROXY_API_KEY="<YOUR_OMNIPROXY_API_KEY>"

Après avoir ouvert le répertoire de travail, exécutez :

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

Remplacez la valeur de --model par l’ID complet figurant dans la liste. goose session ne possède pas de sous-commande start. --provider et --model peuvent également être définis avec les variables d’environnement GOOSE_PROVIDER et GOOSE_MODEL. Même si la passerelle ne vérifie pas la clé, OMNIPROXY_API_KEY doit toujours contenir une valeur. Il peut s’agir d’une chaîne de substitution utilisée uniquement sur la machine locale. Au 2026-10-09, cette configuration a permis de lire le fichier.

Interface

Paramètres

Paramètres dans la barre latérale
Page Modèles
Ajouter un fournisseur personnalisé

Terminal

goose configure

Sélectionner Fournisseurs personnalisés
Puis sélectionner l’ajout
Choisir le type Compatible avec OpenAI

Fichier

custom_providers

Sous macOS et Linux, dans ~/.config
Sous Windows, dans APPDATA
Définir base_url selon l’exemple officiel

Ces trois méthodes écrivent le même type de configuration. Pour le type de Provider, choisissez OpenAI Compatible.

Vérification avec une tâche réelle

Ouvrez un répertoire contenant un fichier ordinaire, puis exécutez la commande goose session de la section précédente. Demandez à goose de lire la première ligne du fichier que vous indiquez. Il doit afficher le contenu du fichier, et pas seulement confirmer que la configuration a été enregistrée.

Pour lire des fichiers ou exécuter des commandes, la session nécessite l’extension Developer. Cette extension peut être considérée comme un module d’outils qui permet à goose de traiter les fichiers et les commandes locales. Elle est généralement incluse dans la configuration par défaut. Si goose répond qu’il ne dispose pas d’outils pour les fichiers, ajoutez à la commande :

--with-builtin developer

N’ajoutez pas simultanément --no-profile, car cette option désactive les extensions par défaut.

Le 2026-10-09, goose 1.54.0 a lu la première ligne du fichier indiqué. La première réponse peut prendre environ une minute.

Vérifiez ensuite la source et le nom du modèle dans l’historique des appels d’OmniProxy.

Démarrage

La session s’ouvre

goose session
Le fournisseur est celui qui vient d’être ajouté
Le nom du modèle figure dans la liste

Tâche

Il a réellement effectué l’action

Par exemple, lister le répertoire actuel
Vérifier sa réponse
Ne pas se contenter de vérifier que l’enregistrement a réussi

Journaux

La passerelle reçoit l’appel

Utiliser l’adresse de l’exemple de la documentation
Ne pas enregistrer la clé dans le dépôt
L’ID du modèle correspond à celui de la liste

Après avoir enregistré le Provider, vérifiez également la configuration avec une véritable session.

Erreurs courantes

Commande goose introuvable : ajoutez le répertoire d’installation au PATH comme indiqué sur la page d’installation, puis rouvrez le terminal.
Aucune fenêtre avec la version de bureau sur un M3 : vérifiez les autorisations de lecture et d’écriture de ~/.config.
Échec du trousseau de clés : n’enregistrez pas la clé dans le keyring et utilisez une variable d’environnement.
Le modèle ne figure pas dans la liste : dans la version de bureau, sélectionnez Use custom model pour saisir manuellement le nom du modèle. goose configure ne permet pas de saisir un nom de modèle personnalisé. Pour le terminal, utilisez la version de bureau ou modifiez directement GOOSE_MODEL dans la configuration.
Connexion à l’adresse impossible : vérifiez que l’API URL se termine par /v1/chat/completions, comme dans l’exemple, et qu’OmniProxy est en cours d’exécution.
goose indique qu’il ne peut pas lire les fichiers : ajoutez l’extension Developer et n’utilisez pas --no-profile.
L’erreur unsupported Responses role: system est renvoyée : l’adresse est généralement correcte. Utilisez un autre ID complet figurant dans la liste des modèles.

Références officielles

Pour l’installation, consultez Install goose. Pour les Providers personnalisés, consultez goose providers. Les ID de modèles utilisés dans les exemples sont présentés sur la page des modèles xAI et la page GPT-6 Luna.

Remplacez chaque espace réservé par des valeurs de votre propre configuration OmniProxy. Ne publiez jamais une vraie clé.

Un résultat sauvegardé ou un HTTP 200 seul ne prouve pas une compatibilité complète de l'Agent. Vérifiez la source et le modèle dans l'enregistrement d'appel d'OmniProxy.

Sources officielles · goose ↗