Como Usar Claude Code com OpenRouter: Tutorial Completo

Se você aprecia o fluxo de trabalho fluido do Claude Code (a ferramenta de linha de comando da Anthropic), então você provavelmente sabe que, por padrão, ele espera o formato da API da Anthropic. Mas e se você quiser usar um modelo diferente, ou explorar novos modelos que não estão disponíveis através da API direta da Anthropic? É aí que o OpenRouter entra! Ele fornece acesso unificado e compatível com a API OpenAI a centenas de modelos de muitos provedores diferentes.

Ao unir os dois sistemas, você pode ter o melhor dos dois mundos: a interface amigável para desenvolvedores do Claude Code e o vasto catálogo de modelos do OpenRouter. Esta integração é o que chamamos de “Claude Code com Openrouter.”

O truque é usar um "roteador / proxy" que traduz entre os dois formatos de API. Uma vez configurado, você pode executar o Claude Code como de costume, mas com o OpenRouter impulsionando o backend.

Principais Vantagens de Usar o Claude Code com Openrouter

Combinar Claude Code e Openrouter desbloqueia uma série de benefícios poderosos:

• Acesso a mais de 400 modelos — incluindo variantes Claude, modelos estilo GPT, LLMs de código aberto e muito mais.
• Não é necessário assinatura Anthropic — você paga apenas pelo que usa através do modelo de pagamento por uso do Openrouter.
• Troca flexível de modelos — mude de modelo durante a sessão no Claude Code com /model, ou roteie com base no tipo de tarefa (leve vs raciocínio, custo vs desempenho).
• Otimização de custos — modelos de baixo custo ou gratuitos para tarefas rotineiras, modelos poderosos apenas quando necessário: ideal para desenvolvedores preocupados com o orçamento.
• Roteamento local ou baseado em nuvem — execute tudo localmente para privacidade, ou hospede seu roteador para uso compartilhado em equipe, CI/CD ou automação em nuvem.
• Ferramentas e flexibilidade — alguns roteadores suportam recursos avançados como streaming, fallback de modelo, multiplexação de múltiplos provedores e integração com fluxos de trabalho de desenvolvimento mais amplos.

Pré-requisitos

Antes de começar, certifique-se de ter:

1. Claude Code instalado globalmente (por exemplo, via npm install -g @anthropic-ai/claude-code).

2. Uma **conta Openrouter** com uma chave API válida (sk-or-...) (Crie uma conta em OpenRouter).

3. Uma ferramenta de roteador/proxy (Docker é o mais fácil, mas roteadores baseados em Node.js também funcionam) para lidar com a conversão de formato

4. Conforto básico no uso de variáveis de ambiente e linha de comando

Com esta configuração, você poderá direcionar o Claude Code para o roteador — que então encaminhará as requisições para o Openrouter e roteará as respostas de volta.

Método 1: y-router (Mais Simples e Recomendado)

Um dos roteadores mais amplamente usados para esta configuração é o y-router. Ele atua como um tradutor entre o formato de API esperado pela Anthropic e a API estilo OpenAI do Openrouter (veja o repositório em: GitHub). Veja como fazer isso passo a passo com o y-router:

1. Implante o y-router localmente (Docker recomendado):

git clone https://github.com/luohy15/y-router.git
cd y-router
docker compose up -d

Isso levanta um serviço de roteador local escutando (por padrão) em http://localhost:8787.

2. Configure suas variáveis de ambiente para que o Claude Code envie suas requisições para o y-router, não diretamente para a Anthropic:

export ANTHROPIC_BASE_URL="http://localhost:8787"
export ANTHROPIC_AUTH_TOKEN="sk-or-<sua-chave-openrouter>"
export ANTHROPIC_MODEL="z-ai/glm-4.5-air"   # para um modelo rápido e leve
# ou export ANTHROPIC_MODEL="z-ai/glm-4.5"   # para um modelo mais poderoso

3. Execute o Claude Code:

claude

A interface será iniciada normalmente. Se você digitar /model, verá o modelo alimentado pelo Openrouter selecionado. Parabéns — você agora está usando o Claude Code com Openrouter. (ishan.rs)

Este método mantém o roteamento local, simples e sob seu controle — ideal para desenvolvedores que valorizam a privacidade e baixa sobrecarga.

Método 2: Claude Code Router (baseado em npm, Rico em Recursos)

Se você preferir não usar Docker, existe outra opção robusta: Claude Code Router — uma ferramenta de roteador baseada em Node.js projetada para dar ao Claude Code acesso a provedores externos (veja o repositório em GitHub). Veja como configurá-lo:

1. Instale globalmente:

npm install -g @musistudio/claude-code-router

Em seguida, crie um arquivo de configuração (por exemplo, ~/.claude-code-router/config.json) com suas configurações e modelos preferidos. Muitos usuários incluem o Openrouter como provedor, especificando sua chave API e listando os modelos suportados (mais detalhes sobre este método em lgallardo.com).

