Goose + JoinGonka Gateway : votre propre fournisseur et clé dans le trousseau

Étape 1 : installer Goose. Les méthodes officielles pour le CLI, d'après la documentation du projet :

# macOS and Linux: the script puts the binary in ~/.local/bin
curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | CONFIGURE=false bash

# macOS, Homebrew
brew install block-goose-cli

La variable CONFIGURE=false désactive l'assistant goose configure que le script lance sinon immédiatement après l'installation : c'est l'installateur qui configurera le fournisseur. Si le répertoire ~/.local/bin n'est pas dans le PATH, le script vous le dira. Pour Windows, le même dépôt contient un script download_cli.ps1, et l'application de bureau se télécharge depuis la page de documentation ; elle et le CLI lisent les mêmes réglages, donc tout ce qui suit vaut pour les deux. Vérification — goose --version.

Étape 2 : obtenir une clé. Inscrivez-vous sur gate.joingonka.ai/register, confirmez votre adresse et créez une clé avec le préfixe jg- dans la section « Clés API ». Une seule clé et un seul solde valent pour tous les modèles du réseau.

Étape 3 : lancer l'installateur.

npx @joingonka/setup --tool goose

L'installateur demandera la clé — elle n'est pas transmise en argument de ligne de commande, pour ne pas rester dans l'historique du shell — et fera ce qui suit :

• créer le fichier de fournisseur custom_providers/custom_joingonka.json avec l'adresse de la passerelle et les trois modèles du réseau avec leurs vraies fenêtres de contexte, en permissions 600. Les noms custom_joingonka et CUSTOM_JOINGONKA_API_KEY sont ceux que Goose dérive lui-même du nom « JoinGonka », donc la clé saisie dans l'assistant ira au bon endroit ;
• faire de JoinGonka le fournisseur par défaut avec le modèle DeepSeek V4 Flash — mais uniquement si aucun fournisseur n'est encore choisi, ou si le nôtre est choisi avec un modèle vide ou disparu du réseau. Il ne touche pas à un autre choix et affiche la commande pour essayer : goose session --provider custom_joingonka --model … ;
• placer la clé dans secrets.yaml, uniquement si le stockage des secrets de Goose est bien basé sur un fichier ; sinon il dira clairement qu'il reste une étape — détails dans la section sur la clé ;
• faire des copies de sauvegarde des fichiers modifiés et, à la fin, envoyer une requête réelle à la passerelle pour vérifier immédiatement la clé, l'adresse et le modèle.

L'installateur trouve le répertoire de configuration comme Goose lui-même : ~/.config/goose sous Linux et macOS, %APPDATA%\Block\goose\config sous Windows, <root>/config si GOOSE_PATH_ROOT est défini. Un autre modèle se choisit avec le flag --model et les raccourcis deepseek, glm ou minimax ; un modèle explicitement indiqué est toujours écrit. Le mode sans question récupère la clé depuis la variable d'environnement :

JOINGONKA_API_KEY=jg-your-key npx @joingonka/setup --tool goose --model glm --non-interactive

Tout ce que fait l'installateur peut être effectué manuellement. Le fournisseur est un fichier JSON distinct ~/.config/goose/custom_providers/custom_joingonka.json ; le nom du fichier correspond au champ name :

{
  "name": "custom_joingonka",
  "engine": "openai",
  "display_name": "JoinGonka",
  "description": "JoinGonka Gateway — Gonka AI inference (OpenAI-compatible)",
  "api_key_env": "CUSTOM_JOINGONKA_API_KEY",
  "base_url": "https://gate.joingonka.ai/v1/chat/completions",
  "models": [
    { "name": "deepseek-ai/DeepSeek-V4-Flash-0731", "context_limit": 380000 },
    { "name": "zai-org/GLM-5.3-Flash", "context_limit": 390000 },
    { "name": "MiniMaxAI/MiniMax-M2.7", "context_limit": 200000 }
  ],
  "supports_streaming": true,
  "requires_auth": true
}

Il n'y a pas de limite de réponse distincte prévue pour l'entrée du modèle dans Goose. Pour ces modèles, il ne transmet pas de limite dans la requête du tout — nous l'avons vérifié via son journal de requêtes — et en mode streaming, la passerelle limite elle-même la réponse au plafond du modèle : 32 768 tokens pour DeepSeek V4 Flash, 8192 pour GLM-5.3 Flash et MiniMax M2.7. Il n'est pas nécessaire de définir la variable globale GOOSE_MAX_TOKENS pour cela : elle est unique pour tous les fournisseurs à la fois.

