# Guia definitivo para usar o Claude Code com modelos gratuitos (depois de testar 6 métodos) > Source: > Published: 2026-05-31 07:28:27+00:00 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) |