OpenHands + JoinGonka Gateway : agent sur votre propre endpoint

Le projet possède aujourd'hui plusieurs interfaces, et l'endroit où chercher les paramètres du modèle dépend de celle que vous exécutez. Les valeurs elles-mêmes sont identiques partout, seul le chemin pour y accéder diffère.

Agent Canvas nécessite Node.js et uv — sur lequel fonctionne le serveur local de l'agent (détails dans les instructions d'installation). La documentation mentionne Node.js 22.12 ou supérieur, mais à partir de la version 1.17, le paquet lui-même déclare Node.js 24 ou supérieur — installez la version 24 pour éviter tout avertissement de version incompatible. Il existe également une option en conteneur : l'image ghcr.io/openhands/agent-canvas propose l'interface sur http://localhost:8000/canvas et ne voit que les répertoires que vous avez montés.

Clé JoinGonka. Inscrivez-vous sur gate.joingonka.ai/register, confirmez votre adresse et créez une clé avec le préfixe jg- dans la section « API-keys ». Une clé et un solde sont valables pour tous les modèles du réseau. La liste des outils de l'installateur @joingonka/setup ne contient pas OpenHands, et ce n'est pas un oubli : ses paramètres vivent dans l'interface et dans le stockage sécurisé du backend, et non dans un fichier de configuration texte que l'on pourrait facilement modifier de l'extérieur.

Étape 1. Lancez Agent Canvas et ouvrez Settings > LLM. L'assistant de premier lancement propose son propre fournisseur OpenHands — cette étape peut être ignorée, il est facile de revenir aux paramètres plus tard.

Étape 2. Cliquez sur Add LLM Profile et accédez à l'onglet Advanced : l'onglet Basic ne propose que les fournisseurs et les modèles de la liste intégrée.

Étape 3. Remplissez les trois champs :

Étape 4. Enregistrez le profil. Avant l'enregistrement, Canvas vérifie la configuration avec une requête depuis le backend : si la clé est refusée ou si le modèle est indisponible, le profil ne sera pas enregistré et vous verrez un message d'erreur.

Étape 5. Commencez une nouvelle conversation et envoyez un court message. Les conversations déjà ouvertes continuent de fonctionner avec le modèle avec lequel elles ont commencé.

Pourquoi openai/. LiteLLM définit le fournisseur par le préfixe du modèle. Le préfixe openai/ ne signifie pas « modèle d'OpenAI », mais « communiquer avec le serveur via le protocole OpenAI Chat Completions ». Seul le premier segment est supprimé, de sorte que le véritable identifiant atteint la passerelle — deepseek-ai/DeepSeek-V4-Flash-0731. Dans la documentation OpenHands, le même schéma est illustré avec l'exemple openai/qwen/qwen3.6-35b-a3b. Sans préfixe, LiteLLM refusera de fonctionner avec le message LLM Provider NOT provided.

Pourquoi /v1 et rien d'autre. LiteLLM accède au serveur via le client officiel OpenAI, et celui-ci ajoute automatiquement /chat/completions. C'est pourquoi l'adresse doit se terminer par /v1 : sans suffixe, la requête ne passera pas par l'API, et avec un suffixe supplémentaire, elle sera dirigée vers un chemin inexistant. Une autre exigence de Canvas : l'adresse doit être accessible depuis le backend, et pas seulement depuis le navigateur. La passerelle est une adresse HTTPS publique, elle est visible depuis le conteneur Docker de la même manière que depuis l'hôte ; les astuces comme host.docker.internal ne sont nécessaires que pour les modèles situés sur votre machine.

Profils pour les trois modèles. Créez un profil pour chaque modèle du réseau et nommez-les brièvement — par exemple deepseek, glm et minimax (la documentation mentionne une limite de dix profils). Vous pouvez basculer directement dans la conversation, sans perdre le contexte : via le bouton de sélection de profil dans le champ de saisie ou par la commande /model glm ; /model sans argument affichera la liste. Pour ne pas insérer la clé dans chaque profil, vous pouvez l'enregistrer une fois dans le bloc Provider Connections — il est disponible sur le backend local.

Ancienne interface dans Docker. Les champs sont les mêmes : Settings → onglet LLM → activer Advanced → Custom Model, Base URL, API Key → Save Changes.

Le CLI s'installe en une seule commande via uv et, au premier lancement, vous guide lui-même dans la configuration du modèle ; on y revient ensuite avec Ctrl+P → Settings :

uv tool install openhands --python 3.12
openhands

Pour les scripts, les variables d'environnement sont plus pratiques. Détail important : par défaut, le CLI les ignore et ne les applique qu'avec le drapeau --override-with-envs — pour un seul lancement, sans rien enregistrer :

export LLM_MODEL="openai/deepseek-ai/DeepSeek-V4-Flash-0731"
export LLM_BASE_URL="https://gate.joingonka.ai/v1"
export LLM_API_KEY="jg-your-key"

openhands --override-with-envs

Le même ensemble fonctionne sans interface — pour la CI et les tâches par lots :

openhands --headless --override-with-envs -t "Read calc.py and tell me in one sentence whether it has a bug."

En mode headless, l'agent agit toujours avec auto-approbation : lancez-le donc là où il a les coudées franches, dans un répertoire dédié ou un conteneur. Le drapeau --json transforme la sortie en flux d'événements JSONL — pratique à traiter dans un pipeline. C'est exactement ainsi que nous avons testé l'intégration le 21 septembre 2026 sur le CLI 1.16.0 : en en-tête, le CLI affiche Agent initialized with model: openai/deepseek-ai/DeepSeek-V4-Flash-0731, puis l'agent lit le fichier et répond sur le fond.

