DeepSeek Harness

Settings → Models → “Add model provider” → “Custom model API” recebe cinco campos — Provider ID, display name, base URL, API protocol e API key — e coloca Claude e GPT no mesmo seletor do cartão DeepSeek integrado.

# 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 a passo

1. Crie uma chave em /app/keys e copie-a — ela é exibida uma única vez.
2. Inicie a interface Web (dsh web) e acesse Settings → Models. Selecione Add model provider. O cartão abre em Third-party model provider, que lista apenas os provedores incluídos no dsh — altere para Custom model API.
3. Preencha Provider ID (em letras minúsculas e permanente — a documentação informa que as solicitações, as sessões salvas, os padrões de modelo e as referências às credenciais usam esse ID; para renomeá-lo, é preciso adicionar um novo provedor e excluir o antigo), nome de exibição, URL base https://api.kunavo.com/v1, protocolo da API OpenAI Chat Completions e chave de API. A chave é somente para gravação; o dsh a mantém em $DSH_HOME/.credentials.yaml e armazena no perfil apenas uma referência a ela.
4. Em Model catalog, selecione Fetch available models — Kunavo responde com GET /v1/models, então a lista é preenchida automaticamente. Marque os modelos que quiser e selecione Add selected. Também funciona digitar os IDs manualmente, e a documentação recomenda fazer isso sempre que a descoberta não listar nenhum modelo.
5. Opcional: para usar IDs Claude com o protocolo próprio da Anthropic, adicione uma segunda API de modelo personalizada com seu próprio Provider ID, URL base https://api.kunavo.com — sem /v1 —, protocolo da API Anthropic Messages e a mesma chave. A busca também lista o catálogo completo aqui; adicione apenas os IDs claude- (saiba por que apenas esses).
6. Escolha um modelo no compositor e envie uma mensagem que envolva um arquivo, não apenas uma saudação — o harness depende de chamadas de ferramentas para a maior parte do que faz, então uma primeira execução que leia e edite algo informa mais. As alterações de modelo entram em vigor na próxima solicitação; a documentação afirma explicitamente que não é necessário reiniciar.

Verificado em a página “Configure models” do DeepSeek Harness (o mesmo texto de docs/user/guide/providers.md na tag dsh-v0.2.0-rc.2) em 1 de outubro de 2026. As configurações de terceiros podem mudar; se o nome de um campo aqui já não corresponder ao que você vê, aquela página é a autoridade, não esta.

Verifique antes de depurar o cliente

Uma solicitação determina se a falha está no endpoint, na chave ou no arquivo de configuração. Se isto retornar JSON, a mesma URL base e a mesma chave funcionarão em 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-..."

Qual ID de modelo inserir no campo

Todo modelo de texto pode ser acessado como um ID de modelo — a lista atual está em GET /v1/models, e o catálogo com preços está na página de modelos. As tarifas são em USD por 1 milhão de tokens, entrada / saída.

Claude por meio de Anthropic Messages

Kunavo também responde à API Anthropic Messages, e anthropic-messages é um dos três protocolos oferecidos pelo formulário. A documentação do harness é clara: “Um provedor usa um protocolo; portanto, um gateway que oferece dois precisa de dois provedores” — trata-se de um segundo provedor ao lado do primeiro, não de uma configuração dele.

