Documentação

Aider

O Aider lê OPENAI_API_BASE e OPENAI_API_KEY. Aponte-as para a Kunavo, coloque openai/ antes do ID do modelo, e Claude e GPT ficam a um argumento --model de distância.

Duas variáveis de ambiente e um prefixo. Defina OPENAI_API_BASE como https://api.kunavo.com/v1, OPENAI_API_KEY como sua chave da sk-kn-… e execute o Aider com --model openai/<id>. Nada muda no repositório nem na instalação do Aider.

~/.zshrc

export OPENAI_API_BASE=https://api.kunavo.com/v1
export OPENAI_API_KEY=sk-kn-...

# The openai/ prefix is required — it tells Aider to speak the OpenAI
# protocol to OPENAI_API_BASE instead of resolving the id as a known model.
aider --model openai/claude-sonnet-5

O prefixo openai/ é obrigatório e o sufixo /v1 deve fazer parte da URL base. Se remover o prefixo, o Aider tentará resolver o ID usando sua própria tabela de provedores — gerando o erro “modelo desconhecido”. Se remover /v1, a solicitação não encontrará a rota.

Passo a passo

Crie uma chave em /app/keys e copie-a — ela é exibida uma única vez.
Exporte OPENAI_API_BASE e OPENAI_API_KEY no shell de onde você inicia o Aider ou coloque-as em ~/.aider.conf.yml, como mostrado abaixo.
Inicie o Aider no seu repositório com aider --model openai/claude-sonnet-5.
Na inicialização, o Aider exibe o modelo que resolveu. Se essa linha mostrar o ID solicitado, o endpoint está configurado corretamente.

A documentação de referência do Aider para isso está na página de APIs compatíveis com a OpenAI.

Como não incluir isso no perfil do shell

Os mesmos dois valores podem ficar no arquivo de configuração do Aider, que é o local mais adequado quando você alterna entre endpoints por projeto.

~/.aider.conf.yml

# ~/.aider.conf.yml — same two values, without exporting them each shell.
openai-api-base: https://api.kunavo.com/v1
openai-api-key: sk-kn-...
model: openai/claude-sonnet-5

Verifique antes de depurar o Aider

Uma solicitação basta para determinar se a falha está no endpoint, na chave ou na resolução de modelos do Aider. Se ela retornar uma lista JSON de IDs de modelos, a mesma URL base e a mesma chave funcionarão no Aider — e qualquer erro restante será o prefixo openai/.

# Settles whether a failure is the endpoint, the key, or Aider.
# A JSON list of model ids means the same base URL will work in Aider.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

Quais modelos escolher

Todos os modelos de texto da Kunavo estão disponíveis como openai/<id> — a lista completa está na página de modelos e é retornada em tempo real por GET /v1/models. As tarifas são em USD por 1 milhão de tokens, entrada/saída.

ID do modelo	Entrada / saída da Kunavo	Indicação de uso
`claude-haiku-4-5`	$0.70 / $3.50	Claude mais barato — adequado para chamadas de mapa do repositório e mensagens de commit do Aider
`claude-sonnet-5`	$1.40 / $7.00	O equilíbrio padrão entre qualidade e preço para edição
`claude-opus-5`	$3.50 / $17.50	Nível Claude de maior qualidade — para alterações no nível da arquitetura
`gpt-5-6-terra`	$0.70 / $4.20	Mesma chave, outra família — útil para obter uma segunda opinião sobre um diff complexo

O Aider reenvia o mapa do repositório e os arquivos editados a cada interação; portanto, o gasto de tokens acompanha o tamanho do contexto, e não o tamanho da edição. Por isso, o cache de prompts é o fator mais importante aqui, e --model com --weak-model openai/claude-haiku-4-5 é a combinação de menor custo: o modelo mais robusto faz as edições; o mais simples escreve mensagens de commit e resumos. A cobrança é por token, debitada de um saldo pré-pago sem mensalidade — consulte os detalhes em cobrança.

Perguntas frequentes

Como uso o Aider com uma API compatível com a OpenAI?

Defina OPENAI_API_BASE como a URL base do endpoint e OPENAI_API_KEY como sua chave, depois inicie o Aider com o ID do modelo precedido por openai/ — por exemplo, `aider --model openai/claude-sonnet-5`. Na Kunavo, a URL base é https://api.kunavo.com/v1. O prefixo é obrigatório: sem ele, o Aider tenta resolver o ID usando sua própria tabela de provedores, em vez de enviá-lo ao seu endpoint.

O Aider pode usar modelos Claude por meio de um endpoint compatível com a OpenAI?

Sim. O Aider se comunica usando o protocolo da OpenAI com o endereço indicado por OPENAI_API_BASE. Assim, um modelo Claude servido nesse formato fica acessível sem credenciais da Anthropic — o ID do modelo é apenas outra string na lista /v1/models. Na Kunavo, todos os IDs do Claude e do GPT usam a mesma chave; portanto, para alternar entre eles, basta mudar o argumento --model, sem alterar a configuração.

Por que o Aider diz que o modelo é desconhecido?

Quase sempre, falta o prefixo openai/. O Aider trata um ID sem prefixo como um modelo que deve reconhecer e falha quando não o reconhece; `openai/<id>` indica que ele deve encaminhar o ID diretamente para OPENAI_API_BASE. A segunda causa mais comum é uma URL base sem o sufixo /v1, que provoca um erro de conexão ou 404, em vez de um erro de modelo desconhecido.

O Aider mostra o custo de uma sessão?

O Aider exibe a contagem de tokens e uma estimativa de custo por interação, calculada com base nos metadados dos próprios modelos — para um endpoint personalizado, essa estimativa pode estar errada, pois o Aider não conhece as tarifas do seu endpoint. Considere confiável a contagem de tokens e consulte o provedor para saber a cobrança real. Na Kunavo, o custo por solicitação aparece na visualização de uso; a cobrança é feita de um saldo pré-pago, sem mensalidade.