Points clés
- Vérifiez l'endpoint avec curl avant de toucher à OpenCode, afin de savoir si un échec vient de la configuration ou de l'API.
- Un fournisseur personnalisé nécessite trois éléments : URL de base, clé API et un ID de modèle, qui est uncensored ici.
- Définissez la limite de contexte à 100 000 tokens afin que l'agent planifie autour de la fenêtre réelle.
- Le streaming et l'appel de fonctions sont pris en charge, ce dont a besoin une boucle d'exécution.
Ce dont vous avez besoin avant de commencer
OpenCode est un agent de codage open-source qui s'exécute dans votre terminal. Il peut communiquer avec de nombreux fournisseurs de modèles et vous permet d'ajouter votre propre fournisseur si l'endpoint suit le format de chat OpenAI. Cette API le fait, la configuration consiste donc à remplir quelques champs.
Rassemblez d'abord ces trois valeurs :
- URL de base :
https://api.kimicode.top/v1 - ID de modèle :
uncensored - Clé API : créez-en une sur la page clé API. Les nouveaux comptes peuvent y réclamer un crédit d'essai de 0,50 $ en un clic, ce qui est largement suffisant pour les tests ci-dessous. La clé d'essai permet 2 requêtes simultanées et 60 requêtes par minute.
Conservez la clé dans une variable d'environnement au lieu de la coller dans des fichiers que vous commiterez :
export KIMICODE_API_KEY="your-key-here"Étape 1 : tester l'endpoint avec curl
Faites ceci avant de configurer n'importe quel outil. Si curl fonctionne et OpenCode non, vous savez que le problème vient de la configuration. Si curl échoue, vous corrigez la clé ou l'URL une seule fois, pas à deux endroits.
curl https://api.kimicode.top/v1/chat/completions \
-H "Authorization: Bearer $KIMICODE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"messages": [{"role": "user", "content": "Say hello in five words."}],
"max_tokens": 40
}'Vous devriez obtenir un objet JSON avec un tableau choices et un bloc usage. Un 401 signifie que la clé est incorrecte ou manque le préfixe Bearer. Un 404 signifie généralement que l'URL a été mal tapée ou inclut déjà /chat/completions.
Un agent de codage diffuse ses réponses et appelle des outils, vérifiez donc ces deux points également :
curl -N https://api.kimicode.top/v1/chat/completions \
-H "Authorization: Bearer $KIMICODE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"stream": true,
"messages": [{"role": "user", "content": "Count from one to five."}]
}'Vous devriez voir une série de lignes data:, chacune avec un petit delta JSON, se terminant par les chiffres d'utilisation et un marqueur final. Le drapeau -N désactive la mise en mémoire tampon de curl afin que les chunks apparaissent à mesure qu'ils arrivent.
Étape 2 : ajouter un fournisseur personnalisé à OpenCode
OpenCode lit un fichier de configuration JSON, opencode.json, depuis votre dossier de projet ou depuis son répertoire de configuration global. Les fournisseurs personnalisés de style OpenAI sont déclarés avec le package compatible OpenAI de l'AI SDK, une URL de base et une liste de modèles. La disposition ci-dessous suit la documentation publique d'OpenCode au moment de la rédaction. Les noms de champs peuvent changer entre les versions, alors comparez-le avec la section fournisseur de la documentation OpenCode actuelle si quelque chose est rejeté.
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"kimicode": {
"npm": "@ai-sdk/openai-compatible",
"name": "Kimicode API",
"options": {
"baseURL": "https://api.kimicode.top/v1",
"apiKey": "{env:KIMICODE_API_KEY}"
},
"models": {
"uncensored": {
"name": "Uncensored",
"limit": {
"context": 100000,
"output": 8192
}
}
}
}
},
"model": "kimicode/uncensored"
}La clé sous models est l'ID de modèle exact envoyé au serveur, elle doit donc lire uncensored. La dernière ligne sélectionne le fournisseur et le modèle par défaut, écrits sous la forme nom du fournisseur, une barre oblique, puis l'ID du modèle.
La forme {env:KIMICODE_API_KEY} indique à OpenCode de lire la variable depuis votre shell. Si votre version gère les identifiants via sa propre commande de connexion, utilisez cette méthode et laissez la clé hors du fichier. Dans les deux cas, ne committez pas une vraie clé.
Configuration du projet ou configuration globale
Vous pouvez conserver le bloc fournisseur à deux endroits. Un fichier à la racine du projet s'applique uniquement à ce dépôt, ce qui convient à une équipe partageant une seule configuration. Un fichier dans votre répertoire de configuration utilisateur s'applique partout, ce qui convient à un défaut personnel. Lorsque les deux existent, le fichier du projet s'ajoute ou écrase le fichier global.
Préférez le fichier global pour la définition du fournisseur et la variable d'environnement pour la clé. Ainsi, chaque dépôt peut utiliser l'endpoint, et rien de secret ne se trouve à côté de votre code source. Si plusieurs personnes travaillent sur un même projet, committez uniquement le bloc fournisseur sans clé, et faites en sorte que chaque personne définisse sa propre variable. Cela rend également simple la rotation d'une clé : changez la variable, redémarrez le terminal, et le fichier de configuration reste inchangé.
Étape 3 : choisir le modèle et exécuter une tâche
Démarrez OpenCode dans un dossier de projet et ouvrez son sélecteur de modèles. Votre fournisseur personnalisé devrait apparaître dans la liste avec le nom d'affichage que vous avez défini. Sélectionnez-le, puis donnez à l'agent une petite tâche vérifiable telle qu'expliquer une fonction ou écrire un test unitaire pour un fichier court.
Commencez petit pour deux raisons. Premièrement, vous pouvez voir si les appels de fonctions fonctionnent : lorsque OpenCode demande au modèle de lire ou de modifier un fichier, il le fait via l'interface d'appel de fonctions. Deuxièmement, un agent de codage envoie beaucoup de texte par tour, y compris le contenu des fichiers et l'historique, donc une longue session consomme des tokens rapidement. La section suivante met des chiffres sur cela.
Si le modèle n'apparaît pas, vérifiez que le fichier est un JSON valide, qu'il se trouve là où OpenCode cherche la configuration, et que le nom du fournisseur correspond à ce que vous avez tapé dans le champ model.
Tester l'appel de fonctions et le mode JSON directement
OpenCode repose sur l'appel de fonctions pour lire des fichiers, exécuter des commandes et éditer du code, il vaut donc la peine de confirmer que l'endpoint gère une définition d'outil avant de blâmer l'agent pour un échec. Cette requête propose un outil et pose une question qui en a besoin.
curl https://api.kimicode.top/v1/chat/completions \
-H "Authorization: Bearer $KIMICODE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"messages": [{"role": "user", "content": "What is in the file notes.txt?"}],
"tools": [{
"type": "function",
"function": {
"name": "read_file",
"description": "Read a text file by path",
"parameters": {
"type": "object",
"properties": {"path": {"type": "string"}},
"required": ["path"]
}
}
}],
"tool_choice": "auto"
}'Une bonne réponse contient une entrée tool_calls nommant read_file avec une chaîne d'arguments JSON. L'agent exécute l'outil, puis renvoie le résultat sous forme de message avec role défini sur tool, et le modèle continue à partir de là. Si vous ne voyez que du texte brut, essayez un prompt plus direct, car le fait que le modèle décide d'appeler un outil fait partie de son comportement.
Le mode JSON est un interrupteur séparé. Ajouter "response_format": {"type": "json_object"} demande une sortie JSON valide, et cela aide lorsqu'un autre script doit analyser ce qui revient. Mentionnez JSON dans votre prompt également, afin que le modèle sache quelle forme vous attendez.
Taille du contexte et coût d'une session
La fenêtre de contexte est de 100 000 tokens, comptant le prompt et la complétion ensemble. Définir limit.context à 100000 permet à l'agent de connaître le plafond réel, afin qu'il puisse tronquer ou résumer l'historique avant que le serveur n'ait à rejeter une requête. Une complétion peut utiliser tout l'espace restant, et max_tokens est optionnel.
La facturation est de $0,15 par 1 M de tokens d'entrée et de $0,50 par 1 M de tokens de sortie. Les agents sont lourds en entrée, car chaque tour renvoie la conversation. Voici un exemple détaillé pour une session modérée :
- 40 tours, chacun envoyant environ 30 000 tokens d'entrée : 1 200 000 tokens d'entrée, soit 1,2 x $0,15 = $0,18.
- Chaque tour retourne environ 800 tokens de sortie : 32 000 tokens de sortie, soit 0,032 x $0,50 = $0,016.
- Total : $0,196, soit environ vingt cents pour toute la session.
Vos chiffres varieront. Lisez les valeurs usage dans les réponses, ou surveillez l'en-tête X-Balance-USD, qui indique votre solde restant à chaque réponse. Le crédit est prépayé et n'expire jamais, et les requêtes échouées ou refusées ne sont pas facturées. Les détails sont sur la page tarifs.
Attentes réalistes pour un agent de développement
Il s'agit d'un modèle de texte général ajusté pour répondre sans refus de contenu pour un usage adulte légal. Ce n'est pas un modèle construit spécifiquement pour le code, et cette page ne fait aucune affirmation de benchmark. Le fait qu'il modifie votre dépôt de manière fiable est quelque chose que vous devriez tester sur vos propres tâches, avec le contrôle de version activé, avant de lui confier quelque chose d'important.
Il gère les mécanismes dont a besoin un agent : appel d'outils avec des tool_calls en streaming, résultats d'outils envoyés en tant que messages role: "tool", et mode JSON via response_format. Il est uniquement textuel, sans images, donc les fonctionnalités qui attachent des captures d'écran ne fonctionneront pas.
Deux limites sont importantes pour les agents. Une clé complète permet 8 requêtes simultanées et 300 requêtes par minute. Les sous-agents ou les exécutions d'outils en parallèle qui déclenchent de nombreux appels à la fois peuvent atteindre la limite de concurrence, et une requête en streaming conserve sa place jusqu'à la fin du flux. Lorsque cela se produit, vous obtenez une erreur HTTP 429 avec le code concurrency. Le code rate_limited signifie trop de requêtes par minute. En cas de surcharge temporaire, vous pouvez également voir un 429 avec Retry-After: 5. Réduisez le parallélisme ou attendez et réessayez.
Dépannage
| Symptôme | Cause probable | Correction |
|---|---|---|
| 401 Accès refusé | Clé vide ou incorrecte ; la variable d'environnement n'est pas définie dans le shell qui a lancé OpenCode | Exécutez echo $KIMICODE_API_KEY dans le même terminal, puis redémarrez OpenCode |
| 404 Non trouvé | L'URL de base inclut /chat/completions ou manque /v1 | Utilisez exactement https://api.kimicode.top/v1 |
| Modèle non trouvé | L'ID du modèle diffère de uncensored | Faites correspondre la clé dans models à l'ID retourné par GET /v1/models |
429 avec concurrency | Trop de requêtes à la fois | Réduisez le nombre d'appels d'outils en parallèle, ou attendez la fin des flux |
| Requête trop volumineuse | Corps de plus de 8 Mo ou historique proche de la limite de la fenêtre de contexte | Commencez une nouvelle session ou résumez l'historique |
Pour tout ce qui n'est pas couvert ici, la page de documentation contient la référence complète des requêtes, et le guide d'intégration couvre le même endpoint sous l'angle d'autres clients de style OpenAI.
