DeepSeek Harness: installazione e connessione API

DeepSeek Harness è un agente di coding open source e agent runtime di DeepSeek AI. Fornisce loop, tools, accesso al workspace, sessions, permissions e interfaccia attorno a un modello. Il modello continua a provenire da un API Provider. Questo tutorial spiega prima cosa fa il DeepSeek code harness e poi lo collega a OmniaKey tramite il flusso ufficiale custom provider.

Che cos'è DeepSeek Harness?

DeepSeek Harness, abbreviato dsh, non è un nuovo modello linguistico. È il software che trasforma un modello in agent capace di capire un workspace, chiamare tools, modificare file, eseguire command, conservare sessions e chiedere approval.

Alcuni articoli lo chiamano framework open source per agenti AI. I materiali ufficiali sono più specifici: open-source agent harness, agente di coding estensibile local-first e ambiente di sviluppo/runtime per agent.

Il principio centrale è everything is a plugin. Basato su Cordis, permette di sostituire o ricomporre tramite configurazione models, tools, skills, sessions, sandboxes, storage, loops, scheduling e perfino la UI.

L'event stream tracciabile è più di una chat. La documentazione descrive resume, fork, search e replay come operazioni sullo stesso session log, utile quando un agent esegue molti tool call prima della risposta.

Cosa non è DeepSeek Harness

• Non è DeepSeek V4 Pro né un altro modello. Harness e modello sono livelli distinti.
• Non è ancora una stable production release. DeepSeek lo definisce developer preview e avverte di compatibility-breaking changes.
• Con il quick start npm non è un servizio di coding hosted. La Web UI si collega al loopback locale per default.
• Open source non rende gratuita l'inference. Il repository usa MIT license, mentre l'API è fatturata dal Provider configurato.

Configurare OmniaKey in DeepSeek Harness

I valori completi prima dei passaggi dettagliati:

Il suffisso /v1 fa parte della Base URL. Non usare solo l'origine, non duplicare /v1/v1 e non incollare il path completo /chat/completions. Harness aggiunge da solo l'operation path.

1. Installare e avviare DeepSeek Harness

Installa Node.js, apri un terminale nella project directory che l'agent deve vedere ed esegui il quick start ufficiale:

npx @deepseek-ai/dsh web

Il comando attuale avvia la Web UI su:

http://127.0.0.1:3080

Se 3080 è occupata, scegli un'altra porta:

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

La directory di avvio di dsh diventa la posizione filesystem predefinita. Il composer resta però indisponibile finché non aggiungi e selezioni un workspace nella UI. Scegli il repository consapevolmente: l'agent può ricevere file e shell tools secondo la permission policy attiva.

2. Creare una API key OmniaKey dedicata

Apri il dashboard API Keys OmniaKey e crea una chiave solo per DeepSeek Harness. Una chiave separata è più facile da limitare, ruotare, revocare e auditare rispetto a una credential condivisa.

Non mettere la chiave in chiaro in repository, shell history, screenshot, issue o chat log. La Web UI tratta le chiavi salvate come write-only. DeepSeek documenta che il secret è in $DSH_HOME/.credentials.yaml, mentre settings conserva soltanto la credential reference e la pagina riceve un descriptor mascherato.

3. Aggiungere OmniaKey come custom provider

In una nuova installazione, accetta Internal Testing Notice con Continue. Il dialogo successivo chiede una chiave DeepSeek ufficiale; scegli Configure later, perché OmniaKey va configurato come custom provider e non in quella route integrata.

In DeepSeek Harness apri Settings → Models, scegli Add a custom provider e inserisci:

1. Provider ID: omniakey, iniziando con una lettera minuscola.
2. Display name: OmniaKey.
3. Base URL: https://api.omniakey.com/v1.
4. API protocol: openai-completions.
5. API key: la chiave OmniaKey appena creata.

Il Provider ID è permanente perché viene usato da sessions, defaults, requests e credential references. Display name, Base URL, protocol, credential e model list restano modificabili.

4. Recuperare e selezionare i modelli

Sotto Model catalog, scegli Fetch available models. Per un Custom Provider OpenAI-compatible, lo strumento invia con Bearer authentication un GET /models alla Base URL attuale. Con questa configurazione chiama GET /v1/models di OmniaKey.

Seleziona solo i modelli che userai. Questi due ID sono buoni punti di partenza:

Lo stesso Provider può usare anche i modelli Claude, GPT, Gemini, Grok e GLM attualmente supportati da OmniaKey. Copia gli ID esatti dal catalogo live; il model name è un identifier preciso, non un alias approssimativo.

Se discovery non è disponibile, aggiungi manualmente il Model ID corretto. dsh richiede almeno un modello per creare il custom Provider.

5. Scegliere il workspace e verificare in sicurezza

Salva il Provider, seleziona il progetto con Choose workspace, crea una nuova session e scegli OmniaKey / deepseek-v4-pro oppure OmniaKey / deepseek-v4-flash.

Inizia con un task read-only molto ristretto:

Ispeziona package.json e riassumi gli scripts disponibili. Non modificare file e non eseguire comandi.

