{"slug": "guia-definitivo-para-usar-o-claude-code-com-modelos-gratuitos-depois-de-testar-6", "title": "Guia definitivo para usar o Claude Code com modelos gratuitos (depois de testar 6 métodos)", "summary": "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.", "body_md": "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.\n\nDiferente 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.\n\nEu 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.\n\nO 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:\n\nApontei para a API do OpenRouter usando arquivo de configurações do claude em ~/.claude/settings.json, e usei um modelo gratuito para esse teste.\n\nFuncionou 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.\n\nO 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.\n\nPassei um bom tempo configurando o `config.json`\n\n. Testei apontar para provedores diferentes:\n\nNenhum funcionou, o erro mais comum era `\"Missing model in request body\"`\n\n.\n\n**O que esse erro significa na prática?**\n\nO 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.\n\nO erro `\"Missing model in request body\"`\n\nindica 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`\n\n. Sem o nome do modelo, o provedor não sabia qual IA deveria responder.\n\nCriei conta na NVIDIA. Peguei a chave gratuita, porém após configurar o proxy recebi o retorno `404 page not found`\n\nao 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.\n\nDepois 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).\n\nDessa vez o proxy retornava `200 OK`\n\n. Eu achei que tinha resolvido, mas o Claude Code mostrava `\"Provider API request failed\"`\n\n. 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.\n\nA causa: modelos Gemini exigem que os `reasoning_details`\n\n(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.\n\n`free-claude-code`\n\né um projeto impressionante, mas a combinação com o `OpenRouter`\n\nainda é problemática por uma limitação da própria API do OpenRouter. Funciona para perguntas simples, quebra em tarefas reais.\n`ollama launch claude`\n\n. Parecia promissor. Modelo local, sem depender de API externa.\n\nAí 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.\n\nO 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.\n\n```\nnpm install -g claude-code-gemini\ncc-gemini\n```\n\nPegue sua chave gratuita do Google Gemini em ** aistudio.google.com/apikey**. O\n\n`cc-gemini`\n\nvai 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.\n\nPorém, perguntas complexas demoram mais. Quando testei fazer o `/init`\n\nnum 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`\n\n. 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.\n\n5 minutos me pareceu bem aceitável para uma tarefa de primeira análise do projeto e criação do CLAUDE.md.\n\nDois 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.\n\nO pacote `claude-code-gemini`\n\ncria 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.\n\nPara forçar o Claude Code a usar esse proxy, o `cc-gemini`\n\nfaz duas coisas:\n\n`sk-gemini-proxy`\n\nno arquivo de configuração do Claude (`~/.claude.json`\n\n)`ANTHROPIC_API_KEY=\"sk-gemini-proxy\"`\n\nÉ 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.\n\nToda vez que eu rodava `cc-gemini`\n\n, aparecia um alerta perguntando se eu queria usar a chave do ambiente. O alerta é inofensivo, mas repetitivo.\n\n**Solução permanente:** editar o arquivo `cli.js`\n\ndo `cc-gemini`\n\ne remover a linha `ANTHROPIC_API_KEY: \"sk-gemini-proxy\"`\n\n. 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.\n\n| Método | Veredito |\n|---|---|\nOpenRouter |\nÓtimo para testes rápidos, mas o limite de 50 requisições por dia trava qualquer uso sério. |\nClaude Code Router |\nTecnicamente robusto, mas a configuração é frágil. Um erro no JSON quebra tudo. |\nNVIDIA NIM |\nTem potencial, mas o processo de ativação manual (1-2 dias de espera) inviabiliza para quem quer começar agora. |\nfree-claude-code |\nProjeto impressionante, mas a tradução das tools quebra com frequência. |\nOllama |\nViável apenas com GPU dedicada. Em CPU comum, o tempo de resposta inviabiliza o uso interativo. |\ncc-gemini |\nFunciona de primeira. Sem configuração. Sem dor de cabeça. |\n\nDepois 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.\n\nDe 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:\n\nAs 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.\n\n**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`\n\n, 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.\n\n| Métrica | Resultado |\n|---|---|\nTempo de configuração |\n2 minutos |\nRespostas simples |\n10-15 segundos |\nRespostas complexas |\n3-5 minutos |\nCusto |\nR$ 0 |\nLimite diário |\n250 requisições |\nReset do limite |\nMeia-noite (Pacific Time) |", "url": "https://wpnews.pro/news/guia-definitivo-para-usar-o-claude-code-com-modelos-gratuitos-depois-de-testar-6", "canonical_source": "https://dev.to/vitor_maverickfonsecado/guia-definitivo-para-usar-o-claude-code-com-modelos-gratuitos-depois-de-testar-5-metodos-1ieo", "published_at": "2026-05-31 07:28:27+00:00", "updated_at": "2026-05-31 07:40:58.275748+00:00", "lang": "en", "topics": ["ai-tools", "ai-agents", "large-language-models", "artificial-intelligence"], "entities": ["Claude Code", "OpenRouter", "Skilljar", "Cursor", "Copilot"], "alternates": {"html": "https://wpnews.pro/news/guia-definitivo-para-usar-o-claude-code-com-modelos-gratuitos-depois-de-testar-6", "markdown": "https://wpnews.pro/news/guia-definitivo-para-usar-o-claude-code-com-modelos-gratuitos-depois-de-testar-6.md", "text": "https://wpnews.pro/news/guia-definitivo-para-usar-o-claude-code-com-modelos-gratuitos-depois-de-testar-6.txt", "jsonld": "https://wpnews.pro/news/guia-definitivo-para-usar-o-claude-code-com-modelos-gratuitos-depois-de-testar-6.jsonld"}}