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

Vitor Maverick Fonseca dos Santos — Sun, 31 May 2026 07:28:27 +0000

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.

A motivação

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:

Método 1: OpenRouter direto

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.

Método 2: Claude Code Router (CCR)

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:

OpenRouter (modelos gratuitos como Qwen e Gemini via API)
NVIDIA NIM (modelos próprios da NVIDIA)
DeepSeek (compatível via endpoint adaptado)

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.

Método 3: free-claude-code + NVIDIA NIM

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.

Método 4: free-claude-code + OpenRouter

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.

O `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.

Método 5: Ollama modelo local

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 que funcionou: cc-gemini

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.

O desempenho

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.

Por que o Gemini demora mais?

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.

Como o cc-gemini funciona por dentro

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:

Injeta a chave sk-gemini-proxy no arquivo de configuração do Claude (~/.claude.json)
Define a variável de ambiente 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.

O único inconveniente (e como resolvê-lo)

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.

O que eu aprendi com cada método

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.

Estado final

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:

10 requisições por minuto
250 requisições por dia
250 mil tokens por minuto

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)

DEV Community: Vitor Maverick Fonseca dos Santos

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

A motivação

Método 1: OpenRouter direto

Método 2: Claude Code Router (CCR)

Método 3: free-claude-code + NVIDIA NIM

Método 4: free-claude-code + OpenRouter

O `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.

Método 5: Ollama modelo local

O que funcionou: cc-gemini

O desempenho

Por que o Gemini demora mais?

Como o cc-gemini funciona por dentro

O único inconveniente (e como resolvê-lo)

O que eu aprendi com cada método

Estado final

[Boost]

Code Agents: Como aumentar a produtividade sem se tornar dependente

DEV Community: Vitor Maverick Fonseca dos Santos

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

A motivação

Método 1: OpenRouter direto

Método 2: Claude Code Router (CCR)

Método 3: free-claude-code + NVIDIA NIM

Método 4: free-claude-code + OpenRouter

O 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.

Método 5: Ollama modelo local

O que funcionou: cc-gemini

O desempenho

Por que o Gemini demora mais?

Como o cc-gemini funciona por dentro

O único inconveniente (e como resolvê-lo)

O que eu aprendi com cada método

Estado final

[Boost]

Code Agents: Como aumentar a produtividade sem se tornar dependente

O `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.