• URL base https://api.kunavo.com, a raiz sem caminho. Na execução, essa raiz enviou uma solicitação para /v1/messages?beta=true — o caminho que o Claude Code também usa e que a Kunavo responde. Com /v1 no final, a solicitação foi enviada para /v1/v1/messages. DeepSeek Harness e Claude Code compara lado a lado as solicitações dos dois clientes.
• Apenas IDs Claude. A /v1/messages da Kunavo atende IDs claude-, e nenhum outro; um ID gpt- recebe um 404 que especifica /v1/chat/completions. Mantenha GPT no provedor openai-completions.
• A busca lista todos os modelos; adicione apenas os modelos Claude. O README do dsh em llm-pi-ai informa que a descoberta neste protocolo consulta GET /v1/models com o cabeçalho x-api-key da Anthropic, e a lista de modelos da Kunavo aceita a chave nesse cabeçalho, assim como em Authorization: Bearer — isso se baseia no código-fonte do dsh e nos próprios testes da Kunavo, não na execução. O resultado de Fetch available models é o catálogo completo, incluindo GPT e modelos de imagem; portanto, marque apenas os IDs claude-. Digitar os IDs manualmente funciona da mesma forma. Uma lista completa confirma menos do que parece: o mesmo README diz que a URL de listagem é aceita com ou sem /v1, enquanto as solicitações de modelo usam a URL base sem alterações — portanto, Fetch também preenche a lista a partir de https://api.kunavo.com/v1, mas a primeira mensagem enviada usando essa URL base vai para /v1/v1/messages.
• O que isso permite. A solicitação chega no formato da Anthropic — na execução, o prompt do sistema foi enviado no campo de nível superior system, então a função developer não entra em questão —, e a Kunavo o repassa como está, em vez de traduzi-lo do formato OpenAI. O provedor openai-completions alcança os mesmos IDs Claude por meio de tradução, e é por isso que ele é usado nas etapas.

O arquivo usado pelo formulário

A página Models grava $DSH_HOME/profiles/<profile>/cordis.patch.yml — $DSH_HOME/profiles/web/cordis.patch.yml quando você começa com dsh web. A documentação antiga do dsh apontava para $DSH_HOME/settings.yaml; a documentação da versão 0.2.0-rc.2, não. Quando o navegador está na mesma máquina que o servidor, Open configuration file no cabeçalho Settings abre o arquivo, e os adaptadores o leem novamente na próxima solicitação. Cinco detalhes importam para este endpoint:

1. Janela de contexto e máximo de tokens de saída — no formulário, em Customized settings → Model options. Um ID digitado manualmente não inclui nenhum dos dois, então se aplicam os valores padrão da rota: 262,144 tokens de contexto e 32,768 de saída, segundo o README do llm-pi-ai — e, na execução, os dois provedores personalizados solicitaram exatamente max_tokens: 32768. Todos os IDs na tabela acima aceitam valores maiores; confira a linha correspondente e aumente os limites usando a entrada do catálogo do modelo se quiser mais. A Kunavo cobra pelos tokens que o modelo gera, não pelo limite.
2. compat.supportsDeveloperRole — não é necessário. O harness recomenda essa opção para gateways que rejeitam a função developer; Kunavo interpreta essa função como a mensagem de sistema em todas as famílias, inclusive Claude. (Até 2026-09-30, o caminho do Claude a descartava, e este item orientava a ativar a opção — não há problema em deixá-la ativada.)
3. compat.maxTokensField — deixe como está. O harness combina essa opção com a opção acima como solução inicial habitual, mas o próprio manipulador da Kunavo lê max_completion_tokens e usa max_tokens como alternativa; assim, o valor padrão já funciona.
4. reasoningEfforts — nenhum campo no formulário. Um modelo inserido manualmente não declara níveis, então o menu Effort não aparece, e o valor padrão do próprio endpoint determina se o modelo raciocina. Declare os níveis você mesmo se quiser o menu; em openai-completions, cada chave é um nível e seu valor é a grafia enviada como reasoning_effort. Isso funciona para um ID gpt-; em um ID claude-, não tem efeito, porque a interface de chat da Kunavo não encaminha reasoning_effort para a Anthropic (/docs/chat#reasoning).
5. Tipos de entrada (input: [text, image] no arquivo) — a documentação deixa claro que isso “declara algo sobre seu endpoint, em vez de verificá-lo”. Marcar Image para um ID que não aceita imagens não é detectado pelo harness; a solicitação só é recusada mais adiante. Confira o ID em /models antes de marcar a opção.

O restante do que uma sessão envia — 24 definições de ferramentas por turno, uma solicitação curta de título para cada sessão nova e os campos adicionais na rota própria do DeepSeek — está contabilizado em Preços do DeepSeek Harness.