DeepSeek Harness : installation et connexion API

DeepSeek Harness est un agent de code open source et un runtime d'agent créé par DeepSeek AI. Il fournit la boucle, les tools, l'accès au workspace, les sessions, les permissions et l'interface autour d'un modèle. Le modèle vient toujours d'un API Provider. Ce tutoriel explique d'abord le DeepSeek code harness, puis le connecte à OmniaKey par le flux officiel de custom provider.

Qu'est-ce que DeepSeek Harness ?

DeepSeek Harness, abrégé dsh, n'est pas un nouveau modèle de langage. C'est le logiciel qui transforme un modèle en agent capable de comprendre un workspace, appeler des tools, modifier des fichiers, exécuter des commandes, conserver des sessions et demander une approbation.

Certains articles parlent de framework d'agent IA open source. Les documents officiels sont plus précis : agent harness open source, agent de code extensible local-first, et environnement de développement/runtime pour agents.

Son principe central est everything is a plugin. Construit sur Cordis, le projet permet de remplacer ou recomposer par configuration les models, tools, skills, sessions, sandboxes, storage, loops, scheduling et même l'interface.

Le flux d'événements traçable est plus qu'un historique de chat. La documentation décrit resume, fork, search et replay comme des opérations sur le même session log, ce qui aide lorsqu'un agent effectue plusieurs tool calls avant de répondre.

Ce que DeepSeek Harness n'est pas

• Ce n'est ni DeepSeek V4 Pro ni un autre modèle. Harness et modèle sont deux couches distinctes.
• Ce n'est pas encore une version de production stable. DeepSeek l'étiquette developer preview et avertit de changements incompatibles.
• Avec le quick start npm, ce n'est pas un service de coding hébergé. La Web UI écoute le loopback local par défaut.
• Open source ne signifie pas inference gratuite. Le dépôt utilise la licence MIT, mais l'API est facturée par le Provider configuré.

Configuration OmniaKey dans DeepSeek Harness

Voici les valeurs complètes avant les étapes détaillées :

Le suffixe /v1 fait partie de la Base URL. N'utilisez pas l'origine seule, ne répétez pas /v1/v1 et ne collez pas le chemin complet /chat/completions. DeepSeek Harness ajoute lui-même le chemin d'opération.

1. Installer et lancer DeepSeek Harness

Installez Node.js, ouvrez un terminal dans le répertoire projet que l'agent doit voir, puis lancez le quick start officiel :

npx @deepseek-ai/dsh web

La commande démarre actuellement la Web UI ici :

http://127.0.0.1:3080

Si 3080 est occupé, choisissez un autre port :

npx @deepseek-ai/dsh web --port 3081

Le répertoire où vous lancez dsh devient l'emplacement filesystem par défaut. Le composer reste indisponible tant que vous n'ajoutez et ne sélectionnez pas un workspace dans l'UI. Choisissez volontairement le dépôt : l'agent peut recevoir des tools fichier et shell selon la permission policy active.

2. Créer une clé API OmniaKey dédiée

Ouvrez le dashboard des clés API OmniaKey et créez une clé réservée à DeepSeek Harness. Une clé distincte est plus simple à plafonner, faire tourner, révoquer et auditer qu'un credential partagé.

Ne placez jamais la clé en clair dans un dépôt, l'historique du shell, une capture, une issue ou un chat. La Web UI traite les clés enregistrées comme write-only. DeepSeek documente que le secret est stocké dans $DSH_HOME/.credentials.yaml, tandis que settings ne garde qu'une credential reference et que la page reçoit un descripteur masqué.

3. Ajouter OmniaKey comme custom provider

Sur une nouvelle installation, acceptez Internal Testing Notice avec Continue. Le dialogue suivant demande une clé officielle DeepSeek ; choisissez Configure later, car OmniaKey doit être placé dans un custom provider et non dans cette route intégrée.

Dans DeepSeek Harness, ouvrez Settings → Models, choisissez Add a custom provider et saisissez :

