Modelos gratuitos para OpenCode via FreeLLMAPI

OpenCode é um agente de programação aberto que funciona no terminal: lê arquivos de projeto, edita código, executa comandos e testes, pesquisa no repositório e trabalha com git. Ele não está vinculado a um provedor modelo, portanto, quase qualquer serviço compatível com OpenAI pode ser conectado a ele.

FreeLLMAPI é um roteador auto-hospedado aberto que coleta planos gratuitos de dezenas de provedores de IA em um endereço /v1 compatível com OpenAI. Em vez de trinta chaves, trinta limites e trinta locais onde uma solicitação pode falhar, você tem um gateway local e uma chave unificada. O próprio roteador seleciona um modelo disponível, muda para o próximo quando ocorre o erro 429 ou 5xx e garante que as solicitações não ultrapassem as cotas das tarifas gratuitas.

Neste post irei descrever a instalação do FreeLLMAPI, adição de provedores e conexão do gateway ao OpenCode.

O que você precisa

Para funcionar você precisa de quatro coisas:

• OpenCode instalado. Se o agente ainda não estiver instalado, discuti o procedimento de instalação em uma nota separada sobre OpenCode e DeepSeek.
• FreeLLMAPI em execução. A maneira mais fácil é instalar um aplicativo de desktop ou contêiner Docker.
• Node.js 20.18 ou posterior. Isso é necessário para o gerador CLI que configura o OpenCode. O próprio OpenCode pode ser instalado sem o Node.
• Chaves de pelo menos um provedor. Planos gratuitos do Google AI Studio, Groq, Cerebras, Mistral, OpenRouter, NVIDIA, HuggingFace e outros serviços do catálogo são adequados.

Instalando o FreeLLMAPI

O projeto possui vários caminhos de instalação. Escolha aquele que for mais conveniente para o seu sistema.

Aplicativo para desktop

A opção mais fácil para Windows e macOS é o instalador pronto na página de lançamentos. No Windows é .exe, no macOS é .dmg para Apple Silicon ou Intel. O aplicativo fica na bandeja e eleva o roteador junto com o painel de controle localmente.

Não é necessária senha para a versão desktop: o painel faz login sozinho por meio de uma conta local oculta. As únicas credenciais necessárias são a chave unificada na janela pop-up da bandeja ou no cabeçalho da página Chaves.

Os dados do aplicativo estão localizados em um diretório:

• Windows — %APPDATA%\FreeLLMAPI\
• macOS — ~/Library/Application Support/FreeLLMAPI/
• Linux — ~/.config/FreeLLMAPI/

Docker

Se o Docker já estiver instalado, o servidor será acionado com um comando. O script cria o diretório ~/freellmapi, gera uma chave de criptografia, baixa a imagem e inicia o contêiner:

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

Executar o script novamente é seguro: o arquivo .env e a chave de criptografia são salvos e o contêiner é atualizado para a versão mais recente. No Windows, esse método funciona em WSL ou em qualquer ambiente bash.

Após o lançamento, o painel abre em:

http://localhost:3001

Para instalação do servidor, você precisa criar uma conta com email e senha. Se a senha for esquecida, o código de redefinição será impresso no log do contêiner:

docker compose logs -f freellmapi

Docker Compose

Se você quiser manter a configuração no git e gerenciar a inicialização manualmente, o Compose normal servirá. No macOS e Linux:

git clone https://github.com/tashfeenahmed/freellmapi.git
cd freellmapi
ENCRYPTION_KEY="$(openssl rand -hex 32)"
printf "ENCRYPTION_KEY=%s\nPORT=3001\n" "$ENCRYPTION_KEY" > .env
docker compose up -d

No Windows PowerShell:

git clone https://github.com/tashfeenahmed/freellmapi.git
cd freellmapi
$Bytes = New-Object Byte[] 32
[Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($Bytes)
$ENCRYPTION_KEY = -join ($Bytes | ForEach-Object { "{0:x2}" -f $_ })
"ENCRYPTION_KEY=$ENCRYPTION_KEY`nPORT=3001" | Out-File -Encoding utf8 .env
docker compose up -d

A chave ENCRYPTION_KEY é necessária: ela é usada para criptografar as chaves do provedor no banco de dados SQLite. Você não pode alterá-lo imediatamente – segredos antigos não serão mais descriptografados. Para rotação, o projeto possui um comando separado, rotate-encryption-key.

Executando a partir do código-fonte

Para desenvolvimento ou depuração, você pode executar o projeto por meio do Node.js:

git clone https://github.com/tashfeenahmed/freellmapi.git
cd freellmapi
npm install
ENCRYPTION_KEY="$(node -e 'console.log(require("crypto").randomBytes(32).toString("hex"))')"
printf "ENCRYPTION_KEY=%s\nPORT=3001\n" "$ENCRYPTION_KEY" > .env
npm run dev

Neste modo, a API e o painel são acionados na porta 3001 e a interface Vite é acionada na 5173.

Primeiro lançamento e chaves do provedor

Abra o painel, vá até a página Chaves e adicione as chaves dos serviços que utilizamos. Para cada provedor, a interface possui um link para cadastro e uma dica de onde conseguir a chave. Basta começar com um ou dois: por exemplo, Google AI Studio e Groq.

Depois de adicionada, a chave passa por uma verificação de integridade. Se o provedor respondeu com um erro, a chave permanecerá na lista, mas será marcada como não íntegra – ela pode ser verificada novamente ou excluída.

Em seguida, você deve ir até a página Modelos e ver quais modelos estão disponíveis. Lá você também pode configurar a estratégia de roteamento e a ordem da Fallback Chain – a cadeia pela qual o roteador passa em caso de erros e limites. O modelo auto significa que a escolha é feita pelo próprio roteador. Além dele, estão disponíveis opções como auto:fast, auto:smart e perfis nomeados para tarefas específicas.

Vale verificar também se existem modelos na cadeia que suportam ferramentas. OpenCode usa ativamente chamadas de ferramentas, e um modelo sem esse recurso não será capaz de ler arquivos ou executar comandos normalmente.

A chave unificada é obtida ali, na página Chaves ou na bandeja do aplicativo desktop. Parece uma string com um prefixo:

freellmapi-...

É esta chave, e não as chaves de provedores individuais, que é indicada no OpenCode.

Conecte-se ao OpenCode

O FreeLLMAPI possui um gerador de configuração que lê o diretório do modelo do gateway em execução, faz uma cópia de backup da configuração existente e adiciona cuidadosamente o provedor a ela.

Primeiro, vamos definir a chave unificada para a variável de ambiente. O gerador o lê em vez de um sinalizador separado, para que o segredo não acabe no histórico de comandos.

No macOS e Linux:

export FREELLMAPI_API_KEY=freellmapi-YOUR_KEY

No Windows PowerShell:

$env:FREELLMAPI_API_KEY="freellmapi-YOUR_KEY"

Agora vamos ver o que exatamente será gravado:

npx freellmapi setup-opencode --url http://localhost:3001 --dry-run

Se a diferença for satisfatória, repita o comando sem o sinalizador:

npx freellmapi setup-opencode --url http://localhost:3001

O gerador grava a configuração global do OpenCode:

~/.config/opencode/opencode.json

O provedor freellmapi aparece nele com o pacote @ai-sdk/openai-compatível, o endereço base http://localhost:3001/v1 e um mapa de modelos do catálogo ativo. O modelo padrão se torna freellmapi/auto.

A chave em si não vai parar no arquivo: a configuração contém a substituição {env:FREELLMAPI_API_KEY}. Portanto, a variável deve permanecer definida quando o agente for iniciado:

opencode

Este método também é conveniente porque o segredo não vai parar na configuração e não vai acabar no git. Para CI e execuções únicas, isso é mais correto do que armazenar a chave em um arquivo.

Configuração manual

Se não quiser executar o gerador, você pode descrever manualmente o provedor em opencode.json. A opção mínima é assim:

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

O campo model no nível superior é importante: sem ele, o OpenCode pode continuar a usar o modelo anterior ou não selecionar nada em uma nova instalação. É melhor tirar o contexto e os limites de saída da resposta do gateway, em vez de inventá-los:

curl http://localhost:3001/v1/models

Você pode adicionar identificadores específicos à lista de modelos se precisar mudar para eles manualmente. Mas para o trabalho diário, auto é suficiente: o próprio roteador selecionará um modelo ativo e mudará quando o limite for atingido.

Como usar

Após iniciar o opencode, a lista de modelos é aberta com um comando familiar:

/models

Terá um provedor FreeLLMAPI e um modelo automático. Em seguida, o trabalho prossegue normalmente: descrevemos a tarefa, especificamos arquivos via @, alternamos o modo de planejamento com a tecla Tab, revertemos as edições com o comando /undo. Para um novo projeto, é útil executar /init para que o agente crie AGENTS.md.

Algumas dicas práticas:

• Roteamento. Para rotina, deixe em automático. Se você precisa de velocidade, experimente auto:fast, se a qualidade for auto:smart ou um modelo específico forte do catálogo.
• Diagnóstico Cada resposta do gateway contém um cabeçalho X-Routed-Via com o nome do provedor e modelo que realmente atendeu a solicitação. Mostra para onde o roteador enviou a tarefa.
• Analytics. Na página Analytics, o painel mostra o volume de solicitações, sucesso, atrasos p50/p95 e consumo de token por provedor.
• Continuidade do diálogo. Ao trocar de modelo no meio de uma conversa, o gateway pode adicionar uma breve nota sobre a transferência de contexto. Ativado pela variável FREELLMAPI_CONTEXT_HANDOFF=on_model_switch.

Se o OpenCode estiver sendo executado em um contêiner e o FreeLLMAPI estiver sendo executado em um host, localhost apontará para o próprio contêiner. Nesse caso, você precisa usar host.docker.internal ou outro endereço acessível a partir do contêiner no baseURL.

No que prestar atenção

FreeLLMAPI não é um substituto para modelos pagos e nem um serviço com SLA. É uma maneira de agrupar planos gratuitos em um único gateway. Portanto, existem várias restrições:

• A qualidade flutua. As tarifas gratuitas terminam e, tarde da noite, mais perto do esgotamento das cotas diárias, o roteador pode mudar para modelos mais fracos. As cotas geralmente são redefinidas à meia-noite UTC.
• As latências são variáveis. Diferentes provedores respondem de maneira diferente e, ao mudar para um modelo de backup, a solicitação pode demorar muito mais.
• Não existem modelos principais. Modelos bons, mas não de última geração, estão disponíveis em planos gratuitos. Para arquiteturas complexas, vale a pena considerar isso.
• O gateway deve estar em execução. Se o aplicativo ou contêiner for interrompido, o OpenCode não receberá uma resposta. A inicialização automática do aplicativo na bandeja ou a reinicialização da política de contêiner resolve esse problema.
• O projeto foi projetado para um usuário. As chaves do provedor são armazenadas localmente e criptografadas, mas um painel compartilhado por várias pessoas não é o cenário para esta ferramenta. A chave unificada e o .env devem ser protegidos da mesma forma que um segredo normal.

E mais uma nuance: o catálogo de modelos se atualiza sozinho, mas a instalação gratuita recebe um instantâneo do catálogo com um atraso de cerca de trinta dias. O plano pago Premium agiliza a atualização, mas não é necessário conhecer o projeto – o próprio roteador permanece gratuito e aberto.

Links

https://github.com/tashfeenahmed/freellmapi
https://freellmapi.co/
https://freellmapi.co/models
https://github.com/tashfeenahmed/freellmapi/releases/latest
https://github.com/tashfeenahmed/freellmapi/blob/main/docs/en/install/01-install.md
https://github.com/tashfeenahmed/freellmapi/blob/main/docs/en/clients/01-agent-clients.md
https://github.com/tashfeenahmed/freellmapi/blob/main/cli/README.md
https://opencode.ai/
https://opencode.ai/docs/
https://opencode.ai/docs/providers/

Fontes

https://github.com/tashfeenahmed/freellmapi
https://github.com/tashfeenahmed/freellmapi/blob/main/README.ru.md
https://github.com/tashfeenahmed/freellmapi/blob/main/docs/en/install/01-install.md
https://github.com/tashfeenahmed/freellmapi/blob/main/docs/en/clients/01-agent-clients.md
https://github.com/tashfeenahmed/freellmapi/blob/main/docs/en/clients/02-supported-agents.md
https://github.com/tashfeenahmed/freellmapi/blob/main/cli/README.md
https://opencode.ai/docs/providers/