Documentação

Documentação

Nanocoder

O Nanocoder trata um endpoint remoto da mesma forma que trata o Ollama: uma entrada em nanocoder.providers com nome, URL base, chave e lista de modelos. sdkProvider usa openai-compatible por padrão, então não é necessário declarar mais nada.

Uma entrada Custom Provider em nanocoder.providers, no arquivo agents.config.json — name, baseUrl, apiKey, models — sem necessidade de uma linha sdkProvider, pois o padrão é openai-compatible.

agents.config.json
{
  "nanocoder": {
    "providers": [
      {
        "name": "Kunavo",
        "baseUrl": "https://api.kunavo.com/v1",
        "apiKey": "${KUNAVO_API_KEY}",
        "models": ["claude-sonnet-5", "claude-haiku-4-5", "gpt-5-6-sol"]
      }
    ]
  }
}
A Kunavo não executou o Nanocoder com este endpoint. Todos os campos acima foram transcritos da própria página Custom Provider do Nanocoder, não de uma sessão concluída por alguém daqui — esta é uma referência de configuração, não um teste de compatibilidade. Primeiro execute uma tarefa pequena e limitada e mantenha outra opção disponível enquanto isso.
A URL base mantém o sufixo /v1. A documentação do Nanocoder esclarece isso por meio de exemplos, não de uma regra: a tabela de campos descreve baseUrl apenas como “URL do endpoint da API”, mas o exemplo da própria página Custom Provider é "baseUrl": "https://my-api.example.com/v1", e todas as páginas de provedores compatíveis com OpenAI no site fazem o mesmo — https://openrouter.ai/api/v1, http://localhost:11434/v1. Se remover o sufixo, a falha será um 404 na rota, não um 401 na chave.
sdkProvider foi omitido acima de propósito — a tabela de campos diz que ele “usa openai-compatible por padrão”, que é o formato transmitido pela rede ao qual a Kunavo responde aqui. Os outros valores documentados (google, anthropic, github-copilot) selecionam um SDK diferente, e nenhum deles é necessário para acessar um endpoint de chat completions.
Três consultas determinam qual configuração prevalece, nesta ordem: NANOCODER_PROVIDERS (ou NANOCODER_PROVIDERS_FILE), depois agents.config.json no diretório de trabalho e, por fim, a configuração por usuário — ~/Library/Preferences/nanocoder/ no macOS, ~/.config/nanocoder/ no Linux e %APPDATA%\nanocoder\ no Windows. A primeira encontrada prevalece, e definir NANOCODER_CONFIG_DIR ignora completamente as consultas ao projeto e ao diretório pessoal. Se a chave editada não for a chave enviada, verifique essa ordem de precedência.
Ainda não tem uma chave? Crie uma conta na Kunavo, gere uma chave (ela começa com sk-kn-) e adicione crédito a partir de $10 — as chamadas são pagas com esse saldo, e chamadas malsucedidas não são cobradas. O painel então abre na configuração de Nanocoder.

Passo a passo

  1. Crie uma chave em /app/keys e copie-a — ela só é exibida uma vez. Exporte-a como KUNAVO_API_KEY em vez de colá-la no arquivo: o Nanocoder substitui $VAR, ${VAR} e ${VAR:-default} recursivamente em todas as strings de uma entrada de provedor e lê .env do diretório de trabalho.
  2. Execute /settings providers dentro do Nanocoder e escolha Custom Provider. O assistente solicita, nesta ordem, Provider name, Base URL, API key (optional), Model names e Request timeout, e oferece buscar a lista de modelos no endpoint — a Kunavo responde GET /v1/models, então essa busca é preenchida automaticamente.
  3. Ou ignore o assistente e escreva você mesmo agents.config.json usando o bloco acima. Observe que as configurações são resolvidas arquivo por arquivo: um arquivo no nível do projeto que define nanocoder.providers fornece o bloco inteiro, portanto as entradas da configuração global não são mescladas a ele.
  4. Defina uma janela de contexto. O Nanocoder resolve o limite nesta ordem: /context-max, depois contextWindows[model], contextWindow, NANOCODER_CONTEXT_LIMIT e, por fim, models.dev — e a Kunavo não é um provedor de models.dev; portanto, sem um dos quatro primeiros, o cálculo usa um valor alternativo que não corresponde ao seu modelo. Os números estão em /models.
  5. Abra /model, escolha um dos IDs listados — o seletor os mostra sob o name informado — e execute algo pequeno que precise chamar uma ferramenta. Se as chamadas de ferramenta retornarem em formato inválido em um modelo específico, disableToolModels permite desativá-las por modelo, em vez de por provedor.

