OpenCode com uma API compatível com OpenAI: configuração

O que você precisa antes de começar

O OpenCode é um agente de código de código aberto que roda no seu terminal. Ele pode conversar com muitos provedores de modelos e permite que você adicione seu próprio provedor se o endpoint seguir o formato de chat do OpenAI. Esta API o segue, então a configuração é apenas preencher alguns campos.

Reúna esses três valores primeiro:

• URL base: https://api.kimicode.top/v1
• ID do modelo: uncensored
• Chave de API: crie uma na página da chave de API. Contas novas podem resgatar um crédito de teste de $0.50 lá com um clique, o que é suficiente para os testes abaixo. A chave de teste permite 2 requisições simultâneas e 60 requisições por minuto.

Mantenha a chave em uma variável de ambiente em vez de colá-la em arquivos que você faz commit:

Copyexport KIMICODE_API_KEY="your-key-here"

Passo 1: teste o endpoint com curl

Faça isso antes de configurar qualquer ferramenta. Se o curl funcionar e o OpenCode não, você sabe que o problema está na configuração. Se o curl falhar, você corrige a chave ou a URL uma vez, não em dois lugares.

Copycurl https://api.kimicode.top/v1/chat/completions \
  -H "Authorization: Bearer $KIMICODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "Say hello in five words."}],
    "max_tokens": 40
  }'

Você deve receber um objeto JSON com uma matriz choices e um bloco usage. Um 401 significa que a chave está errada ou faltando o prefixo Bearer. Um 404 geralmente significa que a URL foi digitada errada ou já inclui /chat/completions.

Um agente de programação transmite suas respostas e chama ferramentas, então verifique esses dois também:

Copycurl -N https://api.kimicode.top/v1/chat/completions \
  -H "Authorization: Bearer $KIMICODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "stream": true,
    "messages": [{"role": "user", "content": "Count from one to five."}]
  }'

Você deve ver uma série de linhas data:, cada uma com um pequeno delta JSON, terminando com as métricas de uso e um marcador final. A flag -N desativa o buffer do curl para que os chunks apareçam conforme chegam.

Passo 2: adicione um provedor personalizado ao OpenCode

O OpenCode lê um arquivo de configuração JSON, opencode.json, da pasta do seu projeto ou do seu diretório de configuração global. Provedores personalizados estilo OpenAI são declarados com o pacote compatível com OpenAI do AI SDK, uma base URL e uma lista de modelos. O layout abaixo segue a documentação pública do OpenCode no momento da escrita. Os nomes dos campos podem mudar entre versões, então compare-o com a seção de provedor da documentação atual do OpenCode se algo for rejeitado.

Copy{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "kimicode": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Kimicode API",
      "options": {
        "baseURL": "https://api.kimicode.top/v1",
        "apiKey": "{env:KIMICODE_API_KEY}"
      },
      "models": {
        "uncensored": {
          "name": "Uncensored",
          "limit": {
            "context": 100000,
            "output": 8192
          }
        }
      }
    }
  },
  "model": "kimicode/uncensored"
}

A chave sob models é o ID exato do modelo enviado ao servidor, então deve ler uncensored. A última linha seleciona o provedor e o modelo como padrão, escrito como nome do provedor, uma barra e depois o ID do modelo.

A forma {env:KIMICODE_API_KEY} diz ao OpenCode para ler a variável do seu shell. Se sua versão lida com credenciais através do seu próprio comando de login, use essa rota e deixe a chave de fora do arquivo. De qualquer forma, não faça commit de uma chave real.

Configuração do projeto ou configuração global

Você pode manter o bloco do provedor em dois lugares. Um arquivo na raiz do projeto se aplica apenas a esse repositório, o que é adequado para uma equipe que compartilha uma configuração. Um arquivo no seu diretório de configuração do usuário se aplica em todos os lugares, o que é adequado para um padrão pessoal. Onde ambos existem, o arquivo do projeto adiciona ou substitui o global.

Prefira o arquivo global para a definição do provedor e a variável de ambiente para a chave. Assim, cada repositório pode usar o endpoint, e nada secreto fica ao lado do seu código-fonte. Se várias pessoas trabalham em um projeto, faça commit apenas do bloco do provedor sem uma chave, e faça com que cada pessoa defina sua própria variável. Isso também torna simples rotacionar uma chave: altere a variável, reinicie o terminal e o arquivo de configuração permanece intacto.

Passo 3: escolha o modelo e execute uma tarefa

Inicie o OpenCode em uma pasta de projeto e abra o seletor de modelos. Seu provedor personalizado deve aparecer na lista com o nome de exibição que você definiu. Selecione-o e dê ao agente uma tarefa pequena e verificável, como explicar uma função ou escrever um teste unitário para um arquivo curto.

Comece pequeno por dois motivos. Primeiro, você pode ver se a chamada de função funciona: quando o OpenCode pede ao modelo para ler ou editar um arquivo, ele o faz através da interface de chamada de função. Segundo, um agente de programação envia muito texto por turno, incluindo conteúdos de arquivos e histórico, então uma sessão longa consome tokens rapidamente. A próxima seção coloca números nisso.

