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 | bashAbra 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>
opencodeO comando faz três coisas:
- Ele adiciona um provedor
freellmapiem~/.config/opencode/opencode.json. O provedor lista os modelos do seu catálogo atual com os limites de contexto deles. - Ele define
freellmapi/autocomo 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
modelde nível superior usa o formatoprovider/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 deGET /v1/models.
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.
| Modelo | Gratuito em | Contexto | Limites gratuitos (melhor oferta) | Ferramentas | Visão |
|---|---|---|---|---|---|
| GLM 5.3 | UnoRouter | 1M | 1 req/min 1 req/min per model | Sim | Não |
| GLM 5.3 Flash | NVIDIA NIM, UnoRouter | 1M | 40 req/min 40 RPM | Sim | Sim |
| Gemini 3.8 Flash | Google AI Studio | 1M | Recurring provider quota | Sim | Sim |
| Qwen3.8 Flash Next | AMD Radeon Cloud | 262K | Recurring daily account allowance | Sim | Não |
| Qwen3.8 Flash | ElectronHub | 1M | $0.25/week shared recurring credit | Sim | Sim |
| Gemini 3.7 Flash | Google AI Studio | 1M | 10 req/min 20 req/dia 250,000 tokens/min ~3M | Sim | Sim |
| GPT-5.6 Luna | ElectronHub | 1M | $0.25/week shared recurring credit | Sim | Sim |
| Dots3 Note Preview | Kilo Gateway, OpenRouter | 512K | 20 req/min 50 req/dia 50 req/day account-wide (1,000 after a $10 purchase) | Sim | Sim |
| DeepSeek V4 Flash | AMD Radeon Cloud, BazaarLink, ElectronHub | 1M | 10 req/min 50 req/dia Shared rate limit | Sim | Não |
| Qwen3.8 27B | ElectronHub, Groq, OVH AI Endpoints | 262K | 30 req/min 250 req/dia 70,000 tokens/min ~6M | Sim | Sim |
| Gemini 3.6 Flash | Google AI Studio | 1M | 10 req/min 20 req/dia 250,000 tokens/min ~3M | Sim | Sim |
| Qwen 3.8 27B | Cloudflare Workers AI | 262K | Shared 10k neurons/day | Sim | Sim |
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_switchno.envdo 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
| Problema | Causa | Solução |
|---|---|---|
| "Invalid API key" com uma chave válida | Um apiKey vazio na configuração substitui a chave de /connect | Remova apiKey de options ou execute setup-opencode novamente |
| O OpenCode não usa o novo provedor | O model de nível superior não está definido | Defina "model": "freellmapi/auto" |
| Model not found | O ID do modelo não está no mapa models do provedor | Adicione o ID ao mapa ou execute setup-opencode novamente |
A chave {env:VAR} está vazia | O OpenCode substitui uma variável não definida por uma string vazia | Exporte a variável no mesmo shell ou guarde a chave com /connect |
| As chamadas de ferramenta falham | O modelo tem chamada de ferramentas fraca | Selecione um modelo da tabela acima |
| "Todos os modelos atingiram o limite de taxa após N tentativas" | Todas as chaves estão no limite | Adicione chaves de mais provedores ou aguarde os períodos de espera |
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
- Use o Aider com uma API gratuita de LLM
- Use o Codex CLI com modelos gratuitos
- Como usar o Claude Code gratuitamente
- Melhores APIs gratuitas de modelos para código
- URLs base de APIs gratuitas compatíveis com OpenAI
Fontes
- OpenCode docs: providers (V1 config) (verificado em 20 November 2026)
- OpenCode docs: config (verificado em 20 November 2026)
- OpenCode docs: migrate from V1 (verificado em 20 November 2026)
- FreeLLMAPI CLI generators (verificado em 20 November 2026)
- FreeLLMAPI docs: context handoff (verificado em 20 November 2026)