Verificado em Página Custom Provider do Nanocoder em 21 de setembro 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.

Esta é a versão resumida. O guia completo — escolha do modelo, custo de uma sessão real e modos de falha — está em Nanocoder vs OpenCode — quanto cada um custa além do bloco do provedor.

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 Nanocoder.

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

ID do modeloEntrada / saída da KunavoOnde se encaixa em Nanocoder
claude-sonnet-5$1.40 / $7.00o modelo de trabalho padrão para o ciclo de edição e execução de um agente de terminal
claude-haiku-4-5$0.70 / $3.50sessões longas com muitas ferramentas e triagem rápida de arquivos, em que o número de turnos determina a maior parte do custo
gpt-5-6-sol$2.00 / $12.00uma segunda opinião de outra família usando a mesma chave
claude-opus-5$3.50 / $17.50a única refatoração complexa de uma sessão, em que um plano incorreto custa caro
A cobrança é por token, usando um saldo pré-pago e sem tarifa mensal — consulte billing. Em contextos repetidos — que representam a maior parte do que um editor ou cliente de chat envia — o cache de prompt altera a conta mais do que a escolha do modelo.

Perguntas frequentes

O Nanocoder oferece suporte a um endpoint de API personalizado?

Sim, é um recurso oficial documentado, não um campo sem documentação. A própria página “Custom Provider” do Nanocoder declara que qualquer serviço que exponha uma API compatível com OpenAI pode ser adicionado como provedor personalizado e mostra o objeto a ser configurado: name, baseUrl, apiKey e models. Você pode adicioná-lo interativamente com o assistente /settings providers ou manualmente em agents.config.json. Essa era a documentação em 21 de setembro de 2026.

Onde insiro a chave de API do Nanocoder?

No campo apiKey da entrada do provedor em agents.config.json. O Nanocoder aplica recursivamente a substituição de variáveis de ambiente aos campos de string nas configurações do provedor; portanto, a forma mais segura é "apiKey": "${KUNAVO_API_KEY}", com o valor exportado no shell ou em um arquivo .env no diretório de trabalho. As substituições por NANOCODER_PROVIDERS têm a precedência mais alta, seguidas por agents.config.json no nível do projeto e, depois, pelo arquivo por usuário. Portanto, uma edição que parece não surtir efeito geralmente está sendo sobrescrita por uma configuração anterior nessa ordem.

A baseUrl do Nanocoder precisa terminar com /v1?

Para um endpoint compatível com OpenAI, sim — por exemplo, https://api.kunavo.com/v1. A documentação do Nanocoder não declara em texto uma regra sobre o sufixo; sua tabela de campos descreve baseUrl apenas como a URL do endpoint da API. A questão é esclarecida por exemplo: a amostra da própria página Custom Provider usa https://my-api.example.com/v1, e todas as páginas de provedores compatíveis com OpenAI no site incluem o mesmo sufixo. A ausência de /v1 resulta em um 404 na rota, não em um erro de autenticação.

Por que o Nanocoder não mostra nenhum custo ou informa o tamanho de contexto errado para esses modelos?

Porque o Nanocoder lê os metadados dos modelos em models.dev, e um gateway de terceiros que não esteja listado não tem uma entrada lá. A ordem documentada para definir o limite de contexto é /context-max ou --context-max, depois contextWindows[model], depois contextWindow, depois NANOCODER_CONTEXT_LIMIT e, por fim, models.dev; portanto, defina um dos quatro primeiros na entrada do provedor para que o medidor volte a ficar correto. Em qualquer caso, o valor de custo por resposta é calculado pelo próprio cliente com base nos tokens informados — compare-o com o registro de uso do seu provedor, não com o rodapé.