Se o modelo não aparecer, verifique se o arquivo é JSON válido, se está onde o OpenCode procura por configuração e se o nome do provedor corresponde ao que você digitou no campo model.

Testando chamada de funções e modo JSON diretamente

O OpenCode depende de chamada de funções para ler arquivos, executar comandos e editar código, então vale a pena confirmar que o endpoint lida com uma definição de ferramenta antes de culpar o agente por uma falha. Esta requisição oferece uma ferramenta e faz uma pergunta que precisa dela.

Copycurl https://api.kimicode.top/v1/chat/completions \
  -H "Authorization: Bearer $KIMICODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "What is in the file notes.txt?"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "read_file",
        "description": "Read a text file by path",
        "parameters": {
          "type": "object",
          "properties": {"path": {"type": "string"}},
          "required": ["path"]
        }
      }
    }],
    "tool_choice": "auto"
  }'

Uma boa resposta contém uma entrada tool_calls nomeando read_file com uma string de argumento JSON. O agente executa a ferramenta e depois envia o resultado de volta como uma mensagem com role definido como tool, e o modelo continua a partir daí. Se você ver apenas texto simples, tente um prompt mais direto, já que a decisão do modelo de chamar uma ferramenta é parte do seu comportamento.

O modo JSON é uma opção separada. Adicionar "response_format": {"type": "json_object"} pede uma saída JSON válida, e ajuda quando outro script precisa analisar o que volta. Mencione JSON no seu prompt também, para que o modelo saiba que formato você espera.

Tamanho do contexto e custo de uma sessão

A janela de contexto é de 100.000 tokens, contando o prompt e a conclusão juntos. Definir limit.context para 100000 permite que o agente saiba o limite real, para que possa cortar ou resumir o histórico antes que o servidor precise rejeitar uma requisição. Uma conclusão pode usar qualquer espaço restante, e max_tokens é opcional.

A cobrança é de $0,15 por 1M de tokens de entrada e $0,50 por 1M de tokens de saída. Os agentes consomem muitos tokens de entrada, porque cada turno reenvia a conversa. Aqui está um exemplo prático para uma sessão moderada:

• 40 turnos, cada um enviando cerca de 30.000 tokens de entrada: 1.200.000 tokens de entrada, que é 1,2 x $0,15 = $0,18.
• Cada turno retorna cerca de 800 tokens de saída: 32.000 tokens de saída, que é 0,032 x $0,50 = $0,016.
• Total: $0,196, então cerca de vinte centavos para toda a sessão.

Seus números serão diferentes. Leia os valores de usage nas respostas ou observe o cabeçalho X-Balance-USD, que informa seu saldo restante em cada resposta. O crédito é pré-pago e nunca expira, e requisições falhas ou recusadas não são cobradas. Detalhes estão na página de preços.

Expectativas honestas para um agente de programação

Este é um modelo de texto geral ajustado para responder sem recusas de conteúdo para uso adulto legal. Não é um modelo construído especificamente para código, e esta página não faz reivindicações de benchmark. Se ele edita seu repositório de forma confiável é algo que você deve testar em suas próprias tarefas, com controle de versão ligado, antes de entregá-lo algo importante.

Ele cuida da infraestrutura que um agente precisa: chamada de funções com tool_calls em streaming, resultados das ferramentas enviados de volta como mensagens role: "tool" e modo JSON via response_format. É apenas texto, sem imagens, então recursos que anexam capturas de tela não funcionarão.

Dois limites importam para agentes. Uma chave completa permite 8 requisições simultâneas e 300 requisições por minuto. Sub-agentes ou execuções paralelas de ferramentas que disparam muitas chamadas de uma vez podem atingir o limite de concorrência, e uma solicitação em streaming mantém seu slot até o fim do stream. Quando isso acontece, você recebe HTTP 429 com o código concurrency. O código rate_limited significa muitas requisições por minuto. Em sobrecarga temporária, você também pode ver um 429 com Retry-After: 5. Reduza o paralelismo ou aguarde e tente novamente.

Solução de Problemas

Sintoma	Causa provável	Correção
401 Não Autorizado	Chave vazia ou errada; a variável de ambiente não está definida no shell que iniciou o OpenCode	Execute echo $KIMICODE_API_KEY no mesmo terminal, depois reinicie o OpenCode
404 Not Found	URL base inclui /chat/completions ou falta /v1	Use exatamente https://api.kimicode.top/v1
Modelo não encontrado	A chave do modelo difere de uncensored	Corresponda a chave em models ao ID retornado por GET /v1/models
429 com concurrency	Muitas requisições de uma vez	Reduza as chamadas de ferramentas em paralelo ou aguarde o término dos streams
Requisição muito grande	Corpo com mais de 8 MB ou histórico próximo ao limite da janela de contexto	Inicie uma nova sessão ou resuma o histórico

Para qualquer coisa não coberta aqui, a página de docs tem a referência completa de requisição, e o guia de integração cobre o mesmo endpoint do ângulo de outros clientes estilo OpenAI.

Mais guias

• O que significa compatível com OpenAI para uma API?
• Alternativa ao Kimicode: API LLM Hospedada sem censura
• API LLM sem censura: Integração e preços compatíveis com OpenAI