Goose lit le fichier de fournisseur avec un analyseur JSON strict : un commentaire ou une virgule traînante, et le fournisseur disparaît de la liste. Vous pouvez également le créer via l'assistant (goose configure → Custom Providers), mais l'assistant ne demande pas la fenêtre de contexte — vous devrez l'ajouter manuellement.

Le fournisseur et le modèle par défaut sont définis dans ~/.config/goose/config.yaml. C'est ainsi que Goose les enregistre lui-même :

active_provider: custom_joingonka
providers:
  custom_joingonka:
    enabled: true
    model: deepseek-ai/DeepSeek-V4-Flash-0731
    configured: true

L'ancienne disposition — clés plates GOOSE_PROVIDER et GOOSE_MODEL à la racine du fichier — fonctionne également : Goose la lit et la convertit lui-même vers la nouvelle lors de la première sauvegarde des paramètres, comme c'est le cas après goose configure. L'installateur sur un fichier vide écrit précisément des clés plates — n'importe quelle version les comprend. Les variables d'environnement du même nom sont prioritaires sur le fichier : si elles sont définies dans le shell, le choix du config.yaml ne prendra pas effet, et l'installateur vous en avertira.

Dans le fichier du fournisseur chez Goose, il n'y a que le nom du secret — CUSTOM_JOINGONKA_API_KEY. Goose cherche la valeur dans l'ordre suivant : dans la variable d'environnement portant ce nom, puis dans le stockage système de secrets (keyring, sur macOS — Keychain), puis dans le fichier secrets.yaml à côté de la config. Les secrets atterrissent dans ce fichier lorsque le stockage de Goose est de type fichier, et ils y restent en clair, avec les droits 600. Et dans config.yaml, Goose ne cherche pas du tout les clés (documentation).

Le stockage devient fichier si le keyring est désactivé — via la variable GOOSE_DISABLE_KEYRING avec n'importe quelle valeur ou la ligne GOOSE_DISABLE_KEYRING: true dans config.yaml — ou s'il est indisponible : serveur sans session graphique, conteneur, CI. Dans le second cas, Goose écrit dans le journal « Keyring unavailable. Using file storage for secrets. » et bascule lui-même sur le fichier — c'est exactement ce que nous avons observé dans le conteneur. L'installateur ne sait pas écrire dans le keyring, et ne le désactivera pas à votre place : Goose cesserait de voir les secrets qui y sont déjà stockés. D'où les scénarios :

L'étape restante. Lancez goose configure et répondez aux questions de l'assistant — voici comment elles se présentaient lors de notre exécution :

• What would you like to configure? → Configure Providers ;
• Which model provider should we use? → JoinGonka (chez nous, il était en premier) ;
• Would you like to set CUSTOM_JOINGONKA_API_KEY? (optional) → Yes, puis à Enter value for CUSTOM_JOINGONKA_API_KEY, collez la clé — des carrés apparaîtront à la place des caractères. La clé est enregistrée immédiatement ;
• Would you like to configure advanced settings? → No ;
• Select a model — Goose récupère la liste auprès de la passerelle : MiniMaxAI/MiniMax-M2.7, deepseek-ai/DeepSeek-V4-Flash-0731, zai-org/GLM-5.3-Flash. Le curseur est sur la première ligne — pour conserver le modèle choisi par l'installateur, sélectionnez DeepSeek V4 Flash avec les flèches. Après une requête de vérification, l'assistant se terminera par « Configuration saved successfully ».

Dans Goose Desktop, le chemin est le suivant : Settings → Models → Configure providers → JoinGonka → clé → Submit. Vous ne voulez pas coller la clé à la main — placez-la dans une variable et lancez l'assistant depuis le même shell : Goose affichera « CUSTOM_JOINGONKA_API_KEY is set via environment variable » et proposera d'enregistrer la valeur :

read -s CUSTOM_JOINGONKA_API_KEY && export CUSTOM_JOINGONKA_API_KEY
goose configure

Et pour une seule exécution, la clé peut être transmise sans être enregistrée du tout : CUSTOM_JOINGONKA_API_KEY=jg-your-key goose session, dans PowerShell — $env:CUSTOM_JOINGONKA_API_KEY = "jg-your-key"; goose session. La variable d'environnement prime sur la valeur enregistrée, mais ne vit que jusqu'à la fermeture du shell.