1. Provider ID : omniakey, en commençant par une minuscule.
2. Display name : OmniaKey.
3. Base URL : https://api.omniakey.com/v1.
4. API protocol : openai-completions.
5. API key : la clé OmniaKey créée précédemment.

Le Provider ID est permanent, car sessions, defaults, requêtes et credential references le citent. Le Display name, la Base URL, le protocole, le credential et la liste des modèles restent modifiables.

4. Récupérer et sélectionner les modèles

Sous Model catalog, cliquez sur Fetch available models. Pour un custom Provider OpenAI-compatible, l'outil envoie avec Bearer authentication un GET /models à la Base URL. Ici, la requête finale est GET /v1/models sur OmniaKey.

Ne sélectionnez que les modèles que vous utiliserez. Ces deux IDs sont de bons points de départ :

Le même Provider peut aussi utiliser les modèles Claude, GPT, Gemini, Grok et GLM actuellement pris en charge par OmniaKey. Copiez les IDs exacts depuis le catalogue en direct ; un nom de modèle est un identifiant exact, pas un alias approximatif.

Si le discovery est indisponible, ajoutez manuellement le Model ID exact. dsh demande au moins un modèle pour créer le custom Provider.

5. Choisir le workspace et vérifier sans risque

Enregistrez le Provider, choisissez le projet avec Choose workspace, démarrez une nouvelle session et sélectionnez OmniaKey / deepseek-v4-pro ou OmniaKey / deepseek-v4-flash.

Commencez par une tâche read-only très limitée :

Inspecte package.json et résume les scripts disponibles. Ne modifie aucun fichier et n'exécute aucune commande.

Ce test confirme workspace, Provider, clé, Model ID et response path avant d'autoriser édition ou shell. Une réponse textuelle ne valide pas tous les formats de tool calls ; testez ensuite une opération réversible avant de confier un gros refactor.

Les Model Settings s'appliquent à la requête suivante sans redémarrer le serveur. Une session ayant déjà envoyé une requête conserve toutefois le modèle enregistré dans son log. Après un changement de Provider ou de modèle, utilisez une nouvelle session pour un test sans ambiguïté.

Option : configurer OmniaKey dans settings.yaml

La Web UI est plus claire pour le premier passage. Dans un environnement local contrôlé, vous pouvez définir le Provider dans $DSH_HOME/settings.yaml en référençant une variable d'environnement plutôt qu'en incluant la clé :

export OMNIAKEY_API_KEY="your-omniakey-api-key"

llm-pi-ai:
  providers:
    omniakey:
      displayName: OmniaKey
      apiKeyEnv: OMNIAKEY_API_KEY
      api: openai-completions
      baseURL: https://api.omniakey.com/v1
      models:
        - id: deepseek-v4-pro
        - id: deepseek-v4-flash

La clé doit exister dans l'environnement du processus Harness. Ne remplacez pas apiKeyEnv par un secret littéral dans settings.yaml. La référence officielle dsh-llm-pi-ai recommande les credential references pour garder les secrets hors du document settings.

Pourquoi utiliser OmniaKey avec DeepSeek Harness ?

DeepSeek Harness accepte déjà les gateways personnalisés ; OmniaKey transforme ce point d'extension en une seule entrée Provider réutilisable.

• Une configuration pour plusieurs familles. Changez le Model ID exact dans le picker sans créer un profil par vendor.
• Model discovery. Harness peut lire la liste OpenAI-compatible d'OmniaKey au lieu de saisir les IDs de mémoire.
• Contrôles opérationnels séparés. Donnez à Harness sa propre clé, son quota, son cycle de rotation et son usage trail.
• Identité explicite du modèle. OmniaKey n'effectue pas de silent model substitution : le Provider et le modèle demandés s'exécutent, et un upstream indisponible produit une erreur visible.
• Paiement de l'usage API, pas d'un abonnement agent supplémentaire. OmniaKey utilise un solde prépayé et une facturation par token ; disponibilité et tarifs restent dans le catalogue.

