DeepSeek Harness: instalação e conexão com API

DeepSeek Harness é um agente de programação open source e agent runtime da DeepSeek AI. Ele fornece loop, tools, acesso ao workspace, sessions, permissões e interface ao redor de um modelo. O modelo continua vindo de um API Provider. Este tutorial explica primeiro o que o DeepSeek code harness faz e depois o conecta à OmniaKey pelo fluxo oficial de custom provider.

O que é DeepSeek Harness?

DeepSeek Harness, abreviado como dsh, não é um novo modelo de linguagem. É o software que transforma um modelo em agent capaz de entender um workspace, chamar tools, editar arquivos, executar comandos, preservar sessions e pedir aprovação.

Algumas notícias o chamam de framework open source de agentes de IA. Os materiais oficiais são mais específicos: open-source agent harness, agente de programação extensível local-first e ambiente de desenvolvimento/runtime para agents.

O princípio central é everything is a plugin. Construído sobre Cordis, o projeto permite substituir ou recompor por configuração models, tools, skills, sessions, sandboxes, storage, loops, scheduling e até a UI.

O event stream rastreável é mais do que histórico de chat. A documentação descreve resume, fork, search e replay como operações no mesmo session log, útil quando um agent faz vários tool calls antes de responder.

O que DeepSeek Harness não é

• Não é DeepSeek V4 Pro nem outro modelo. Harness e modelo são camadas separadas.
• Ainda não é uma release estável de production. A DeepSeek o marca como developer preview e avisa que haverá mudanças incompatíveis.
• No quick start npm, não é um serviço de coding hospedado. A Web UI usa local loopback por padrão.
• Open source não torna inference gratuita. O repositório usa MIT license, enquanto a API é cobrada pelo Provider configurado.

Configuração da OmniaKey no DeepSeek Harness

Os valores completos antes das etapas:

O sufixo /v1 faz parte da Base URL. Não use só a origem, não duplique como /v1/v1 e não cole o caminho completo /chat/completions. O Harness acrescenta o operation path.

1. Instalar e iniciar o DeepSeek Harness

Instale Node.js, abra um terminal no diretório do projeto que o agent deve ver e execute o quick start oficial:

npx @deepseek-ai/dsh web

O comando atual inicia a Web UI em:

http://127.0.0.1:3080

Se 3080 estiver ocupada, escolha outra porta:

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

O diretório onde dsh é iniciado vira o local padrão no filesystem. Porém o composer fica indisponível até você adicionar e selecionar um workspace na UI. Escolha deliberadamente o repositório; o agent pode receber file e shell tools conforme a permission policy ativa.

2. Criar uma chave API OmniaKey dedicada

Abra o dashboard de API Keys da OmniaKey e crie uma chave só para o DeepSeek Harness. Uma chave separada é mais fácil de limitar, rotacionar, revogar e auditar do que uma credencial compartilhada.

Não coloque a chave em texto puro em repositórios, histórico do shell, screenshots, issues ou chats. A Web UI trata chaves salvas como write-only. A DeepSeek documenta que o segredo fica em $DSH_HOME/.credentials.yaml, enquanto settings guarda apenas a credential reference e a página recebe um descriptor mascarado.

3. Adicionar a OmniaKey como custom provider

Em uma instalação nova, aceite Internal Testing Notice com Continue. O diálogo seguinte pede uma chave oficial DeepSeek; escolha Configure later, pois a OmniaKey entra em custom provider, não nessa rota integrada.

No DeepSeek Harness, abra Settings → Models, escolha Add a custom provider e preencha:

1. Provider ID: omniakey, começando com letra minúscula.
2. Display name: OmniaKey.
3. Base URL: https://api.omniakey.com/v1.
4. API protocol: openai-completions.
5. API key: a chave OmniaKey criada antes.

O Provider ID é permanente porque sessions, defaults, requests e credential references o utilizam. Display name, Base URL, protocolo, credential e lista de modelos continuam editáveis.

4. Buscar e selecionar modelos

Em Model catalog, clique em Fetch available models. Para um Custom Provider OpenAI-compatible, a ferramenta envia com Bearer authentication um GET /models à Base URL atual. Nessa configuração, chama o GET /v1/models da OmniaKey.

Selecione apenas modelos que pretende usar. Estes dois IDs são bons pontos de partida:

O mesmo Provider também pode usar Claude, GPT, Gemini, Grok e GLM atualmente suportados pela OmniaKey. Copie os IDs exatos do catálogo ao vivo; model names são identifiers exatos, não aliases aproximados.

Se o discovery falhar, adicione manualmente o Model ID correto. dsh exige ao menos um modelo para criar o custom Provider.

5. Selecionar o workspace e verificar com segurança

Salve o Provider, escolha o projeto com Choose workspace, inicie uma nova session e selecione OmniaKey / deepseek-v4-pro ou OmniaKey / deepseek-v4-flash.

Comece com uma tarefa read-only bem limitada:

Inspecione package.json e resuma os scripts disponíveis. Não edite arquivos nem execute comandos.

