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/