Commencez par vérifier les paramètres que Goose voit réellement :

goose info -v

Dans le bloc « goose Configuration », vous devez retrouver les lignes GOOSE_PROVIDER: custom_joingonka et GOOSE_MODEL avec l'identifiant du modèle. Ensuite, faites un test ponctuel sans session interactive : placez dans un répertoire vide un fichier contenant un bug évident et demandez-lui de le trouver.

goose run --no-session -t "Read calc.py and tell me in one sentence whether it has a bug."

L'option --no-session n'enregistre pas l'exécution dans l'historique. Un en-tête du type ● new session · custom_joingonka deepseek-ai/DeepSeek-V4-Flash-0731 apparaîtra, suivi de l'appel d'outil — ▸ shell avec la commande cat calc.py — puis de la réponse indiquant le bug détecté. Pour imposer un autre modèle le temps d'une exécution, utilisez --model : zai-org/GLM-5.3-Flash ou MiniMaxAI/MiniMax-M2.7. Lors de notre test du 23 septembre 2026, les trois modèles du réseau ont bouclé le cycle « requête → outil → résultat → réponse ». Par défaut, le CLI Goose masque le raisonnement des modèles — pour l'afficher, utilisez la variable GOOSE_CLI_SHOW_THINKING=1 lorsque la sortie s'affiche dans le terminal. Côté passerelle, la requête est visible dans votre espace client : section « Utilisation », avec le détail « Par modèles » et « Par clés ».

En cas de problème, le diagnostic se lit généralement directement dans le message :

Un agent consomme des jetons différemment d'un chat. Dès la configuration standard, Goose envoie au modèle les descriptions de dix-huit outils intégrés, et lors de notre test, chaque tour entraînait environ 4,6 mille jetons d'entrée avant même votre question. La tâche « lire un fichier et trouver une erreur » a pris deux à trois tours et 10 à 15 mille jetons, presque entièrement en entrée ; Goose effectue lui-même une requête courte supplémentaire pour inventer un nom à la session. Les extensions inutiles peuvent être désactivées dans goose configure → Toggle Extensions — c'est le moyen le plus simple de réduire l'entrée.

Via le JoinGonka Gateway, les jetons coûtent $0.0069 par million en entrée et $0.021 par million en sortie — le prix est identique pour tous les modèles du réseau et est récupéré sur cette page à partir d'une source en temps réel.

Les estimations dans la colonne de droite sont basées sur les prix de septembre 2026. À titre de comparaison — comment payer pour des modèles dans Goose en général :

La consommation exacte et le solde restant sont consultables dans le tableau de bord, sections « Utilisation » et « Facturation ». Pourquoi DeepSeek V4 Flash est configuré par défaut — avec le plus grand plafond de réponse du réseau —, est détaillé dans l'aperçu du modèle.

Mode de confirmation. Par défaut, Goose fonctionne en mode auto — totalement autonome : il modifie et supprime les fichiers, lance des commandes et utilise des extensions sans rien demander. Sur votre propre projet, c'est pratique ; sur du code qui ne vous appartient pas, mieux vaut durcir le mode :

# inside a session
/mode smart_approve

# permanently, as a line in config.yaml
GOOSE_MODE: smart_approve

C'est une propriété de Goose lui-même, indépendante du fournisseur du modèle.

Changer de modèle. En session — la commande /model avec l'identifiant, par exemple /model zai-org/GLM-5.3-Flash ; pour une exécution — l'option --model de goose run et goose session ; définitivement — goose configure ou la ligne model dans config.yaml. Le fournisseur, lui, reste le même. GLM-5.3 Flash, qui raisonne, est excellent pour la logique embrouillée, mais sa réponse plafonne à 8192 tokens, dont une partie part dans le raisonnement — détails dans la présentation du modèle.

Exécutions sans surveillance. goose run convient aux scripts et à la CI : l'option -q ne laisse dans la sortie que la réponse du modèle, --output-format json renvoie un résultat exploitable. Les garde-fous --max-turns (combien de tours l'agent effectue sans intervention humaine) et --max-tool-repetitions (combien de fois d'affilée un même outil peut être appelé avec les mêmes arguments) protègent contre les boucles.

Confidentialité. Les statistiques d'usage anonymes de Goose sont désactivées par défaut (GOOSE_TELEMETRY_ENABLED). La passerelle ne conserve pas le contenu des prompts ni des réponses — seuls des agrégats de consommation restent dans les statistiques.