Configuration de l'API personnalisée ZCode AI

ZCode peut ajouter des services qui implémentent le protocole Anthropic ou OpenAI en tant que fournisseurs personnalisés. Ce guide suit l'ordre actuel du flux Connect Models → Custom Providers (Anthropic / OpenAI Compatible) officiel de ZCode et configure TokenHub en tant que fournisseur OpenAI-compatible chez https://us-api.tokenhub.com/v1.

Ouvrir les paramètres du modèle

Au premier lancement, lorsqu'aucun modèle n'est disponible, sélectionnez Use API Key. Si ZCode est déjà ouvert, cliquez sur le nom du modèle dans la zone d'invite, choisissez Manage Models et ouvrez Settings → Model Settings.

Ajouter le fournisseur personnalisé TokenHub

Suivez les sept étapes du flux du fournisseur personnalisé de ZCode :

1. Ouvrez Settings → Model Settings.
2. Au bas de la liste des fournisseurs, cliquez sur Add Provider.
3. Nommez le fournisseur TokenHub.
4. Choisissez OpenAI-compatible. Dans le menu Base URL, sélectionnez une adresse personnalisée ou saisissez manuellement https://us-api.tokenhub.com/v1.
5. Entrez votre clé TokenHub API dans API Key.
6. Cliquez sur Add Model et entrez un ID de modèle exact à partir du catalogue de modèles TokenHub. Ajoutez chaque modèle supplémentaire séparément.
7. Enregistrez les paramètres et activez le commutateur Enable du fournisseur. Confirmez que chaque modèle que vous avez l'intention d'utiliser est également activé.

ZCode ne déduit pas les identifiants de modèles tiers pour vous. Si le fournisseur ne renvoie pas de liste de modèles, ajoutez chaque ID exact manuellement avec Add Model.

Ne mélangez pas les paramètres des protocoles Anthropic et OpenAI dans un seul fournisseur. Créez un fournisseur distinct pour Anthropic Messages et utilisez la racine URL requise par ce protocole.

Configurer les paramètres avancés pour un modèle

Sous Settings → Model Providers, ouvrez le modèle que vous avez ajouté et développez Advanced :

• Max output tokens: laisse normalement ce champ vide et laisse le service de modèle signaler la valeur prise en charge. Définissez-le manuellement uniquement après avoir confirmé la limite du modèle cible.
• Context window: ceci est modifiable pour les modèles de fournisseur personnalisé et la valeur enregistrée s'applique uniquement aux nouvelles conversations. Utilisez la spécification du modèle TokenHub, et non la valeur d'un autre modèle.
• Les niveaux visibles du Thinking effort: dépendent du modèle et du protocole. Les requêtes OpenAI-compatible utilisent reasoning_effort ; un déploiement tiers peut rejeter certains niveaux affichés par ZCode. Baissez le niveau ou désactivez l'option après une erreur de paramètre 400.
• Custom request parameters: ZCode n’injecte pas automatiquement les valeurs arbitraires ajoutées manuellement au fournisseur local options dans le corps de la demande. Ne comptez pas sur la modification de ~/.zcode/v2/config.json pour ajouter des paramètres de raisonnement ou d'image supplémentaires.

Comment ZCode décide si l'entrée d'image est disponible

ZCode combine le fournisseur, l'ID de modèle, les capacités de catalogue de modèles et le protocole actif lors du traitement des images :

• Lorsque le support est connu, ZCode conserve l'image et l'envoie au service de modèles.
• Lorsque le modèle est marqué comme non pris en charge, ZCode supprime l'image et la remplace par une notification textuelle.
• Lorsque la capacité est inconnue, ZCode ne bloque pas l'image à l'avance ; TokenHub prend la décision finale et peut rejeter la demande.

Le même modèle peut être traité différemment via un autre fournisseur ou protocole. Testez d'abord le texte et envoyez une image uniquement lorsque la page de modèle TokenHub répertorie explicitement l'entrée d'image.

Sélectionnez le modèle et vérifiez

1. Revenez au sélecteur de modèle dans la boîte de dialogue.
2. Choisissez le fournisseur TokenHub et le modèle que vous avez ajouté.
3. Envoyez une courte instruction telle que « Expliquez le fichier actuel sans le modifier ».
4. Dans les journaux de requête TokenHub, confirmez que la requête utilise /v1/chat/completions et vérifiez l'ID du modèle, le code d'état et l'utilisation.
5. Une fois les réponses textuelles stables, testez l'édition, les appels d'outils, le contexte long et la saisie d'image séparément.

Cela suit les conseils officiels Verify The Setup de ZCode : sélectionnez le nouveau canal, envoyez une courte instruction de test et confirmez une réponse stable avant un véritable travail.

Portée du proxy HTTP intégré à ZCode

Un proxy HTTP configuré dans ZCode Settings couvre les API de modèle, MCP, WebFetch, les processus enfants du terminal, le marché des extensions et le chargement des pages dans l'application. Il ne couvre pas la connexion au compte de bureau, la génération de wiki, le Web Remote Control WebSocket ou les connexions à distance SSH. ZCode n’achemine pas non plus toutes les requêtes via les variables système HTTP_PROXY / HTTPS_PROXY par défaut. Redémarrez ZCode après avoir modifié le proxy intégré à l'application.

Dépannage

• Modèle manquant : assurez-vous que le fournisseur et le modèle sont activés.
• 404 : confirmez que le point final ne répète pas /chat/completions.
• Incompatibilité de format de demande : vérifiez si le fournisseur est OpenAI-compatible ou Anthropic.
• Le texte fonctionne mais pas l’édition de code : le modèle sélectionné peut ne pas disposer d’appels d’outils natifs fiables.
• L'effort de réflexion renvoie 400 : diminuez ou désactivez le niveau car le déploiement risque de ne pas l'accepter.
• La demande d'image échoue : utilisez un ID de modèle canonique et confirmez que le fournisseur, le protocole et le modèle TokenHub prennent tous en charge les images.
• Le changement de proxy n'a aucun effet : redémarrez ZCode et confirmez que le type de trafic est couvert par le proxy intégré de ZCode.

Référence officielle

• ZCode : connecter les modèles