OpenHands

Settings → LLM → Advanced demande trois champs — Custom Model, Base URL, API Key — avec l’identifiant du modèle portant le préfixe openai/ et l’URL de base conservant son /v1.

# Settings → LLM → Advanced  (toggle "Advanced" on first)
Custom Model   openai/claude-sonnet-5
Base URL       https://api.kunavo.com/v1
API Key        sk-kn-...

# The "openai/" prefix is the provider, not a vendor: it tells OpenHands to
# speak the OpenAI Chat Completions protocol to the Base URL above. The model
# id after the slash is Kunavo's, and resolves at Kunavo.
#
# Keep the /v1. It belongs to the openai/ prefix — a litellm_proxy/ model
# takes the bare origin instead, which is the opposite convention.

Étape par étape

1. Créez une clé sur /app/keys et copiez-la — elle n’est affichée qu’une seule fois.
2. Ouvrez Paramètres → LLM et activez le bouton Advanced. Les trois champs apparaissent dans cet ordre : Custom Model, Base URL, API Key.
3. Saisissez l’identifiant du modèle avec son préfixe — openai/claude-sonnet-5, et non claude-sonnet-5. Les identifiants proposés par Kunavo sont ceux renvoyés par GET /v1/models, soit la même liste que la documentation officielle d’OpenHands vous indique d’utiliser pour choisir un identifiant personnalisé.
4. Collez https://api.kunavo.com/v1 dans le champ Base URL et votre clé dans API Key, puis cliquez sur Save Changes. OpenHands indique que l’enregistrement d’un profil local valide d’abord la configuration auprès du backend et bloque l’enregistrement en cas d’échec ; une erreur ici correspond donc à un véritable rejet, et non à un simple problème d’affichage.
5. Vérifiez ce à quoi le backend peut accéder, et non votre navigateur. L’URL de base doit être accessible depuis la machine exécutant l’Agent Server — la documentation précise que si Agent Canvas s’exécute dans Docker, 127.0.0.1 est le conteneur. Un endpoint public comme celui de Kunavo est le cas le plus simple ; un proxy d’entreprise placé devant lui ne l’est pas.
6. Démarrez une conversation nouvelle et confiez-lui une tâche qui lit et modifie un fichier. OpenHands précise qu’un LLM enregistré s’applique aux nouvelles conversations et que les anciennes doivent d’abord être redémarrées ; une exécution qui utilise les outils vous renseigne davantage sur l’association que ne le ferait un simple salut.

Vérifié avec Page des paramètres du modèle de langage (LLM) d’OpenHands le 21 septembre 2026. Les paramètres tiers évoluent ; si le nom d’un champ ne correspond plus à ce que vous voyez ici, cette page fait autorité, pas celle-ci.

Vérifiez avant de déboguer le client

Une requête suffit à déterminer si l’échec vient de l’endpoint, de la clé ou du fichier de configuration. Si cette requête renvoie du JSON, la même URL de base et la même clé fonctionnent dans OpenHands.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

Quel identifiant de modèle saisir dans le champ

Tous les modèles textuels sont accessibles sous forme d’identifiant de modèle — la liste à jour se trouve sur GET /v1/models, et le catalogue avec les prix sur la page des modèles. Les tarifs sont en USD par million de tokens, entrée / sortie.

Trois particularités à connaître avant le débogage

OpenHands comporte davantage d’éléments qu’une interface en ligne de commande à processus unique, et deux d’entre eux ressemblent à l’endpoint LLM sans en être un. Voici ce qu’indique sa documentation officielle, consultée à la date mentionnée ci-dessus :

1. Le bac à sable n’est pas le modèle. OpenHands exécute votre travail dans un bac à sable du serveur agent et appelle le modèle sur le réseau ; ce sont des interfaces distinctes, avec des identifiants d’accès distincts. Une clé configurée ici autorise des appels au modèle. Elle ne détermine en rien ce à quoi le bac à sable peut accéder ; un problème réseau dans le bac à sable ne ressemble pas à une erreur d’authentification.
2. Les agents ACP sont entièrement distincts. Agent Canvas peut déléguer à Claude Code, Codex ou Gemini CLI en tant qu’agent ACP, et la page Configure a Model précise qu’ils « gèrent leur propre accès aux modèles » — un profil LLM ne redirige donc pas ce sous-processus. Si vous vous attendiez à voir du trafic sur votre clé et qu’il n’y en a pas, vérifiez quel agent est réellement en cours d’exécution. La comparaison entre OpenHands et Claude Code explique cette distinction, y compris la règle de priorité des identifiants qui la détermine.
3. Profils et limite de 10 profils. Une configuration enregistrée devient un profil LLM ; le dernier profil enregistré devient actif pour les nouvelles conversations, et il est possible de changer de profil en cours de conversation sans perdre le contexte — c’est ce qui permet d’utiliser un identifiant économique et un identifiant coûteux avec une seule clé. La documentation limite ce nombre à 10 profils par compte. Une connexion de fournisseur enregistre une fois le fournisseur, la clé API et l’URL de base facultative pour plusieurs profils. La même page précise que ce panneau est disponible sur les backends de serveur agent locaux et masqué sur un backend OpenHands Cloud.