Cela ne rend pas OmniaKey toujours meilleur qu'une clé DeepSeek directe. Pour le seul compte et endpoint natifs DeepSeek, le Provider direct est logique. OmniaKey est utile lorsqu'une installation Harness doit employer plusieurs familles choisies avec une clé et une Base URL.

Dépannage

Fetch available models renvoie 401

Vérifiez que la clé vient d'OmniaKey, ne contient pas d'espace, reste active et est associée exactement à https://api.omniakey.com/v1. Le model discovery utilise Bearer authentication.

Le Provider renvoie 404

Vérifiez la Base URL avant de changer de modèle. Les erreurs courantes sont l'absence de /v1, sa répétition ou l'utilisation de https://api.omniakey.com/v1/chat/completions comme Base URL.

UNKNOWN_MODEL

Le modèle n'est pas dans la liste enregistrée du custom Provider. Récupérez à nouveau les modèles ou ajoutez l'ID exact du catalogue OmniaKey, puis sélectionnez-le dans une nouvelle session.

MISSING_CREDENTIAL

Enregistrez la clé via Settings → Models ou assurez-vous que OMNIAKEY_API_KEY existe dans le shell qui lance DeepSeek Harness. Une variable définie dans un autre terminal ne met pas à jour un processus déjà lancé.

Le changement de modèle ne semble pas appliqué

Démarrez une nouvelle session. Les sessions existantes conservent Provider et modèle dans leur append-only log après la première requête.

Le texte fonctionne mais un tool échoue

La génération de texte et l'usage structuré de tools sont deux contrôles distincts. Commencez par une tâche read-only, inspectez l'échec précis dans la vue Trajectory, puis seulement augmentez limites ou permissions. Un tool call mal formé n'est pas réparé en faisant tourner une clé valide.

Questions fréquentes

DeepSeek Harness est-il gratuit ?

Le code source est sous licence MIT. L'inference du modèle est séparée et peut entraîner des frais via DeepSeek, OmniaKey ou un autre Provider.

DeepSeek Harness peut-il utiliser DeepSeek V4 Pro via OmniaKey ?

Oui. Ajoutez OmniaKey comme custom Provider openai-completions et choisissez l'ID exact deepseek-v4-pro. deepseek-v4-flash est également disponible comme route moins chère.

Pour la version 0813, les tarifs peak/off-peak et les calculs de tokens, consultez le guide de prix API DeepSeek V4 Pro (English). La route Flash plus récente, la vision native, les benchmarks et le statut actuel de V4 Pro sont dans la revue DeepSeek V4.1 Flash.

Faut-il coller une clé OmniaKey dans la carte DeepSeek intégrée ?

Utilisez plutôt Add a custom provider. La carte intégrée configure la route officielle DeepSeek, alors que le formulaire personnalisé est la voie documentée pour un gateway et expose Base URL, protocole et liste de modèles.

Le même Provider peut-il utiliser Claude, GPT ou Gemini ?

Oui, si l'interface OpenAI-compatible d'OmniaKey prend actuellement le modèle en charge. Récupérez la liste en direct et ajoutez les IDs exacts. Les caractéristiques de protocole peuvent varier ; testez les tools avec le modèle choisi.

Où la clé API est-elle stockée ?

Les clés enregistrées dans Models sont write-only et stockées dans $DSH_HOME/.credentials.yaml; settings garde la credential reference. Pour une configuration YAML, utilisez apiKeyEnv et l'environnement du processus.

DeepSeek Harness est-il prêt pour un workflow de production stable ?

Traitez-le aujourd'hui comme une cible d'évaluation. DeepSeek parle explicitement de developer preview et avertit de changements incompatibles. Épinglez les versions, sauvegardez la configuration sans secrets et revérifiez le guide après chaque upgrade.

Sources vérifiées

• DeepSeek Harness product page
• DeepSeek Harness GitHub README
• Official Web UI quick start
• Official model and custom-provider guide
• Official dsh-llm-pi-ai provider reference
• OmniaKey OpenAI-compatible API reference (English)
• OmniaKey live model catalog