Les paramètres enregistrés du CLI se trouvent dans ~/.openhands/agent_settings.json : on y change le modèle en modifiant trois champs du bloc llm — model, api_key et base_url. Mieux vaut ne pas créer le fichier de zéro : l'assistant du premier lancement y écrit aussi les autres réglages de l'agent, dont la compression de l'historique, sans laquelle une longue conversation finira par buter sur la fenêtre de contexte.

Si vous intégrez l'agent dans votre propre code, le SDK OpenHands accepte les trois mêmes valeurs :

from pydantic import SecretStr
from openhands.sdk import LLM

llm = LLM(
    model="openai/deepseek-ai/DeepSeek-V4-Flash-0731",
    base_url="https://gate.joingonka.ai/v1",
    api_key=SecretStr("jg-your-key"),
)

Le prix des modèles du réseau est unique, donc le choix dépend du comportement. Deux chiffres sont importants pour un agent autonome. Fenêtre de contexte : chaque étape renvoie l'historique, et plus la fenêtre est longue, plus l'agent travaille longtemps sans perte. Plafond de réponse : l'étape où l'agent écrit un gros fichier en entier doit tenir dans une seule réponse. Le tableau présente les résultats de notre exécution de la même tâche (lire un fichier et trouver une erreur) via OpenHands CLI 1.16.0 avec le SDK 1.21.0.

Le schéma de travail pour une tâche longue reprend les conseils de la documentation OpenHands : planifier avec un modèle, exécuter avec un autre. Commencez la conversation sur le profil glm et demandez un plan sans modifier les fichiers ; envoyez ensuite /model deepseek et donnez l'ordre d'exécuter. L'historique, les fichiers et l'état de la tâche sont conservés lors du basculement. Gardez le profil minimax en troisième position : il est pratique d'y passer quand les deux autres n'ont plus de capacité aux heures de pointe, et vous pouvez lui confier la génération des titres de conversation dans Settings > Application.

Compression de l'historique. Même une fenêtre de centaines de milliers de jetons est finie sur une tâche de plusieurs heures. Dans OpenHands, le condenseur s'en charge : il résume les anciens événements en un court résumé, ce qui, selon la documentation, réduit la latence et la consommation de jetons dans les longues conversations. Dans Agent Canvas, il se configure dans la section Settings > Condenser ; lors de notre exécution, le CLI l'a activé lui-même, avec un seuil de 80 événements.

Limites du modèle. OpenHands récupère la fenêtre de contexte et le plafond de réponse depuis le répertoire LiteLLM, et les identifiants du réseau Gonka n'y figurent pas (nous avons vérifié sur LiteLLM 1.81), donc l'agent n'a pas ses propres valeurs pour ces modèles. Cela ne gêne pas le fonctionnement : la passerelle applique elle-même le plafond de réponse, selon le tableau ci-dessus. Si vous souhaitez définir des limites explicitement, utilisez les champs max_input_tokens et max_output_tokens dans le SDK, et dans Canvas, l'onglet All permet d'accéder à l'ensemble complet des champs du profil. Plus de détails sur le modèle par défaut dans la présentation de DeepSeek V4 Flash.

Vous pouvez vérifier que les requêtes passent bien par la passerelle de deux manières. Côté OpenHands : lancez une nouvelle conversation et une tâche courte comme "lis le README et résume-le en une phrase" : l'agent doit appeler un outil et répondre. Côté passerelle : dans votre tableau de bord, section "Utilisation" (Usage), la requête apparaîtra dans la répartition "Par modèles", et le bloc "Par clés" affichera l'heure de la dernière requête. Si c'est vide, la conversation se déroule sur un autre profil : vérifiez lequel est marqué comme actif.

Selon la documentation OpenHands, le nombre de tentatives et les pauses entre elles lors d'une erreur 429 se configurent via les variables LLM_NUM_RETRIES, LLM_RETRY_MIN_WAIT et LLM_RETRY_MAX_WAIT. Les valeurs par défaut différant entre la documentation et le SDK, basez-vous sur les valeurs réelles : dans l'état de conversation CLI 1.16.0, nous avons observé 5 tentatives avec des pauses allant de 8 à 64 secondes.

Via la passerelle JoinGonka, les tokens 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é dynamiquement sur cette page.

Les estimations de la colonne de droite sont basées sur les prix de septembre 2026 ; le fonctionnement économique des agents est détaillé dans l'article sur l'API la moins chère pour les agents IA.

Plafond de dépenses. OpenHands conseille de définir des limites de dépenses — la passerelle l'intègre nativement via le modèle de paiement : le solde est prépayé, et l'agent ne pourra pas dépenser plus que ce qu'il y a sur le compte. Le solde restant et la consommation quotidienne sont visibles dans le tableau de bord. Pour la CI et les automatisations en arrière-plan, créez une clé séparée afin que leur consommation ne soit pas mélangée à la vôtre ; les clés filles avec limite quotidienne sont décrites dans l'article sur les Management Keys.

Limite de confiance. Agent Canvas, lancé via npm, s'exécute avec vos droits d'utilisateur et accède à tout le système de fichiers. Pour du code externe, utilisez la version Docker : l'agent ne verra que le répertoire monté. Il s'agit d'une caractéristique propre à OpenHands, indépendante du fournisseur du modèle.

La correspondance reste chez vous. OpenHands conserve l'historique des conversations en local, dans ~/.openhands, et l'envoie au modèle à chaque étape ; la passerelle ne stocke aucune correspondance — vos prompts et votre code ne sont pas conservés après la réponse.

Si la tâche contient des images — captures d'écran, schémas — créez un profil dédié avec un modèle vision : les modèles du réseau Gonka sont textuels. Pour le code, les commandes et les fichiers, ce n'est pas une limite.