Guia definitivo para usar o Claude Code com modelos gratuitos (depois de testar 6 métodos)

A developer tested six methods to use Claude Code with free AI models, finding that only one worked reliably. The engineer encountered failures with OpenRouter's free tier due to rate limits, proxy translation errors with the CCR tool, and broken tool-handling when routing through NVIDIA NIM and OpenRouter. The successful method involved configuring the Claude CLI to use a local Ollama instance, bypassing the API limitations that caused other approaches to fail on multi-step tasks.

Antes de começar: você sabe o que é o Claude Code? Não estou falando da GUI Graphical User Interface que acessamos no navegador pra fazer perguntas. O Claude Code é exatamente o oposto: é um agente de IA que vive no seu terminal. Não possui interface gráfica, mas também tem se tornado muito útil no dia a dia do desenvolvedor de software. Diferente de ferramentas como Cursor ou Copilot que são plugins de IDE , o Claude Code roda no terminal, lê e escreve arquivos diretamente, executa comandos shell e faz tarefas de múltiplas etapas de forma autônoma. Você não copia e cola código entre uma aba do navegador e seu editor. Você digita um comando no terminal e ele age. Eu queria fazer o curso "Claude Code in Action" no Skilljar. O curso é gratuito, ensina na prática como usar o Claude Code no terminal, e os exercícios exigem que você execute comandos reais. O problema? O curso é grátis, mas a ferramenta não. Logo comecei a buscar por alternativas gratuitas que não pesassem no bolso. Para minha surpresa, encontrei muito conteúdo na internet, porém nem todos atualizados. Testei 6 métodos diferentes e somente um funcionou como esperado. Seguem os métodos testados: Apontei para a API do OpenRouter usando arquivo de configurações do claude em ~/.claude/settings.json, e usei um modelo gratuito para esse teste. Funcionou por 10 minutos e então veio o retorno de erro 429: limite de requisições excedido. O plano gratuito do OpenRouter permite 50 requisições por dia, e em 10 minutos de teste eu já tinha usado todas. O CCR é um proxy que promete fazer o Claude Code original não um fork modificado se comunicar com qualquer provedor. A ideia era rodar o cliente oficial da Anthropic, mas redirecionar as requisições para modelos gratuitos de outras plataformas. Passei um bom tempo configurando o config.json . Testei apontar para provedores diferentes: Nenhum funcionou, o erro mais comum era "Missing model in request body" . O que esse erro significa na prática? O CCR funciona como um tradutor entre o Claude Code e o provedor terceiro. Quando o Claude Code envia uma requisição, o CCR precisa extrair o nome do modelo e injetá-lo no corpo da requisição para o provedor. O erro "Missing model in request body" indica que o CCR não estava fazendo essa injeção corretamente . Ele enviava a requisição para o OpenRouter, NVIDIA ou DeepSeek sem o campo model . Sem o nome do modelo, o provedor não sabia qual IA deveria responder. Criei conta na NVIDIA. Peguei a chave gratuita, porém após configurar o proxy recebi o retorno 404 page not found ao tentar conectar com o modelo. Fazendo uma pesquisa rápida, o problema parece ser com todas as contas gratuitas da NVIDIA, que precisam de permissão manual para usar a API pública. Não achei fácil de configurar, então passei para a próxima opção. Depois do fracasso com NVIDIA NIM, resolvi testar o mesmo proxy apontando para o OpenRouter. A ideia era usar os modelos gratuitos que o OpenRouter disponibiliza Qwen, Gemma, DeepSeek R1, entre outros . Dessa vez o proxy retornava 200 OK . Eu achei que tinha resolvido, mas o Claude Code mostrava "Provider API request failed" . O problema era específico: a tradução das tools ferramentas estava quebrada. O padrão era sempre o mesmo: a primeira requisição funcionava, o Claude Code executava a ferramenta, mas na segunda requisição enviando o resultado da tool de volta o proxy quebrava. A causa: modelos Gemini exigem que os reasoning details tokens criptografados sejam preservados entre requisições . O OpenRouter não envia esses tokens em respostas com streaming , e o Claude Code usa streaming o tempo todo. Sem os tokens, a segunda requisição falha com HTTP 400. free-claude-code é um projeto impressionante, mas a combinação com o OpenRouter ainda é problemática por uma limitação da própria API do OpenRouter. Funciona para perguntas simples, quebra em tarefas reais. ollama launch claude . Parecia promissor. Modelo local, sem depender de API externa. Aí pedi "oi". O modelo levou mais de 5 minutos tentando responder. Para perguntas mais elaboradas, só Deus sabe quanto tempo demoraria. Ao que tudo indica, sem GPU dedicada, modelos locais são impraticáveis para uso interativo. O repositório oficial está no GitHub: github.com/yuqie6/claude-code-gemini . O projeto resolve um problema específico: o Claude Code original só fala com a API da Anthropic. Este proxy traduz as requisições em tempo real para o formato que o Gemini entende. npm install -g claude-code-gemini cc-gemini Pegue sua chave gratuita do Google Gemini em aistudio.google.com/apikey . O cc-gemini vai pedir essa chave na primeira execução. Um proxy local sobe na porta 8100. O Claude Code abre, possibilitando testar as principais funcionalidades.Perguntas simples que exigem pouca capacidade de planejamento e ação funcionaram muito bem. Comandos básicos como "liste os arquivos", "explique este código", "renomeie esta função". Para esses exercícios, o Gemini respondeu rápido — cerca de 10 a 15 segundos. Porém, perguntas complexas demoram mais. Quando testei fazer o /init num projeto grande, com mais de 500 linhas de código, o modelo levou cerca de 5 minutos para analisar o projeto e criar o CLAUDE.md . Foi um desempenho demorado quando comparado com o Claude Code comum, que utiliza um modelo próprio e demorou somente 1 minuto e 34 segundos. 5 minutos me pareceu bem aceitável para uma tarefa de primeira análise do projeto e criação do CLAUDE.md. Dois motivos, o primeiro é que o proxy traduz em tempo real cada conversão adiciona latência. Segundo, o Gemini é mais conservador, ele pensa mais antes de agir. Em tarefas que exigem múltiplas ferramentas ler arquivo, escrever arquivo, rodar teste, corrigir erro , o Claude Code é bem mais rapido. MAs embora seja mais devagar, o Gemini me pareceu bem metódico , levando a um resultado final é similar, com um código gerado que tem qualidade comparável. O pacote claude-code-gemini cria um proxy local usando LiteLLM. Esse proxy recebe as requisições no formato da Anthropic e traduz para o formato da API do Google Gemini. Para forçar o Claude Code a usar esse proxy, o cc-gemini faz duas coisas: sk-gemini-proxy no arquivo de configuração do Claude ~/.claude.json ANTHROPIC API KEY="sk-gemini-proxy" É por isso que, nas versões mais recentes do Claude Code, aparece um alerta perguntando se você quer usar a chave do ambiente. A resposta certa é sempre "Yes" opção 1 . O "recommended" ao lado do "No" é um aviso genérico da Anthropic — ignore. Toda vez que eu rodava cc-gemini , aparecia um alerta perguntando se eu queria usar a chave do ambiente. O alerta é inofensivo, mas repetitivo. Solução permanente: editar o arquivo cli.js do cc-gemini e remover a linha ANTHROPIC API KEY: "sk-gemini-proxy" . A chave continua sendo injetada pelo arquivo de configuração, então o proxy continua funcionando. O alerta some e o claude-code-gemini roda em silêncio. Sem perguntas. Sem interrupções. | Método | Veredito | |---|---| OpenRouter | Ótimo para testes rápidos, mas o limite de 50 requisições por dia trava qualquer uso sério. | Claude Code Router | Tecnicamente robusto, mas a configuração é frágil. Um erro no JSON quebra tudo. | NVIDIA NIM | Tem potencial, mas o processo de ativação manual 1-2 dias de espera inviabiliza para quem quer começar agora. | free-claude-code | Projeto impressionante, mas a tradução das tools quebra com frequência. | Ollama | Viável apenas com GPU dedicada. Em CPU comum, o tempo de resposta inviabiliza o uso interativo. | cc-gemini | Funciona de primeira. Sem configuração. Sem dor de cabeça. | Depois de alguns minutos usando o cc-gemini para analisar projetos mais completos, algo aconteceu: finalmente atingi o rate limit do Gemini. A mensagem de erro apareceu no terminal, e o Claude Code parou de responder. Foi um momento "ah, então era real mesmo". O limite existe. E você precisa saber como ele funciona para não ser pego de surpresa durante o curso ou num momento crítico de trabalho. De acordo com a documentação oficial do Google, os limites do Gemini API no tier gratuito funcionam em múltiplas dimensões: requisições por minuto RPM , tokens por minuto TPM e requisições por dia RPD . Para o modelo Gemini 2.5 Flash que o cc-gemini usa por padrão , os limites são: As requisições por dia RPD resetam à meia-noite no horário do Pacífico Pacific Time — para quem está no Brasil, isso significa que o contador zera por volta das 4h da manhã horário de verão nos EUA ou 3h fora do horário de verão . O Google também implementou em maio de 2026 um sistema de "cota baseada em computação" que considera a complexidade das tarefas — ou seja, uma análise de código pesada consome mais cota do que um "oi". A cota tem dois níveis: um limite que reseta a cada 5 horas e um limite semanal total. Isso significa que mesmo que você espere o reset diário, se já usou muito na semana, pode continuar bloqueado até o ciclo semanal reiniciar. Ou seja, nem tudo que brilha é ouro. Essa opção também tem contras. Porém, dado o fracasso dos demais testes, o cc-gemini foi o mais eficaz e o único que realmente funcionou com um desempenho próximo ao do Claude Code oficial. Hoje eu abro o terminal, digito cc-gemini , e o Claude Code está lá. Perguntas simples respondem em 10-15 segundos. Perguntas complexas podem levar alguns minutos, mas a qualidade é comparável ao modelo pago. | Métrica | Resultado | |---|---| Tempo de configuração | 2 minutos | Respostas simples | 10-15 segundos | Respostas complexas | 3-5 minutos | Custo | R$ 0 | Limite diário | 250 requisições | Reset do limite | Meia-noite Pacific Time |