Início / Guias / Use o OpenCode com uma API LLM gratuita

Use o OpenCode com uma API LLM gratuita

O OpenCode é um agente de programação de código aberto para terminal e desktop. Ele aceita qualquer provedor compatível com OpenAI. Este guia conecta o OpenCode a modelos gratuitos por meio do FreeLLMAPI. Um comando grava a configuração e guarda a chave.

O código, os nomes dos modelos e os rótulos do catálogo ao vivo são exibidos em inglês.

Etapa 1: instale o FreeLLMAPI

O FreeLLMAPI é um gateway de código aberto. Ele roda no seu computador, em Docker, e reúne os planos gratuitos de 45 provedores atrás de uma única chave.

Instale no macOS ou no Linux

curl -fsSL https://freellmapi.co/install.sh | bash

Abra http://localhost:3001. Adicione pelo menos duas chaves de provedores gratuitos na página Keys. O Google AI Studio e a Groq fornecem, cada um, uma chave gratuita em poucos minutos. Copie sua chave unificada da mesma página.

Etapa 2: conecte o OpenCode com um comando

Um comando

npx freellmapi setup-opencode --url http://localhost:3001 --api-key <unified-key> --dry-run
npx freellmapi setup-opencode --url http://localhost:3001 --api-key <unified-key>
opencode

O comando faz três coisas:

  • Ele adiciona um provedor freellmapi em ~/.config/opencode/opencode.json. O provedor lista os modelos do seu catálogo atual com os limites de contexto deles.
  • Ele define freellmapi/auto como modelo padrão.
  • Ele guarda a chave no arquivo de credenciais do OpenCode, ~/.local/share/opencode/auth.json. Você não precisa de uma variável de ambiente, na CLI nem no aplicativo de desktop.

O comando faz uma cópia de segurança antes de gravar. Ele mescla o novo provedor, então seus outros provedores continuam. Se XDG_CONFIG_HOME ou XDG_DATA_HOME estiver definido, o comando usa essas pastas.

Antes de iniciar uma tarefa longa, verifique se o gateway pode atender uma requisição agora. Esta chamada lista somente os modelos que têm uma chave utilizável neste momento:

Verifique quais modelos estão prontos

curl "http://localhost:3001/v1/models?execution_status=ready" \
  -H "Authorization: Bearer <unified-key>"

Um modelo com o status exhausted tem chaves, mas todas estão no limite agora. Este status é removido quando os períodos de espera terminam. Execute npx freellmapi doctor para confirmar que as requisições de um cliente chegam ao gateway. O registro de requisições do painel mostra cada chamada feita pelo OpenCode. O cabeçalho de resposta X-Routed-Via informa o provedor e o modelo que responderam a cada requisição. Se uma requisição passou por failover, o cabeçalho X-Fallback-Trail informa cada salto que falhou e o motivo.

Configuração manual: o bloco de provedor do opencode.json

Para configurar manualmente, adicione este bloco em ~/.config/opencode/opencode.json, ou em opencode.json no seu projeto. O OpenCode usa @ai-sdk/openai-compatible para endpoints /v1/chat/completions.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "model": "freellmapi/auto",
  "provider": {
    "freellmapi": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "FreeLLMAPI",
      "options": {
        "baseURL": "http://localhost:3001/v1"
      },
      "models": {
        "auto": {
          "name": "Auto",
          "limit": { "context": 128000, "output": 8192 }
        }
      }
    }
  }
}

Depois, adicione a chave. Inicie o OpenCode, execute /connect, selecione o provedor freellmapi e cole sua chave unificada. O ID do provedor em /connect deve ser igual ao ID da configuração. Execute /models para selecionar um modelo.

  • limit.context é o número máximo de tokens de entrada do modelo. limit.output é o número máximo de tokens que ele pode gerar.
  • O model de nível superior usa o formato provider/model. Sem ele, o OpenCode mantém o modelo que usava antes.
  • Todo ID de modelo que você quiser usar deve estar no mapa models. Adicione mais IDs de GET /v1/models.
Nota sobre versões de configuração: a documentação do OpenCode agora descreve um formato de configuração V2 com uma chave providers. A documentação diz que o formato V1 acima continua com suporte. O comando de configuração do FreeLLMAPI grava o formato V1.

Escolha modelos para o OpenCode

O OpenCode é um agente. Ele lê arquivos, os edita e executa comandos por meio de chamadas de ferramentas. Cada requisição leva um prompt de sistema, definições de ferramentas e conteúdo de arquivos. Use modelos com chamada de ferramentas e uma janela de contexto grande.

