OpenCode \u00e9 um agente de programa\u00e7\u00e3o aberto que funciona no terminal: l\u00ea arquivos de projeto, edita c\u00f3digo, executa comandos e testes, pesquisa no reposit\u00f3rio e trabalha com git. Ele n\u00e3o est\u00e1 vinculado a um provedor modelo, portanto, quase qualquer servi\u00e7o compat\u00edvel com OpenAI pode ser conectado a ele.<\/p>\n
FreeLLMAPI \u00e9 um roteador auto-hospedado aberto que coleta planos gratuitos de dezenas de provedores de IA em um endere\u00e7o \/v1 compat\u00edvel com OpenAI. Em vez de trinta chaves, trinta limites e trinta locais onde uma solicita\u00e7\u00e3o pode falhar, voc\u00ea tem um gateway local e uma chave unificada. O pr\u00f3prio roteador seleciona um modelo dispon\u00edvel, muda para o pr\u00f3ximo quando ocorre o erro 429 ou 5xx e garante que as solicita\u00e7\u00f5es n\u00e3o ultrapassem as cotas das tarifas gratuitas.<\/p>\n
Neste post irei descrever a instala\u00e7\u00e3o do FreeLLMAPI, adi\u00e7\u00e3o de provedores e conex\u00e3o do gateway ao OpenCode.<\/p>\n
Para funcionar voc\u00ea precisa de quatro coisas:<\/p>\n
O projeto possui v\u00e1rios caminhos de instala\u00e7\u00e3o. Escolha aquele que for mais conveniente para o seu sistema.<\/p>\n
A op\u00e7\u00e3o mais f\u00e1cil para Windows e macOS \u00e9 o instalador pronto na p\u00e1gina de lan\u00e7amentos. No Windows \u00e9 .exe, no macOS \u00e9 .dmg para Apple Silicon ou Intel. O aplicativo fica na bandeja e eleva o roteador junto com o painel de controle localmente.<\/p>\n
N\u00e3o \u00e9 necess\u00e1ria senha para a vers\u00e3o desktop: o painel faz login sozinho por meio de uma conta local oculta. As \u00fanicas credenciais necess\u00e1rias s\u00e3o a chave unificada na janela pop-up da bandeja ou no cabe\u00e7alho da p\u00e1gina Chaves.<\/p>\n
Os dados do aplicativo est\u00e3o localizados em um diret\u00f3rio:<\/p>\n
Se o Docker j\u00e1 estiver instalado, o servidor ser\u00e1 acionado com um comando. O script cria o diret\u00f3rio ~\/freellmapi, gera uma chave de criptografia, baixa a imagem e inicia o cont\u00eainer:<\/p>\n
curl -fsSL https:\/\/freellmapi.co\/install.sh | bash\n<\/code><\/pre>\n<\/div>\nExecutar o script novamente \u00e9 seguro: o arquivo .env e a chave de criptografia s\u00e3o salvos e o cont\u00eainer \u00e9 atualizado para a vers\u00e3o mais recente. No Windows, esse m\u00e9todo funciona em WSL ou em qualquer ambiente bash.<\/p>\n
Ap\u00f3s o lan\u00e7amento, o painel abre em:<\/p>\n
\nhttp:\/\/localhost:3001\n<\/code><\/pre>\n<\/div>\nPara instala\u00e7\u00e3o do servidor, voc\u00ea precisa criar uma conta com email e senha. Se a senha for esquecida, o c\u00f3digo de redefini\u00e7\u00e3o ser\u00e1 impresso no log do cont\u00eainer:<\/p>\n
\ndocker compose logs -f freellmapi\n<\/code><\/pre>\n<\/div>\nDocker Compose<\/h3>\n
Se voc\u00ea quiser manter a configura\u00e7\u00e3o no git e gerenciar a inicializa\u00e7\u00e3o manualmente, o Compose normal servir\u00e1. No macOS e Linux:<\/p>\n
\ngit clone https:\/\/github.com\/tashfeenahmed\/freellmapi.git\ncd freellmapi\nENCRYPTION_KEY=\"$(openssl rand -hex 32)\"\nprintf \"ENCRYPTION_KEY=%s\\nPORT=3001\\n\" \"$ENCRYPTION_KEY\" > .env\ndocker compose up -d\n<\/code><\/pre>\n<\/div>\nNo Windows PowerShell:<\/p>\n
\ngit clone https:\/\/github.com\/tashfeenahmed\/freellmapi.git\ncd freellmapi\n$Bytes = New-Object Byte[] 32\n[Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($Bytes)\n$ENCRYPTION_KEY = -join ($Bytes | ForEach-Object { \"{0:x2}\" -f $_ })\n\"ENCRYPTION_KEY=$ENCRYPTION_KEY`nPORT=3001\" | Out-File -Encoding utf8 .env\ndocker compose up -d\n<\/code><\/pre>\n<\/div>\nA chave ENCRYPTION_KEY \u00e9 necess\u00e1ria: ela \u00e9 usada para criptografar as chaves do provedor no banco de dados SQLite. Voc\u00ea n\u00e3o pode alter\u00e1-lo imediatamente – segredos antigos n\u00e3o ser\u00e3o mais descriptografados. Para rota\u00e7\u00e3o, o projeto possui um comando separado, rotate-encryption-key.<\/p>\n
Executando a partir do c\u00f3digo-fonte<\/h3>\n
Para desenvolvimento ou depura\u00e7\u00e3o, voc\u00ea pode executar o projeto por meio do Node.js:<\/p>\n
\ngit clone https:\/\/github.com\/tashfeenahmed\/freellmapi.git\ncd freellmapi\nnpm install\nENCRYPTION_KEY=\"$(node -e 'console.log(require(\"crypto\").randomBytes(32).toString(\"hex\"))')\"\nprintf \"ENCRYPTION_KEY=%s\\nPORT=3001\\n\" \"$ENCRYPTION_KEY\" > .env\nnpm run dev\n<\/code><\/pre>\n<\/div>\nNeste modo, a API e o painel s\u00e3o acionados na porta 3001 e a interface Vite \u00e9 acionada na 5173.<\/p>\n
Primeiro lan\u00e7amento e chaves do provedor<\/h2>\n
Abra o painel, v\u00e1 at\u00e9 a p\u00e1gina Chaves<\/b> e adicione as chaves dos servi\u00e7os que utilizamos. Para cada provedor, a interface possui um link para cadastro e uma dica de onde conseguir a chave. Basta come\u00e7ar com um ou dois: por exemplo, Google AI Studio e Groq.<\/p>\n
Depois de adicionada, a chave passa por uma verifica\u00e7\u00e3o de integridade. Se o provedor respondeu com um erro, a chave permanecer\u00e1 na lista, mas ser\u00e1 marcada como n\u00e3o \u00edntegra – ela pode ser verificada novamente ou exclu\u00edda.<\/p>\n
Em seguida, voc\u00ea deve ir at\u00e9 a p\u00e1gina Modelos<\/b> e ver quais modelos est\u00e3o dispon\u00edveis. L\u00e1 voc\u00ea tamb\u00e9m pode configurar a estrat\u00e9gia de roteamento e a ordem da Fallback Chain<\/b> – a cadeia pela qual o roteador passa em caso de erros e limites. O modelo auto<\/b> significa que a escolha \u00e9 feita pelo pr\u00f3prio roteador. Al\u00e9m dele, est\u00e3o dispon\u00edveis op\u00e7\u00f5es como auto:fast<\/b>, auto:smart<\/b> e perfis nomeados para tarefas espec\u00edficas.<\/p>\n
Vale verificar tamb\u00e9m se existem modelos na cadeia que suportam ferramentas. OpenCode usa ativamente chamadas de ferramentas, e um modelo sem esse recurso n\u00e3o ser\u00e1 capaz de ler arquivos ou executar comandos normalmente.<\/p>\n
A chave unificada \u00e9 obtida ali, na p\u00e1gina Chaves<\/b> ou na bandeja do aplicativo desktop. Parece uma string com um prefixo:<\/p>\n\nfreellmapi-...\n<\/code><\/pre>\n<\/div>\n\u00c9 esta chave, e n\u00e3o as chaves de provedores individuais, que \u00e9 indicada no OpenCode.<\/p>\n
Conecte-se ao OpenCode<\/h2>\n
O FreeLLMAPI possui um gerador de configura\u00e7\u00e3o que l\u00ea o diret\u00f3rio do modelo do gateway em execu\u00e7\u00e3o, faz uma c\u00f3pia de backup da configura\u00e7\u00e3o existente e adiciona cuidadosamente o provedor a ela.<\/p>\n
Primeiro, vamos definir a chave unificada para a vari\u00e1vel de ambiente. O gerador o l\u00ea em vez de um sinalizador separado, para que o segredo n\u00e3o acabe no hist\u00f3rico de comandos.<\/p>\n
No macOS e Linux:<\/p>\n
\nexport FREELLMAPI_API_KEY=freellmapi-YOUR_KEY\n<\/code><\/pre>\n<\/div>\nNo Windows PowerShell:<\/p>\n
\n$env:FREELLMAPI_API_KEY=\"freellmapi-YOUR_KEY\"\n<\/code><\/pre>\n<\/div>\nAgora vamos ver o que exatamente ser\u00e1 gravado:<\/p>\n
\nnpx freellmapi setup-opencode --url http:\/\/localhost:3001 --dry-run\n<\/code><\/pre>\n<\/div>\nSe a diferen\u00e7a for satisfat\u00f3ria, repita o comando sem o sinalizador:<\/p>\n
\nnpx freellmapi setup-opencode --url http:\/\/localhost:3001\n<\/code><\/pre>\n<\/div>\nO gerador grava a configura\u00e7\u00e3o global do OpenCode:<\/p>\n
\n~\/.config\/opencode\/opencode.json\n<\/code><\/pre>\n<\/div>\nO provedor freellmapi aparece nele com o pacote @ai-sdk\/openai-compat\u00edvel, o endere\u00e7o base http:\/\/localhost:3001\/v1 e um mapa de modelos do cat\u00e1logo ativo. O modelo padr\u00e3o se torna freellmapi\/auto.<\/p>\n
A chave em si n\u00e3o vai parar no arquivo: a configura\u00e7\u00e3o cont\u00e9m a substitui\u00e7\u00e3o {env:FREELLMAPI_API_KEY}. Portanto, a vari\u00e1vel deve permanecer definida quando o agente for iniciado:<\/p>\n
\nopencode\n<\/code><\/pre>\n<\/div>\nEste m\u00e9todo tamb\u00e9m \u00e9 conveniente porque o segredo n\u00e3o vai parar na configura\u00e7\u00e3o e n\u00e3o vai acabar no git. Para CI e execu\u00e7\u00f5es \u00fanicas, isso \u00e9 mais correto do que armazenar a chave em um arquivo.<\/p>\n
Configura\u00e7\u00e3o manual<\/h2>\n
Se n\u00e3o quiser executar o gerador, voc\u00ea pode descrever manualmente o provedor em opencode.json. A op\u00e7\u00e3o m\u00ednima \u00e9 assim:<\/p>\n
\n{\n \"$schema\": \"https:\/\/opencode.ai\/config.json\",\n \"model\": \"freellmapi\/auto\",\n \"provider\": {\n \"freellmapi\": {\n \"npm\": \"@ai-sdk\/openai-compatible\",\n \"name\": \"FreeLLMAPI\",\n \"options\": {\n \"baseURL\": \"http:\/\/localhost:3001\/v1\",\n \"apiKey\": \"{env:FREELLMAPI_API_KEY}\"\n },\n \"models\": {\n \"auto\": {\n \"name\": \"FreeLLMAPI Auto Router\",\n \"limit\": { \"context\": 1048576, \"output\": 65536 }\n }\n }\n }\n }\n}\n<\/code><\/pre>\n<\/div>\nO campo model no n\u00edvel superior \u00e9 importante: sem ele, o OpenCode pode continuar a usar o modelo anterior ou n\u00e3o selecionar nada em uma nova instala\u00e7\u00e3o. \u00c9 melhor tirar o contexto e os limites de sa\u00edda da resposta do gateway, em vez de invent\u00e1-los:<\/p>\n
\ncurl http:\/\/localhost:3001\/v1\/models\n<\/code><\/pre>\n<\/div>\nVoc\u00ea pode adicionar identificadores espec\u00edficos \u00e0 lista de modelos se precisar mudar para eles manualmente. Mas para o trabalho di\u00e1rio, auto \u00e9 suficiente: o pr\u00f3prio roteador selecionar\u00e1 um modelo ativo e mudar\u00e1 quando o limite for atingido.<\/p>\n
Como usar<\/h2>\n
Ap\u00f3s iniciar o opencode, a lista de modelos \u00e9 aberta com um comando familiar:<\/p>\n
\n\/models\n<\/code><\/pre>\n<\/div>\nTer\u00e1 um provedor FreeLLMAPI e um modelo autom\u00e1tico. Em seguida, o trabalho prossegue normalmente: descrevemos a tarefa, especificamos arquivos via @, alternamos o modo de planejamento com a tecla Tab, revertemos as edi\u00e7\u00f5es com o comando \/undo. Para um novo projeto, \u00e9 \u00fatil executar \/init para que o agente crie AGENTS.md.<\/p>\n
Algumas dicas pr\u00e1ticas:<\/p>\n
\n- Roteamento.<\/b> Para rotina, deixe em autom\u00e1tico. Se voc\u00ea precisa de velocidade, experimente auto:fast, se a qualidade for auto:smart ou um modelo espec\u00edfico forte do cat\u00e1logo.<\/li>\n
- Diagn\u00f3stico<\/b> Cada resposta do gateway cont\u00e9m um cabe\u00e7alho X-Routed-Via com o nome do provedor e modelo que realmente atendeu a solicita\u00e7\u00e3o. Mostra para onde o roteador enviou a tarefa.<\/li>\n
- Analytics.<\/b> Na p\u00e1gina Analytics, o painel mostra o volume de solicita\u00e7\u00f5es, sucesso, atrasos p50\/p95 e consumo de token por provedor.<\/li>\n
- Continuidade do di\u00e1logo.<\/b> Ao trocar de modelo no meio de uma conversa, o gateway pode adicionar uma breve nota sobre a transfer\u00eancia de contexto. Ativado pela vari\u00e1vel FREELLMAPI_CONTEXT_HANDOFF=on_model_switch.<\/li>\n<\/ul>\n
Se o OpenCode estiver sendo executado em um cont\u00eainer e o FreeLLMAPI estiver sendo executado em um host, localhost apontar\u00e1 para o pr\u00f3prio cont\u00eainer. Nesse caso, voc\u00ea precisa usar host.docker.internal ou outro endere\u00e7o acess\u00edvel a partir do cont\u00eainer no baseURL.<\/p>\n
No que prestar aten\u00e7\u00e3o<\/h2>\n
FreeLLMAPI n\u00e3o \u00e9 um substituto para modelos pagos e nem um servi\u00e7o com SLA. \u00c9 uma maneira de agrupar planos gratuitos em um \u00fanico gateway. Portanto, existem v\u00e1rias restri\u00e7\u00f5es:<\/p>\n
\n- A qualidade flutua.<\/b> As tarifas gratuitas terminam e, tarde da noite, mais perto do esgotamento das cotas di\u00e1rias, o roteador pode mudar para modelos mais fracos. As cotas geralmente s\u00e3o redefinidas \u00e0 meia-noite UTC.<\/li>\n
- As lat\u00eancias s\u00e3o vari\u00e1veis.<\/b> Diferentes provedores respondem de maneira diferente e, ao mudar para um modelo de backup, a solicita\u00e7\u00e3o pode demorar muito mais.<\/li>\n
- N\u00e3o existem modelos principais.<\/b> Modelos bons, mas n\u00e3o de \u00faltima gera\u00e7\u00e3o, est\u00e3o dispon\u00edveis em planos gratuitos. Para arquiteturas complexas, vale a pena considerar isso.<\/li>\n
- O gateway deve estar em execu\u00e7\u00e3o.<\/b> Se o aplicativo ou cont\u00eainer for interrompido, o OpenCode n\u00e3o receber\u00e1 uma resposta. A inicializa\u00e7\u00e3o autom\u00e1tica do aplicativo na bandeja ou a reinicializa\u00e7\u00e3o da pol\u00edtica de cont\u00eainer resolve esse problema.<\/li>\n
- O projeto foi projetado para um usu\u00e1rio.<\/b> As chaves do provedor s\u00e3o armazenadas localmente e criptografadas, mas um painel compartilhado por v\u00e1rias pessoas n\u00e3o \u00e9 o cen\u00e1rio para esta ferramenta. A chave unificada e o .env devem ser protegidos da mesma forma que um segredo normal.<\/li>\n<\/ul>\n
E mais uma nuance: o cat\u00e1logo de modelos se atualiza sozinho, mas a instala\u00e7\u00e3o gratuita recebe um instant\u00e2neo do cat\u00e1logo com um atraso de cerca de trinta dias. O plano pago Premium agiliza a atualiza\u00e7\u00e3o, mas n\u00e3o \u00e9 necess\u00e1rio conhecer o projeto – o pr\u00f3prio roteador permanece gratuito e aberto.<\/p>\n
Links<\/h2>\n
https:\/\/github.com\/tashfeenahmed\/freellmapi<\/a>
\nhttps:\/\/freellmapi.co\/<\/a>
\nhttps:\/\/freellmapi.co\/models<\/a>
\nhttps:\/\/github.com\/tashfeenahmed\/freellmapi\/releases\/latest<\/a>
\nhttps:\/\/github.com\/tashfeenahmed\/freellmapi\/blob\/main\/docs\/en\/install\/01-install.md<\/a>
\nhttps:\/\/github.com\/tashfeenahmed\/freellmapi\/blob\/main\/docs\/en\/clients\/01-agent-clients.md<\/a>
\nhttps:\/\/github.com\/tashfeenahmed\/freellmapi\/blob\/main\/cli\/README.md<\/a>
\nhttps:\/\/opencode.ai\/<\/a>
\nhttps:\/\/opencode.ai\/docs\/<\/a>
\nhttps:\/\/opencode.ai\/docs\/providers\/<\/a><\/p>\nFontes<\/h2>\n
https:\/\/github.com\/tashfeenahmed\/freellmapi<\/a>
\nhttps:\/\/github.com\/tashfeenahmed\/freellmapi\/blob\/main\/README.ru.md<\/a>
\nhttps:\/\/github.com\/tashfeenahmed\/freellmapi\/blob\/main\/docs\/en\/install\/01-install.md<\/a>
\nhttps:\/\/github.com\/tashfeenahmed\/freellmapi\/blob\/main\/docs\/en\/clients\/01-agent-clients.md<\/a>
\nhttps:\/\/github.com\/tashfeenahmed\/freellmapi\/blob\/main\/docs\/en\/clients\/02-supported-agents.md<\/a>
\nhttps:\/\/github.com\/tashfeenahmed\/freellmapi\/blob\/main\/cli\/README.md<\/a>
\nhttps:\/\/opencode.ai\/docs\/providers\/<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"OpenCode \u00e9 um agente de programa\u00e7\u00e3o aberto que funciona no terminal: l\u00ea arquivos de projeto, edita c\u00f3digo, executa comandos e testes, pesquisa no reposit\u00f3rio e trabalha com git. Ele n\u00e3o est\u00e1 vinculado a um provedor modelo, portanto, quase qualquer servi\u00e7o compat\u00edvel com OpenAI pode ser conectado a ele. FreeLLMAPI \u00e9 um roteador auto-hospedado aberto que […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[8],"tags":[],"class_list":["post-198","post","type-post","status-publish","format-standard","hentry","category-notes"],"translation":{"provider":"WPGlobus","version":"3.0.6","language":"pt","enabled_languages":["en","ru","zh","de","ja","fr","es","pt","hi"],"languages":{"en":{"title":true,"content":true,"excerpt":false},"ru":{"title":true,"content":true,"excerpt":false},"zh":{"title":true,"content":true,"excerpt":false},"de":{"title":true,"content":true,"excerpt":false},"ja":{"title":true,"content":true,"excerpt":false},"fr":{"title":true,"content":true,"excerpt":false},"es":{"title":true,"content":true,"excerpt":false},"pt":{"title":true,"content":true,"excerpt":false},"hi":{"title":true,"content":true,"excerpt":false}}},"_links":{"self":[{"href":"https:\/\/demensdeum.com\/blog\/pt\/wp-json\/wp\/v2\/posts\/198","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/demensdeum.com\/blog\/pt\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/demensdeum.com\/blog\/pt\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/demensdeum.com\/blog\/pt\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/demensdeum.com\/blog\/pt\/wp-json\/wp\/v2\/comments?post=198"}],"version-history":[{"count":1,"href":"https:\/\/demensdeum.com\/blog\/pt\/wp-json\/wp\/v2\/posts\/198\/revisions"}],"predecessor-version":[{"id":199,"href":"https:\/\/demensdeum.com\/blog\/pt\/wp-json\/wp\/v2\/posts\/198\/revisions\/199"}],"wp:attachment":[{"href":"https:\/\/demensdeum.com\/blog\/pt\/wp-json\/wp\/v2\/media?parent=198"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/demensdeum.com\/blog\/pt\/wp-json\/wp\/v2\/categories?post=198"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/demensdeum.com\/blog\/pt\/wp-json\/wp\/v2\/tags?post=198"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}