Configuração de Coding Agents

Configurar DeepSeek Harness: API Key, Base URL e modelos

Conecte o DeepSeek Harness ao BetterToken com API Key e Base URL no perfil headless. Escolha o protocolo e teste a leitura de arquivos.

Conecte o DeepSeek Harness (dsh) ao BetterToken com um provedor personalizado no perfil headless. Nos testes no macOS, @deepseek-ai/dsh@0.2.1-rc.2 concluiu solicitações de texto e chamadas de ferramentas para leitura de arquivos nas 3 tentativas de cada combinação: Chat Completions com um modelo GPT, Responses com um modelo GPT, Anthropic Messages com um modelo Claude e Anthropic Messages com um modelo GPT.

Configurações principais

Campo	Valor
API Key	BetterToken API Key, lida da variável de ambiente cujo nome é definido em `apiKeyEnv`
Base URL	`https://bettertoken.ai/v1` — Chat Completions / Responses
Base URL para Anthropic Messages	`https://bettertoken.ai`, sem `/v1`
Modelo	`YOUR_MODEL_ID`
Arquivo de configuração	`$DSH_HOME/profiles/headless/cordis.patch.yml` (`DSH_HOME` usa `~/.dsh` por padrão)

Pré-requisitos

Node.js 24.9 ou posterior, conforme as notas oficiais de atualização para rc.2
Uma BetterToken API Key: cadastre-se e obtenha uma
Um ID de modelo copiado da model plaza

Instalação

Execute a versão testada aqui sem instalação global:

npx @deepseek-ai/dsh@0.2.1-rc.2 --help

Durante os testes, a tag npm latest apontava para 0.2.1-rc.2, uma versão candidata a lançamento. Outras tags, como next, não foram testadas.

Configuração manual

Exporte a API Key, substituindo YOUR_API_KEY:

export BETTERTOKEN_API_KEY="YOUR_API_KEY"

Crie ~/.dsh/profiles/headless/cordis.patch.yml. O arquivo contém uma lista de patches do Cordis. Substitua os dois valores YOUR_MODEL_ID pelo mesmo ID de modelo exato:

Chat Completions

- id: llm-pi-ai
  config:
    providers:
      bettertoken:
        api: openai-completions
        baseURL: https://bettertoken.ai/v1
        apiKeyEnv: BETTERTOKEN_API_KEY
        retryPolicy:
          mode: normal
          maxRetries: 2
        models:
          - id: YOUR_MODEL_ID
- id: agent-default-model
  config:
    provider: bettertoken
    model: YOUR_MODEL_ID

Responses

- id: llm-pi-ai
  config:
    providers:
      bettertoken:
        api: openai-responses
        baseURL: https://bettertoken.ai/v1
        apiKeyEnv: BETTERTOKEN_API_KEY
        retryPolicy:
          mode: normal
          maxRetries: 2
        models:
          - id: YOUR_MODEL_ID
- id: agent-default-model
  config:
    provider: bettertoken
    model: YOUR_MODEL_ID

Anthropic Messages

- id: llm-pi-ai
  config:
    providers:
      bettertoken:
        api: anthropic-messages
        baseURL: https://bettertoken.ai
        apiKeyEnv: BETTERTOKEN_API_KEY
        retryPolicy:
          mode: normal
          maxRetries: 2
        models:
          - id: YOUR_MODEL_ID
- id: agent-default-model
  config:
    provider: bettertoken
    model: YOUR_MODEL_ID

apiKeyEnv contém o nome de uma variável de ambiente, não a API Key nem uma expressão ${...}. Um provedor personalizado precisa de api, baseURL e pelo menos uma entrada em models; apenas o id do modelo é obrigatório em cada entrada. Se llm-pi-ai já estiver configurado, copie os provedores que deseja manter para o mesmo config, pois uma nova entrada substitui a existente.

O campo api aceita apenas openai-completions, openai-responses e anthropic-messages para provedores personalizados. A Base URL do Anthropic é a raiz do site, pois o cliente adiciona /v1/messages por conta própria.

Para verificar a sintaxe sem enviar uma solicitação ao modelo, execute npx @deepseek-ai/dsh@0.2.1-rc.2 --profile headless --dump-config.

Verificar a conexão

Execute no mesmo terminal:

npx @deepseek-ai/dsh@0.2.1-rc.2 --profile headless --json "Reply with only: OK"

--json imprime um evento JSON por linha. Verifique se o código de saída é 0, se turn_end.reason indica um encerramento normal e se o campo text do último evento final é igual a OK. Uma execução com falha também pode imprimir um evento final vazio; a presença do evento, por si só, não confirma o sucesso.

Para verificar o acesso a arquivos, crie sample.txt em um diretório vazio e execute nele o mesmo comando com o prompt Read sample.txt using a tool. Reply with only its exact contents.. Confirme que a saída contém um tool_call, um tool_result com o texto do arquivo e um texto final correspondente.

Trocar de modelo

Troque os dois valores YOUR_MODEL_ID por outro ID de modelo exato. Se o novo modelo usar um protocolo diferente, como um modelo Claude via Anthropic Messages, altere api e baseURL juntos. Para listar os modelos retornados pelo gateway, use Fetch available models com um provedor personalizado na interface web do DeepSeek Harness. Durante os testes, o mesmo serviço de descoberta retornou a lista de modelos do BetterToken nos três protocolos.

Erros comuns

Sintoma	O que verificar
`MISSING_CREDENTIAL`, código de saída 1 e nenhuma solicitação no painel	O processo não recebeu a variável indicada por `apiKeyEnv`. Exporte-a no terminal que inicia o `dsh` e confira a grafia. Essa verificação é local.
O perfil `headless` ignora uma Key salva na interface web	O perfil `headless` lê credenciais apenas do ambiente de inicialização, depois do `.env` no diretório atual e, por fim, do `.env` em `DSH_HOME`, nessa ordem.
`404` com o caminho da solicitação terminando em `/v1/v1/messages`	A `baseURL` do Anthropic termina em `/v1`. Use `https://bettertoken.ai`.
Modelo não encontrado	Copie novamente o ID de modelo da model plaza e use-o nos dois locais.
Muitas tentativas após uma falha	Se `retryPolicy` for omitido, o adaptador faz 5 novas tentativas por padrão. Defina `maxRetries` explicitamente, como nos exemplos.
Erro de versão do Node.js	Use Node.js 24.9 ou posterior.

Documentação relacionada

Detalhes técnicos

Nos testes, os caminhos reais das solicitações foram /v1/chat/completions, /v1/responses e /v1/messages para os três valores de api. O dsh também envia automaticamente uma solicitação para gerar o título da sessão pelo provedor e modelo configurados, portanto uma tarefa pode gerar mais de uma solicitação. O cliente adicionou os limites de saída padrão, como 32768 tokens na solicitação principal; eles não foram definidos na configuração.

Os campos input e contextWindow de uma entrada de modelo são declarações para o cliente. Eles não consultam nem comprovam os limites do gateway. A entrada de imagens não foi testada. Os testes foram realizados apenas no macOS.