Esse teste confirma workspace, Provider, chave, Model ID exato e response path antes de autorizar edição ou shell. Uma resposta textual não comprova todos os formatos de tool call; teste depois uma tarefa reversível antes de delegar um grande refactor.

Model settings entram em vigor na próxima request sem reiniciar o servidor. Uma session que já enviou request mantém o modelo registrado no seu log. Após mudar Provider ou modelo, use uma nova session para um teste sem ambiguidade.

Opcional: configurar a OmniaKey em settings.yaml

A Web UI é mais clara no primeiro uso. Em um ambiente local controlado, $DSH_HOME/settings.yaml pode definir o Provider referenciando uma environment variable, sem embutir a chave:

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

A chave precisa existir no ambiente do processo Harness. Não substitua apiKeyEnv por um literal secret em settings.yaml. A referência oficial dsh-llm-pi-ai recomenda credential references para manter segredos fora do documento settings.

Por que usar OmniaKey com DeepSeek Harness?

DeepSeek Harness já aceita gateways personalizados; a OmniaKey transforma esse extension point em uma única entrada de Provider reutilizável.

• Uma configuração para várias famílias. Troque o Model ID exato no picker sem criar um perfil por vendor.
• Model discovery. Harness lê a lista OpenAI-compatible da OmniaKey em vez de exigir que você digite IDs de memória.
• Controles operacionais separados. Dê ao Harness própria chave, quota, ciclo de rotação e usage trail.
• Identidade explícita do modelo. A OmniaKey não faz silent model substitution: Provider e modelo pedidos são executados; um upstream indisponível gera erro visível.
• Pagamento por uso da API, não outra assinatura de agent. A OmniaKey usa saldo pré-pago e cobrança por token; disponibilidade e preços ficam no catálogo.

Isso não torna a OmniaKey sempre melhor que uma chave DeepSeek direta. Se você só precisa da conta e endpoint nativos, o Provider direto é adequado. A OmniaKey é útil quando a mesma instalação Harness precisa usar famílias selecionadas por uma chave e uma Base URL.

Solução de problemas

Fetch available models retorna 401

Confirme que a chave veio da OmniaKey, não tem espaços, continua ativa e está associada exatamente a https://api.omniakey.com/v1. O model discovery usa Bearer authentication.

O Provider retorna 404

Confira primeiro a Base URL. Erros comuns são omitir /v1, duplicá-lo ou usar https://api.omniakey.com/v1/chat/completions como Base URL.

UNKNOWN_MODEL

O modelo selecionado não está na lista salva do custom Provider. Busque os modelos novamente ou adicione o ID exato do catálogo OmniaKey e selecione-o em nova session.

MISSING_CREDENTIAL

Salve a chave em Settings → Models ou verifique se OMNIAKEY_API_KEY existe no shell que inicia o DeepSeek Harness. Definir a variável em outro terminal não atualiza um processo em execução.

O modelo alterado não parece ativo

Inicie uma nova session. Sessions existentes mantêm Provider e modelo no append-only log após a primeira request.

Texto funciona, mas um agent tool falha

Geração básica de texto e uso estruturado de tools são testes diferentes. Comece read-only, inspecione a falha na Trajectory view e só depois aumente limites ou permissões. Um tool call malformado não é corrigido rotacionando uma API key válida.

Perguntas frequentes

DeepSeek Harness é gratuito?

O código-fonte usa MIT license. A inference do modelo é separada e pode gerar cobrança via DeepSeek, OmniaKey ou outro Provider.

DeepSeek Harness pode usar DeepSeek V4 Pro pela OmniaKey?

Sim. Adicione a OmniaKey como custom Provider openai-completions e selecione o ID exato deepseek-v4-pro. deepseek-v4-flash também está disponível como rota mais barata.

Para a release 0813, tarifas peak/off-peak e exemplos de custo, leia o guia de preços da API DeepSeek V4 Pro (English). A route Flash mais recente, native vision, benchmarks e status atual do V4 Pro estão na análise do DeepSeek V4.1 Flash.

Devo colar a chave OmniaKey no card DeepSeek integrado?

Use Add a custom provider. O card integrado configura a rota oficial DeepSeek, enquanto o formulário personalizado é o caminho documentado para gateway e expõe Base URL, protocolo e lista de modelos.

O mesmo Provider pode usar Claude, GPT ou Gemini?

Sim, quando a superfície OpenAI-compatible da OmniaKey suportar o modelo. Busque a lista ao vivo e adicione os IDs exatos. Recursos de protocolo podem variar; teste o comportamento dos tools com o modelo escolhido.

Onde a API key fica armazenada?

Chaves salvas na página Models são write-only e ficam em $DSH_HOME/.credentials.yaml; settings mantém a credential reference. Para YAML direto, use apiKeyEnv e o ambiente do processo.

DeepSeek Harness está pronto para workflow estável de produção?

Hoje, trate-o como alvo de avaliação. A DeepSeek chama a versão explicitamente de developer preview e alerta para mudanças incompatíveis. Fixe versões, faça backup da configuração sem segredos e reveja o guia após upgrades.

Fontes verificadas

• 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