2. Inicie o roteador:

ccr start

Uma vez em execução, defina ANTHROPIC_BASE_URL para a URL do roteador e use claude como de costume. O roteador traduzirá as requisições e permitirá a troca dinâmica entre modelos — incluindo comportamento de fallback, regras de roteamento e muito mais.

Este método é poderoso se você deseja mais controle sobre o roteamento de modelos, políticas de fallback ou integração em cadeias de ferramentas maiores (como CI/CD, scripts automatizados ou experimentos com múltiplos modelos).

Método 3: Proxy Direto do Openrouter (Configuração Mínima para Testes Rápidos)

Se você deseja apenas uma verificação rápida ou teste — sem executar um roteador completo — você pode tentar apontar o Claude Code diretamente para um proxy compatível com Openrouter ou um adaptador mínimo. Algumas soluções da comunidade existem para facilitar isso (veja o repositório em GitHub).

Por exemplo, você pode definir:

export ANTHROPIC_BASE_URL="https://proxy-your-choice.com"
export ANTHROPIC_AUTH_TOKEN="sk-or-<sua-chave>"
export ANTHROPIC_MODEL="openrouter/nome-do-modelo"

Em seguida, execute o Claude Code. Esta abordagem é útil para testes efêmeros ou experimentos rápidos. No entanto, pode faltar robustez (por exemplo, para streaming, chamadas de ferramenta ou sessões de longo prazo), dependendo da implementação do proxy.

Melhores Práticas e Dicas para uma Experiência Tranquila

1. Verifique a compatibilidade do modelo — nem todos os modelos suportam recursos avançados como chamadas de ferramenta ou janelas de contexto longo. Use modelos mais leves para tarefas simples, modelos mais capazes para tarefas pesadas como raciocínio ou codificação.
2. Proteja sua chave API — trate sua chave API do Openrouter como um segredo; armazene-a de forma segura e nunca a exponha no lado do cliente.
3. Gerencie os custos — monitore o uso de tokens ao usar modelos grandes; considere cache de prompts, modelos de fallback ou roteamento baseado em tarefas para otimizar o equilíbrio custo/desempenho.
4. Teste a configuração de roteamento — após a configuração, sempre teste com comandos simples (por exemplo, claude --model <modelo>) para garantir que tudo seja roteado corretamente.
5. Use roteamento de fallback para confiabilidade — em configurações multi-modelo, configure opções de fallback para que, se um modelo estiver indisponível, o roteador possa alternar para outro automaticamente.

Perguntas Frequentes

P1. Preciso pagar pela Anthropic para usar o Claude Code com Openrouter?
Não. Quando configurado com Openrouter (via roteador ou proxy), o Claude Code usa sua chave API do Openrouter para as requisições — você não precisa de uma assinatura paga da Anthropic.

P2. Posso trocar de modelos dinamicamente dentro da mesma sessão do Claude Code?
Sim. Muitos roteadores (e o próprio Claude Code) permitem que você troque de modelos usando /model <nome_do_modelo>. Isso funciona no meio da conversa na maioria dos casos.

P3. Todos os modelos no Openrouter são compatíveis com os recursos do Claude Code (como execução de ferramentas, streaming)?
Nem sempre. Alguns modelos “apenas de texto” ou mais leves podem não suportar chamadas de ferramenta, contexto longo ou streaming. Para fluxos de trabalho complexos, use modelos conhecidos por suportar esses recursos.

P4. Um roteador Docker local é mais seguro do que um hospedado?
Geralmente sim. Executar um roteador localmente lhe dá controle total e evita expor sua chave API a serviços externos. Roteadores hospedados são convenientes, mas podem apresentar trade-offs de segurança ou confiabilidade.

P5. Posso integrar esta configuração em CI/CD ou fluxos de trabalho automatizados?
Com certeza. Ferramentas como o Claude Code Router suportam arquivos de configuração e variáveis de ambiente, o que as torna fáceis de integrar em pipelines de automação (GitHub Actions, scripts, etc.).

Conclusão

Usar o Claude Code com Openrouter é uma maneira elegante e poderosa de se libertar das amarras de um único provedor, mantendo uma interface de desenvolvedor familiar e simplificada. Seja escolhendo executar um roteador local via Docker, usar um roteador baseado em Node.js ou testar via um proxy mínimo — você está abrindo a porta para um catálogo massivo de modelos, opções de custo flexíveis e fluxos de trabalho personalizados.

Para desenvolvedores, projetos paralelos ou equipes que buscam otimizar a codificação impulsionada por IA sem grandes custos indiretos, esta configuração oferece um equilíbrio atraente de controle, flexibilidade e escalabilidade. Com apenas alguns passos de configuração, você pode expandir drasticamente o que seu assistente de IA pode fazer — e então mudar ou escalar conforme suas necessidades evoluem.

Experimente: sua próxima sessão de código pode em breve ser alimentada por um modelo que você nunca imaginou ser possível — tudo sob a familiar interface do Claude Code.