Questo test conferma workspace, Provider, chiave, Model ID esatto e response path prima di consentire edit o shell. Una risposta testuale non dimostra tutti i formati di tool call; prova poi un task reversibile prima di assegnare un grande refactor.

I Model Settings entrano in vigore alla request successiva senza riavvio. Una session che ha già inviato una richiesta conserva però il modello registrato nel proprio log. Dopo un cambio Provider o modello, usa una nuova session per un test chiaro.

Opzionale: configurare OmniaKey in settings.yaml

La Web UI è più chiara al primo utilizzo. In un ambiente locale controllato, $DSH_HOME/settings.yaml può definire il Provider facendo riferimento a una environment variable, senza incorporare la chiave:

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 chiave deve esistere nell'ambiente del processo Harness. Non sostituire apiKeyEnv con un literal secret in settings.yaml. La reference ufficiale dsh-llm-pi-ai consiglia credential references per non inserire secret nel documento settings.

Perché usare OmniaKey con DeepSeek Harness?

DeepSeek Harness supporta già custom gateway; OmniaKey trasforma questo extension point in una singola voce Provider riutilizzabile.

• Una configurazione per più famiglie. Cambia il Model ID esatto nel picker senza creare un profilo per ogni vendor.
• Model discovery. Harness può leggere la lista OpenAI-compatible di OmniaKey invece di farti digitare gli ID a memoria.
• Controlli operativi separati. Assegna a Harness API key, quota, ciclo di rotazione e usage trail propri.
• Identità esplicita del modello. OmniaKey non usa silent model substitution: Provider e modello richiesti vengono eseguiti; un upstream non disponibile restituisce un errore visibile.
• Pagamento dell'uso API, non un altro abbonamento agent. OmniaKey usa saldo prepaid e billing per token; availability e rate restano nel catalogo.

Questo non rende OmniaKey sempre migliore di una chiave DeepSeek diretta. Se ti servono solo account ed endpoint nativi, il Direct Provider è sensato. OmniaKey è utile quando la stessa installazione Harness deve usare più famiglie selezionate con una chiave e una Base URL.

Troubleshooting

Fetch available models restituisce 401

Controlla che la chiave provenga da OmniaKey, non abbia spazi, sia attiva e sia associata esattamente a https://api.omniakey.com/v1. Model discovery usa Bearer authentication.

Il Provider restituisce 404

Verifica prima la Base URL. Errori comuni: omettere /v1, duplicarlo o usare https://api.omniakey.com/v1/chat/completions come Base URL.

UNKNOWN_MODEL

Il modello scelto non è nella lista salvata del custom Provider. Recupera di nuovo i modelli oppure aggiungi l'ID esatto dal catalogo OmniaKey, poi selezionalo in una nuova session.

MISSING_CREDENTIAL

Salva la chiave tramite Settings → Models oppure assicurati che OMNIAKEY_API_KEY esista nella shell che avvia DeepSeek Harness. Impostare la variabile in un altro terminale non aggiorna un processo già in esecuzione.

Il modello cambiato non sembra attivo

Avvia una nuova session. Le session esistenti conservano Provider e modello nell'append-only log dopo la prima request.

Il testo funziona ma un agent tool fallisce

Text generation e uso strutturato dei tools sono controlli diversi. Inizia con un task read-only, esamina l'errore nella Trajectory view e solo dopo aumenta limiti o permissions. Un tool call malformato non si risolve ruotando una API key valida.

Domande frequenti

DeepSeek Harness è gratuito?

Il source code usa MIT license. L'inference del modello è separata e può causare costi API tramite DeepSeek, OmniaKey o un altro Provider.

DeepSeek Harness può usare DeepSeek V4 Pro tramite OmniaKey?

Sì. Aggiungi OmniaKey come custom Provider openai-completions e seleziona l'ID esatto deepseek-v4-pro. deepseek-v4-flash è disponibile anche come route meno costosa.

Per la release 0813, i prezzi peak/off-peak e gli esempi di costo, leggi la guida ai prezzi API DeepSeek V4 Pro (English). La route Flash più recente, native vision, benchmark e stato attuale di V4 Pro sono nella recensione DeepSeek V4.1 Flash.

Devo incollare la chiave OmniaKey nella card DeepSeek integrata?

Usa Add a custom provider. La Built-in Card configura la route ufficiale DeepSeek; il form personalizzato è il percorso documentato per un gateway e mostra Base URL, protocol e model list.

Lo stesso Provider può usare Claude, GPT o Gemini?

Sì, se l'interfaccia OpenAI-compatible di OmniaKey supporta attualmente il modello. Recupera la lista live e aggiungi gli ID esatti. Le funzionalità di protocollo possono variare; verifica il comportamento tools con il modello scelto.

Dove viene salvata la API key?

Le chiavi salvate nella pagina Models sono write-only e si trovano in $DSH_HOME/.credentials.yaml; settings conserva la credential reference. Per YAML diretto usa apiKeyEnv e l'ambiente del processo.

DeepSeek Harness è pronto per un workflow production stabile?

Oggi va trattato come target di valutazione. DeepSeek lo chiama esplicitamente developer preview e avverte di compatibility-breaking changes. Blocca le versioni, salva la configurazione senza secret e ricontrolla la guida dopo gli upgrade.

Fonti verificate

• 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