Modelos gratuitos para o OpenCode: chamada de ferramentas e contexto de 128K ou mais
ModeloGratuito emContextoLimites gratuitos (melhor oferta)FerramentasVisão
GLM 5.3UnoRouter1M1 req/min
1 req/min per model
SimNão
GLM 5.3 FlashNVIDIA NIM, UnoRouter1M40 req/min
40 RPM
SimSim
Gemini 3.8 FlashGoogle AI Studio1MRecurring provider quotaSimSim
Qwen3.8 Flash NextAMD Radeon Cloud262KRecurring daily account allowanceSimNão
Qwen3.8 FlashElectronHub1M$0.25/week shared recurring creditSimSim
Gemini 3.7 FlashGoogle AI Studio1M10 req/min
20 req/dia
250,000 tokens/min
~3M
SimSim
GPT-5.6 LunaElectronHub1M$0.25/week shared recurring creditSimSim
Dots3 Note PreviewKilo Gateway, OpenRouter512K20 req/min
50 req/dia
50 req/day account-wide (1,000 after a $10 purchase)
SimSim
DeepSeek V4 FlashAMD Radeon Cloud, BazaarLink, ElectronHub1M10 req/min
50 req/dia
Shared rate limit
SimNão
Qwen3.8 27BElectronHub, Groq, OVH AI Endpoints262K30 req/min
250 req/dia
70,000 tokens/min
~6M
SimSim
Gemini 3.6 FlashGoogle AI Studio1M10 req/min
20 req/dia
250,000 tokens/min
~3M
SimSim
Qwen 3.8 27BCloudflare Workers AI262KShared 10k neurons/daySimSim

Mostrando 12 de 109 modelos gratuitos correspondentes. Ver todos os modelos.

Dados ao vivo do catálogo FreeLLMAPI (versão 2026.11.19, verificado em 2026-11-19). Os limites gratuitos mudam com frequência. O catálogo é verificado todos os dias.

Use freellmapi/auto para deixar o roteador escolher um modelo para cada requisição. Adicione auto:smart ou auto:fast ao mapa models para direcionar as requisições por inteligência ou por velocidade. Você também pode adicionar um perfil nomeado, por exemplo auto:coding, depois de criá-lo no painel.

Limites de requisições e sessões longas

Uma tarefa de agente pode enviar dezenas de requisições. Um único plano gratuito para uma tarefa longa rapidamente. O FreeLLMAPI conta as requisições e os tokens de cada chave. Quando um provedor envia um erro 429, o roteador envia a requisição para o próximo modelo da cadeia, e a sessão continua.

  • Adicione chaves de quatro ou mais provedores. Mais provedores dão mais requisições por dia.
  • Ative a transferência de contexto com FREELLMAPI_CONTEXT_HANDOFF=on_model_switch no .env do FreeLLMAPI. Quando o modelo muda, o próximo modelo recebe uma nota curta informando que ele continua uma tarefa.
  • As sessões fixas mantêm uma conversa no mesmo modelo por 30 minutos. Isso mantém o agente consistente.
  • Inicie uma nova sessão para cada tarefa. Um contexto menor usa menos tokens por requisição.

Solução de problemas

ProblemaCausaSolução
"Invalid API key" com uma chave válidaUm apiKey vazio na configuração substitui a chave de /connectRemova apiKey de options ou execute setup-opencode novamente
O OpenCode não usa o novo provedorO model de nível superior não está definidoDefina "model": "freellmapi/auto"
Model not foundO ID do modelo não está no mapa models do provedorAdicione o ID ao mapa ou execute setup-opencode novamente
A chave {env:VAR} está vaziaO OpenCode substitui uma variável não definida por uma string vaziaExporte a variável no mesmo shell ou guarde a chave com /connect
As chamadas de ferramenta falhamO modelo tem chamada de ferramentas fracaSelecione um modelo da tabela acima
"Todos os modelos atingiram o limite de taxa após N tentativas"Todas as chaves estão no limiteAdicione chaves de mais provedores ou aguarde os períodos de espera
Use todos estes modelos com uma única chave. FreeLLMAPI é um roteador de código aberto e de hospedagem própria. Ele coloca todas estas camadas gratuitas atrás de um único endpoint compatível com OpenAI e passa para o próximo provedor quando um deles está com limite de requisições. Ver o catálogo ou colocar em produção.

Perguntas frequentes

Posso usar o OpenCode de graça?

Sim. O OpenCode é de código aberto. Conecte-o ao FreeLLMAPI como um provedor compatível com OpenAI. O gateway envia cada requisição para os planos gratuitos dos provedores, então a inferência custa US$ 0.

Como adicionar um provedor próprio compatível com OpenAI ao OpenCode?

Adicione ao opencode.json um provedor com npm definido como @ai-sdk/openai-compatible, options.baseURL e um mapa models. Depois, execute /connect para guardar a chave e /models para selecionar um modelo.

Qual modelo gratuito é o melhor para o OpenCode?

Use um modelo com chamada de ferramentas e pelo menos 128K de contexto. A tabela desta página mostra os modelos gratuitos mais fortes que atendem às duas regras hoje. Use freellmapi/auto para deixar o roteador escolher um.

Onde o OpenCode guarda as chaves de API?

As chaves adicionadas com /connect vão para ~/.local/share/opencode/auth.json. O comando de configuração do FreeLLMAPI grava a chave ali, então a CLI e o aplicativo de desktop a encontram.

Guias relacionados

Fontes

Todos os guias · Ver todos os modelos gratuitos