Tutorial do Claude Code Router: conecte o Claude Code ao DeepSeek, Gemini ou qualquer modelo
O router de código aberto mantém a experiência do Claude Code, mas envia cada requisição para modelos mais baratos — DeepSeek, Kimi, Gemini ou um modelo local do Ollama. Instale com npm, configure os provedores no console ccr ui, defina rotas por cenário e rode uma tarefa real para comprovar. 15 passos com capturas de tela.
Resumo: o que o Claude Code Router faz
- O Claude Code Router (CCR) é um proxy gratuito e de código aberto: o Claude Code mantém a interface, o prompt de sistema e as ferramentas, mas as chamadas de modelo vão para o que você configurar — DeepSeek, Kimi K2, Gemini, OpenRouter ou um modelo local do Ollama.
- A instalação é um único comando npm (npm install -g @musistudio/claude-code-router) e o console web ccr ui edita o ~/.claude-code-router/config.json para você — sem precisar editar JSON à mão.
- O roteamento é por cenário: default, background, think (raciocínio do Plan Mode), longContext (entra em ação automaticamente acima do limite de 60 mil tokens) e webSearch recebem cada um seu próprio modelo.
- ccr code inicia uma sessão roteada com a URL base apontando para http://127.0.0.1:3456; o comando claude simples continua funcionando normalmente. Particularidade conhecida: o /cost fica em $0, então acompanhe o gasto no painel do provedor.
Claude Code Router: Use Gemini 2.5 Pro FREE API in Claude Code
Vídeo de origem:AI With Nathan10:52
claude-code-router — official README
Fatos do produto:musistudio on GitHubDocs
Os passos e capturas seguem o vídeo; os nomes de campos do config.json, os papéis do router e o comportamento dos transformers foram conferidos com o README oficial.
Os frames são capturas creditadas do vídeo de origem, cada uma com link para seu instante exato. O texto deste guia é original — não é uma transcrição.
Configure o Claude Code Router passo a passo
1 · Aponte o Claude Code para modelos mais baratos
- 1
Veja por que o Claude Code precisa de um router
O Claude Code está preso aos modelos Claude, e eles são caros: o Opus 4.1 custa oficialmente US$ 15 por milhão de tokens de entrada e US$ 75 por milhão de saída. O Claude Code Router (CCR), um projeto de código aberto, preserva a experiência do Claude Code mas encaminha cada requisição para o modelo que você escolher — DeepSeek, Kimi, Gemini ou um modelo local do Ollama.
Os preços de tabela da Anthropic antes da troca — essa é a conta que o CCR evita.Ver em 0:30 - 2
Instale o Claude Code e depois o router
O CCR pressupõe que o Claude Code já está instalado: npm install -g @anthropic-ai/claude-code. Depois instale o router: npm install -g @musistudio/claude-code-router. Sua configuração de provedores ficará em ~/.claude-code-router/config.json.
As duas instalações npm do README oficial — o router nunca substitui o Claude Code.Ver em 3:36 - 3
Deixe o npm terminar a instalação global
O npm baixa as dependências do router (um aviso de deprecação do node-domexception é normal). Quando terminar, o comando ccr fica disponível em qualquer lugar.
npm baixando pacotes durante a instalação global do @musistudio/claude-code-router.Ver em 3:49
2 · Adicione provedores no console ccr ui
- 4
Abra o console de configuração com ccr ui
Em vez de editar o JSON à mão, execute ccr ui. Uma aba do navegador abre em 127.0.0.1:3456: os provedores ficam à esquerda, a seção Router à direita atribui modelos a cenários e os Custom Transformers ficam abaixo.
Primeira abertura do console ccr ui — provedores vazios, vagas do router aguardando.Ver em 4:08 - 5
Adicione um provedor a partir de um template
Clique em Add Provider e escolha um template — o vídeo usa o OpenRouter; há presets também para deepseek, gemini, dashscope, modelscope, siliconflow e volcengine. O template preenche a URL da API e uma lista padrão de modelos, e você pode deixar o transformer vazio.
Templates de provedores no ccr ui — escolha um e a URL e os modelos se preenchem sozinhos.Ver em 4:30 - 6
Cole a API key e escolha seus modelos
Três campos importam de verdade: a URL da API (já preenchida), a chave secreta e a lista de modelos. O vídeo adiciona DeepSeek R1 e Kimi K2 no OpenRouter e salva — o provedor aparece no painel esquerdo, pronto para atribuir.
O formulário Edit Provider: URL, chave e modelos — todo o resto pode ficar no padrão.Ver em 4:53 - 7
Deixe os transformers cuidarem das diferenças de API
Os transformers reescrevem requisições e respostas para que APIs de terceiros continuem compatíveis com o Claude Code. O CCR vem com padrões sensatos — por exemplo, um transformer deepseek para api.deepseek.com e um tooluse para o deepseek-chat — então você raramente escreverá o seu.
Exemplos de transformers globais e específicos por modelo do README, incluindo o preset do DeepSeek.Ver em 3:54 - 8
Adicione uma chave gratuita do Gemini para tarefas de raciocínio
Adicione um segundo provedor com o template do Gemini e crie uma API key gratuita no Google AI Studio (Get API key → Create API key). Cole, salve — em breve você atribuirá esse provedor às vagas de raciocínio, contexto longo e busca na web.
Criando a API key gratuita do Gemini no Google AI Studio para o provedor do CCR.Ver em 5:45
3 · Defina as regras de roteamento
- 9
Entenda os cinco papéis do router
default cuida das tarefas gerais (e de tudo que você não atribuir). background executa trabalhos em segundo plano — um modelo pequeno ou local economiza aqui. think cobre raciocínio pesado como o Plan Mode. longContext entra automaticamente acima do longContextThreshold (60 mil tokens por padrão), e o webSearch precisa de um modelo que suporte o recurso — no OpenRouter, acrescente :online ao nome do modelo. /model troca de modelo no meio da sessão.
O objeto Router no README: cada papel, o limite de 60 mil e o sufixo :online.Ver em 1:06 - 10
Atribua um modelo a cada cenário
Na seção Router, escolha entre os modelos dos seus provedores salvos: o vídeo define DeepSeek R1 como default, Kimi K2 para o uso geral, Gemini 2.5 Pro (janela de 1 milhão de tokens) para longContext e o rápido Gemini Flash para webSearch. Clique em Save and Restart no canto superior direito ao terminar.
Preenchendo a vaga Default com deepseek/deepseek-r1-0528 do provedor salvo.Ver em 5:15 - 11
Inicie a sessão roteada com ccr code
De volta ao terminal, execute ccr code. A tela de boas-vindas do Claude Code lista Overrides (via env) — API Base URL http://127.0.0.1:3456 — provando que as requisições agora passam pelo router. O comando claude simples ainda abre uma sessão sem roteamento, sem precisar desinstalar nada.
O bloco Overrides na tela de boas-vindas: seu tráfego passa pelo proxy local do CCR.Ver em 6:45
4 · Rode uma tarefa real e verifique
- 12
Dê a ele uma tarefa de programação real
Escreva o prompt como sempre — o vídeo pede um jogo de quebra-blocos neon com animações modernas. O Claude Code planeja uma lista de tarefas e a executa passo a passo pelos modelos roteados. Espere pequenas excentricidades visuais: o contador de tokens de entrada pode ficar em zero.
O Claude Code avançando pela lista de tarefas enquanto o CCR encaminha as chamadas de modelo.Ver em 7:06 - 13
Revise o resultado pronto
O agente encerra com um resumo de recursos — efeitos visuais, design responsivo, controles, mecânicas de jogo — e os arquivos ficam no seu projeto (index.html, style.css, script.js). Abra o HTML no navegador para testar o resultado você mesmo.
Resumo de conclusão do Claude Code para o jogo de quebra-blocos neon.Ver em 7:30 - 14
Verifique o uso real no painel do provedor
A página Your Activity do OpenRouter é a fonte da verdade: ela mostra as chamadas roteadas — requisições repetidas de Kimi K2 e a chamada ao DeepSeek — com contagem de tokens e gastos. É assim que você confirma que o CCR está mesmo usando seus modelos mais baratos.
Uso do OpenRouter após a sessão: os modelos roteados aparecem com contagens reais de requisições.Ver em 7:45 - 15
Conheça as falhas antes de depender dele
Execute /cost numa sessão roteada e ele reporta US$ 0,0000, com o uso por modelo mostrando claude-sonnet em zero — a contabilidade de custos ainda não está conectada aos provedores externos. O roteamento em si funciona bem; por enquanto, acompanhe o gasto no painel do provedor.
A falha conhecida do /cost em sessões roteadas — os painéis dos provedores são seu medidor real.Ver em 9:25