DeepSeek Harness

Settings → Models → “Add model provider” → “Custom model API” richiede cinque campi — Provider ID, display name, base URL, API protocol e API key — e inserisce Claude e GPT nello stesso selettore della scheda DeepSeek integrata.

# Settings → Models → Add model provider → Custom model API
#
#   Provider ID     kunavo          (lowercase, and permanent)
#   display name    Kunavo
#   base URL        https://api.kunavo.com/v1
#   API protocol    OpenAI Chat Completions   (openai-completions)
#   API key         sk-kn-...
#
# Then Model catalog → Fetch available models → Add selected,
# or type the ids by hand. The page writes the active profile's
# $DSH_HOME/profiles/<profile>/cordis.patch.yml — profile "web" under
# `dsh web`. The same provider there, plus an optional second one
# that sends Claude ids over Anthropic Messages, whose base URL has
# NO /v1. This entry replaces the whole llm-pi-ai config: keep any
# provider already in it.

- id: llm-pi-ai
  config:
    providers:
      kunavo:
        apiKeyEnv: KUNAVO_API_KEY
        api: openai-completions
        baseURL: https://api.kunavo.com/v1   # → /v1/chat/completions
        models:
          - id: claude-sonnet-5
          - id: claude-opus-5
          - id: claude-haiku-4-5
          - id: gpt-5-6-sol
      kunavo-claude:
        apiKeyEnv: KUNAVO_API_KEY
        api: anthropic-messages
        baseURL: https://api.kunavo.com      # → /v1/messages
        models:
          - id: claude-sonnet-5
          - id: claude-haiku-4-5

Passo dopo passo

1. Crea una chiave su /app/keys e copiala: viene mostrata una sola volta.
2. Avvia la Web UI (dsh web) e vai a Impostazioni → Modelli. Seleziona Aggiungi provider di modelli. La scheda si apre su Provider di modelli di terze parti, che elenca solo i provider inclusi in dsh; seleziona API di modello personalizzata.
3. Compila ID provider (in minuscolo e permanente: la documentazione spiega che richieste, sessioni salvate, impostazioni predefinite dei modelli e riferimenti alle credenziali lo usano tutti; per rinominarlo occorre aggiungere un nuovo provider ed eliminare quello vecchio), nome visualizzato, URL di base https://api.kunavo.com/v1, protocollo API OpenAI Chat Completions e chiave API. La chiave è di sola scrittura; dsh la conserva in $DSH_HOME/.credentials.yaml e nel profilo memorizza solo un riferimento a essa.
4. In Catalogo modelli, seleziona Recupera i modelli disponibili: Kunavo risponde a GET /v1/models, quindi il selettore si compila automaticamente. Seleziona quelli che vuoi e scegli Aggiungi selezionati. Gli ID inseriti manualmente funzionano altrettanto bene e la documentazione consiglia di usarli come alternativa ogni volta che la ricerca non restituisce alcun risultato.
5. Facoltativo: per gli ID Claude tramite il protocollo nativo di Anthropic, aggiungi una seconda API di modello personalizzata con un proprio ID provider, URL di base https://api.kunavo.com — senza /v1 — protocollo API Anthropic Messages e la stessa chiave. Anche qui Recupera elenca l'intero catalogo; aggiungi solo gli ID claude- (perché solo quelli).
6. Seleziona un modello nel compositore e invia un turno che interagisca con un file, non un semplice saluto: l'harness si basa sulle chiamate agli strumenti per gran parte delle sue funzioni, quindi una prima esecuzione che legge e modifica qualcosa ti darà più informazioni. Le modifiche al modello hanno effetto dalla richiesta successiva; la documentazione specifica che non è necessario riavviare.

Verificato rispetto a la pagina di DeepSeek Harness “Configure models” (lo stesso testo di docs/user/guide/providers.md nel tag dsh-v0.2.0-rc.2) il 1 ottobre 2026. Le impostazioni di terze parti cambiano; se il nome di un campo qui non corrisponde più a quello visualizzato, fa fede quella pagina, non questa.

Verifica prima di eseguire il debug del client

Una sola richiesta stabilisce se il problema riguarda l'endpoint, la chiave o il file di configurazione. Se restituisce JSON, lo stesso base URL e la stessa chiave funzionano in DeepSeek Harness.

# 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-..."

Quale model id inserire nel campo

Ogni modello di testo è raggiungibile come model id: l'elenco aggiornato è GET /v1/models e il catalogo con i prezzi è nella pagina dei modelli. Le tariffe sono in USD per 1M di token, input / output.

Claude tramite Anthropic Messages

Kunavo risponde anche all'API Anthropic Messages e anthropic-messages è uno dei tre protocolli offerti dal modulo. La documentazione dell'harness è chiara: “Un provider usa un solo protocollo, quindi un gateway che ne offre due richiede due provider”. Si tratta quindi di un secondo provider accanto al primo, non di un'impostazione del primo.

