Saltar para o conteúdo principal
O DeepSeek Harness (comando dsh) é o framework de agente de programação de código aberto da DeepSeek. Ele oferece espaços de trabalho, terminal, edição de arquivos, Skills, planejamento e Web UI. A interface compatível com OpenAI Chat Completions permite conectá-lo à AIHubMix.
Este guia se baseia no DeepSeek Harness 0.2.0-rc.2, a versão mais recente em 18 de outubro de 2026. Em relação à 0.1.0-rc.6, a versão mudou de forma considerável: o local da configuração e a interface foram atualizados. O Harness ainda está em versão prévia para desenvolvedores, portanto versões futuras podem alterar campos ou detalhes da interface.

​
Resumo

A integração requer quatro valores:
AIHubMix configurada na página Models do DeepSeek Harness

​
O que é necessário?

  • Uma chave de API da AIHubMix ativa
  • Node.js 22 (22.19.0 ou posterior) ou Node.js 24 ou posterior
  • Acesso de rede ao registro npm e a https://aihubmix.com

​
Como instalar o DeepSeek Harness?

Instale a versão publicada no npm sem clonar o repositório de código-fonte:
Se aparecer dsh: command not found, execute npm config get prefix e confirme que o diretório bin correspondente está em PATH.

​
Como iniciar a Web UI?

Execute o comando no diretório que será usado como espaço de trabalho. A forma oficialmente recomendada é npx:
Se já estiver instalado globalmente, você também pode executar:
Abra http://127.0.0.1:3080 e selecione ou adicione um espaço de trabalho no primeiro uso.

​
Como configurar o provedor AIHubMix?

Abra Settings → Models → Add model provider, mude o cartão para Custom model API e informe os valores a seguir:
Formulário de provedor personalizado no DeepSeek Harness
O endpoint final é https://aihubmix.com/v1/chat/completions.
Não informe o caminho completo /chat/completions no campo Base URL.

​
Adicionar auto ou outro modelo

Depois de informar Base URL e a chave de API, abra Model catalog e selecione Fetch available models. O Harness solicita GET https://aihubmix.com/v1/models e mostra os IDs de modelo disponíveis.
Modelos da AIHubMix disponíveis no DeepSeek Harness
Para o primeiro teste, você pode adicionar apenas auto com o nome Auto. Para usar um modelo específico, marque-o na lista obtida e selecione Add selected. O seletor gráfico mostra somente modelos registrados no catálogo do Provider atual.
Adicionar manualmente o modelo auto da AIHubMix

​
Comparação entre auto e um modelo específico

As duas opções usam o mesmo Provider, Base URL e chave de API. Trocar de modelo não exige criar o provedor novamente.

​
Armazenar a chave de API em uma variável de ambiente

Em máquinas de desenvolvimento e no CI, o Harness pode ler a chave de uma variável de ambiente por meio de um arquivo de perfil. A Web UI usa o perfil web e os testes headless usam o perfil headless. Os caminhos dos arquivos são:
  • $DSH_HOME/profiles/web/cordis.patch.yml
  • $DSH_HOME/profiles/headless/cordis.patch.yml
Os dois arquivos contêm o conteúdo a seguir:
As duas entradas são obrigatórias. Se você escrever apenas llm-pi-ai e omitir agent-default-model, o modo headless continuará usando o provedor padrão deepseek-official e exibirá MISSING_CREDENTIAL.
Versões anteriores salvavam a configuração em $HOME/.dsh/settings.yaml, arquivo que a versão 0.2.0 não usa mais. Na primeira vez que o DSH 0.2.0 for iniciado, esse arquivo será migrado para um perfil e o original será renomeado para settings.yaml.imported. Essa execução de migração pode exibir MISSING_CREDENTIAL; basta executar o comando mais uma vez.
Quando a chave vem do ambiente de inicialização, a página de configurações mostra um aviso somente leitura sem revelar o valor.
Detalhes do provedor AIHubMix no DeepSeek Harness
Reinicie o Harness depois de alterar a variável.

​
Selecionar um modelo e testar uma conversa

Feche Settings e selecione Auto ou outro modelo adicionado no seletor localizado no canto inferior direito da caixa de entrada.
Auto selecionado no DeepSeek Harness
A resposta esperada confirma a conexão entre Harness, o endpoint compatível com OpenAI Chat Completions e AIHubMix.
Resposta bem-sucedida da AIHubMix no DeepSeek Harness

​
Executar um teste headless

Para testar sem a Web UI, execute o comando a seguir. Ele usa o perfil headless, portanto $DSH_HOME/profiles/headless/cordis.patch.yml precisa conter as duas entradas acima.
Uma execução bem-sucedida mostra DSH_AIHUBMIX_OK.

​
Perguntas frequentes

​
Por que aparece MISSING_CREDENTIAL?

O Harness não obteve uma configuração utilizável. Confirme que as duas entradas foram escritas no perfil e que a variável AIHUBMIX_API_KEY está definida, depois inicie o Harness no mesmo terminal:

​
Por que a busca de modelos retorna 401?

Confirme que a chave de API é válida e não contém espaços ou quebras de linha extras. A solicitação usa autenticação Bearer.

​
Por que Auto é o único modelo no seletor?

O seletor mostra somente modelos já registrados no catálogo atual do Provider. Abra Settings → Models → AIHubMix → Edit, selecione Fetch available models em Model catalog, marque os modelos desejados e selecione Add selected.

​
Por que o Harness mostra UNKNOWN_MODEL?

O catálogo atual não contém esse ID. IDs diferenciam maiúsculas e minúsculas, use o valor exato retornado pela busca.

​
Por que a conexão expira?

Verifique DNS, a rede da organização e o proxy local. O DSH lê automaticamente as variáveis HTTP_PROXY e HTTPS_PROXY. Para excluir endereços do proxy, defina NO_PROXY. Se somente o navegador usa o proxy do sistema, defina HTTP_PROXY e HTTPS_PROXY no terminal que inicia o dsh.

​
Recomendações de segurança

  • Não inclua chaves de API no Git, em capturas de tela ou scripts compartilhados
  • Use o armazenamento de credenciais do Harness ou AIHUBMIX_API_KEY
  • Não exiba a chave de API completa durante o diagnóstico
  • Use o gerenciamento de segredos da plataforma CI para injetar variáveis
Última atualização: 2026-10-18