Documentação

opencode

O opencode cria seus provedores com base no Vercel AI SDK, então apontá-lo para um novo endpoint requer um único bloco que indica um pacote npm e uma baseURL. O pacote indicado determina qual dos dois formatos de protocolo ele usa.

Um bloco de provedor em opencode.json — @ai-sdk/openai-compatible para conclusões de chat, @ai-sdk/openai quando você quiser a superfície /v1/responses.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "kunavo": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Kunavo",
      "options": {
        "baseURL": "https://api.kunavo.com/v1",
        "apiKey": "{env:KUNAVO_API_KEY}"
      },
      "models": {
        "claude-sonnet-5": {
          "name": "Claude Sonnet 5",
          "limit": { "context": 200000, "output": 64000 }
        },
        "claude-haiku-4-5": { "name": "Claude Haiku 4.5" }
      }
    }
  }
}

Testado em 2026-10-10 com opencode 1.18.35: uma tarefa real de código rodou do começo ao fim com claude-sonnet-5 e o bloco de provider acima. Os modelos GPT ainda não são confiáveis no opencode — o opencode envia um limite de saída em toda requisição e, com esse limite, o fornecedor por trás dos nossos modelos GPT às vezes deixa a chamada de ferramenta do modelo de fora da resposta, e o turno termina sem a edição. Use um modelo Claude no opencode até que esta nota seja removida.

O campo npm escolhe o formato do protocolo. @ai-sdk/openai-compatible usa /v1/chat/completions; @ai-sdk/openai usa /v1/responses. A Kunavo oferece ambos, então qualquer um funciona — use o pacote Responses quando quiser que os itens de raciocínio sejam preservados para a família GPT e use o pacote chat-completions para todo o restante.

"apiKey": "{env:KUNAVO_API_KEY}" lê a chave do ambiente ao carregar. opencode.json é um arquivo que acaba em repositórios; uma chave literal nele não permanece secreta.

Defina limit.context e limit.output para cada modelo. O opencode acompanha o contexto restante com base nesses números, então um modelo sem esses valores recebe o orçamento padrão, que não corresponde ao seu próprio limite.

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

Passo a passo

Crie uma chave em /app/keys e copie-a — ela é exibida uma única vez.
Exporte a variável: export KUNAVO_API_KEY=sk-kn-...
Adicione o bloco do provedor a opencode.json — ao arquivo global em ~/.config/opencode/opencode.json, para todos os projetos, ou ao arquivo na raiz do projeto, somente para este repositório.
Inicie opencode e escolha o modelo na lista; o provedor aparece com o name que você definiu.
Para adicionar um modelo mais tarde, inclua outra chave em models — o ID é o que vai pelo protocolo; name é apenas um rótulo.

Verificado em documentação de provedores do opencode em 6 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.

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

# 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 modelo	Entrada / saída da Kunavo	Onde se encaixa em opencode
`claude-sonnet-5`	$1.40 / $7.00	o modelo de build padrão
`claude-opus-5`	$3.50 / $17.50	modo de planejamento, no qual todo o resto depende do plano
`claude-haiku-4-5`	$0.70 / $3.50	trabalho com subagentes e buscas, no qual o número de solicitações é alto
`gpt-5-6-sol`	$2.00 / $12.00	use com @ai-sdk/openai para preservar os itens de raciocínio durante a ida e a volta

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

Como adiciono um provedor personalizado ao opencode?

Adicione um bloco em "provider" no opencode.json indicando um pacote npm, um nome de exibição, options.baseURL, options.apiKey e um mapa models. Use @ai-sdk/openai-compatible para um endpoint que ofereça /v1/chat/completions e @ai-sdk/openai para um que ofereça /v1/responses. O provedor aparecerá na lista de modelos do opencode com o nome que você definiu.

Como mantenho a chave de API fora do opencode.json?

Use a sintaxe de interpolação {env:VAR_NAME} em options.apiKey — por exemplo, "apiKey": "{env:KUNAVO_API_KEY}" — e exporte a variável no shell. O opencode a resolve ao carregar a configuração, então o arquivo pode ser enviado com segurança ao repositório junto com o projeto que ele configura.

Qual é a diferença entre @ai-sdk/openai e @ai-sdk/openai-compatible no opencode?

Eles selecionam endpoints diferentes na mesma URL base. @ai-sdk/openai-compatible chama /chat/completions, implementado por quase todos os gateways; @ai-sdk/openai chama /responses, a interface OpenAI mais recente. Escolha o pacote correspondente ao endpoint que seu serviço realmente oferece — usar o pacote errado gera um erro 404 em uma URL base que, de resto, está correta.

Por que o opencode fica sem contexto antes do esperado?

Porque a entrada do modelo não tem um bloco limit, então o opencode calcula o orçamento com base em um padrão, e não na janela real do modelo. Adicione "limit": { "context": <window>, "output": <max output> } ao modelo em opencode.json, usando os valores do catálogo do provedor; assim, a indicação de contexto e os pontos de compactação correspondem à realidade.