• URL di base https://api.kunavo.com, la radice senza percorso. Nell'esecuzione, quella radice ha inviato la richiesta a /v1/messages?beta=true: il percorso usato anche da Claude Code e a cui Kunavo risponde. Con /v1 alla fine, la richiesta è stata inviata a /v1/v1/messages. DeepSeek Harness e Claude Code a confronto mostra affiancate le richieste dei due client.
• Solo ID Claude. L'/v1/messages di Kunavo supporta gli ID claude- e nient'altro; un ID gpt- genera una 404 che indica /v1/chat/completions. Mantieni GPT sul provider openai-completions.
• Recupera elenca tutti i modelli; aggiungi solo quelli Claude. Il README di dsh llm-pi-ai spiega che la ricerca tramite questo protocollo invia una richiesta GET /v1/models con l'header Anthropic x-api-key e che l'elenco dei modelli di Kunavo accetta la chiave in quell'header, così come in Authorization: Bearer: queste informazioni provengono dal codice sorgente di dsh e dai test di Kunavo, non dall'esecuzione. Il risultato di Recupera i modelli disponibili è l'intero catalogo, inclusi GPT e i modelli di immagini, quindi seleziona solo gli ID claude-; inserirli manualmente funziona altrettanto bene. Un elenco completo dimostra meno di quanto sembri: lo stesso README dice che l'URL di elenco viene accettato con o senza /v1, mentre le richieste dei modelli usano l'URL di base così com'è. Pertanto, Recupera compila l'elenco anche da https://api.kunavo.com/v1, ma il primo turno inviato usando quell'URL di base va a /v1/v1/messages.
• A cosa serve. La richiesta arriva nel formato Anthropic: nell'esecuzione, il prompt di sistema è stato trasmesso nel campo di primo livello system, quindi il ruolo developer non entra in gioco; Kunavo la inoltra così com'è, senza convertirla dal formato OpenAI. Il provider openai-completions raggiunge gli stessi ID Claude tramite traduzione: ecco perché è quello usato nei passaggi.

Il file dietro il modulo

La pagina Modelli scrive in $DSH_HOME/profiles/<profile>/cordis.patch.yml — $DSH_HOME/profiles/web/cordis.patch.yml quando si inizia da dsh web. La documentazione precedente di dsh indicava $DSH_HOME/settings.yaml; quella della versione 0.2.0-rc.2 no. Quando il browser si trova sulla stessa macchina del server, Apri file di configurazione nell'intestazione delle Impostazioni lo apre, e gli adattatori lo rileggono alla richiesta successiva. Per questo endpoint contano cinque cose:

1. Finestra di contesto e token di output massimi — nel modulo, in Impostazioni personalizzate → Opzioni del modello. Un ID inserito manualmente non include nessuno dei due valori, quindi si applicano i valori predefiniti del percorso: 262,144 token di contesto e 32,768 di output, secondo il README di llm-pi-ai; nell'esecuzione, entrambi i provider personalizzati hanno richiesto esattamente max_tokens: 32768. Tutti gli ID nella tabella sopra richiedono valori superiori; controlla la riga in ogni caso e, se vuoi valori più alti, aumentali in base alla voce del catalogo del modello. Kunavo addebita i token generati dal modello, non il limite massimo.
2. compat.supportsDeveloperRole — non serve. L'harness lo consiglia per i gateway che rifiutano il ruolo developer; Kunavo interpreta quel ruolo come il turno di sistema per ogni famiglia, Claude incluso. (Fino al 2026-09-30, il percorso Claude lo eliminava e questa voce consigliava di attivare l'interruttore: lasciarlo attivo non causa problemi.)
3. compat.maxTokensField — lascialo invariato. L'harness lo abbina all'interruttore sopra come prima soluzione abituale, ma il gestore di Kunavo legge max_completion_tokens e ripiega su max_tokens, quindi il valore predefinito funziona già.
4. reasoningEfforts — il modulo non ha un campo per questo. Un modello inserito manualmente non dichiara livelli, quindi il menu Effort non appare e il valore predefinito dell'endpoint determina se il modello esegue il ragionamento. Dichiara tu i livelli se vuoi il menu; in openai-completions ogni chiave è un livello e il relativo valore è la forma inviata come reasoning_effort. Questo raggiunge un ID gpt-; non ha effetto su un ID claude-, perché l'interfaccia chat di Kunavo non inoltra reasoning_effort ad Anthropic (/docs/chat#reasoning).
5. Tipi di input (input: [text, image] nel file): la documentazione chiarisce che questo “dichiara una caratteristica del tuo endpoint, invece di verificarla”. Se selezioni Immagine per un ID che non accetta immagini, l'harness non rileva l'incompatibilità; la richiesta viene rifiutata più avanti. Controlla l'ID su /models prima di selezionare la casella.

Il resto dei dati inviati da una sessione — 24 definizioni di strumenti per turno, una breve richiesta di titolo per ogni nuova sessione e i campi aggiuntivi sul percorso DeepSeek — è conteggiato in Prezzi di DeepSeek Harness.