OpenRouter + Claude Code · Master Guide

O mapa antes da estrada

Você não está instalando o OpenRouter dentro do Claude. Está ensinando o Claude Code a enviar suas chamadas para outra portaria.

Claude Codelê, planeja, executa

→

OpenRouterautentica, roteia, mede uso

→

ModeloSonnet, Opus ou outro

Quero programar no terminal

Use a configuração do Claude Code CLI. É a rota principal.

Quero conversar no aplicativo

Use o Gateway de terceiros do Claude Desktop.

Leia antes de tocar nas configurações

OpenRouter é um gateway de inferência. MCP conecta ferramentas; OpenRouter conecta modelos. Assinatura Claude Pro/Max, créditos da API Anthropic e créditos OpenRouter são caixas financeiras diferentes.

Crie uma chave com limites

A chave é dinheiro em formato de texto. Trate-a como senha bancária, não como trecho decorativo de tutorial.

Entre em Keys.

No painel do OpenRouter, abra a área de chaves e crie uma chave exclusiva para este uso.

Dê um nome legível.

Exemplo: jaya-claude-code. O nome ajuda a descobrir quem consumiu o quê.

Defina um teto.

Configure um limite de crédito. Comece pequeno, valide a rota e aumente quando estiver segura.

Copie uma única vez.

A chave costuma começar com sk-or-v1-. Guarde em um gerenciador de senhas.

Nunca cole sua chave em um documento compartilhado

Este guia usa SUA_CHAVE_OPENROUTER de propósito. Substitua apenas no seu computador.

Claude Code CLI: a rota principal

A integração oficial usa três variáveis: uma URL de gateway, um token de autenticação e a chave Anthropic explicitamente vazia para impedir conflito.

1. Instale ou atualize o Claude Code

Windows PowerShellinstalação

irm https://claude.ai/install.ps1 | iex

macOS / Linux / WSLinstalação

curl -fsSL https://claude.ai/install.sh | bash

2. Configure apenas a sessão atual

Faça primeiro um teste descartável. Se funcionar, transforme em configuração persistente.

Bash / Zshválida nesta sessão

export OPENROUTER_API_KEY="SUA_CHAVE_OPENROUTER"
export ANTHROPIC_BASE_URL="https://openrouter.ai/api"
export ANTHROPIC_AUTH_TOKEN="$OPENROUTER_API_KEY"
export ANTHROPIC_API_KEY=""

PowerShellválida nesta janela

$env:OPENROUTER_API_KEY="SUA_CHAVE_OPENROUTER"
$env:ANTHROPIC_BASE_URL="https://openrouter.ai/api"
$env:ANTHROPIC_AUTH_TOKEN=$env:OPENROUTER_API_KEY
$env:ANTHROPIC_API_KEY=""

A URL certa termina em /api

Para o “Anthropic Skin” usado pelo Claude Code, não acrescente /v1. O endpoint OpenAI-compatible é outra estrada.

Remova autenticação antiga.

Se o Claude Code já estava conectado direto à Anthropic, abra-o e execute /logout. Feche a sessão e abra novamente.

Inicie no projeto.

Entre na pasta do projeto (cd caminho/do/seu/projeto) e rode claude. O diretório atual define o terreno de trabalho do agente.

Confirme a rota.

Rode /status e verifique a origem da credencial e a base URL.

Confirme o consumo.

Faça uma tarefa pequena e abra a área de atividade do OpenRouter. O registro deve aparecer ali.

Configuração persistente por projeto

Use .claude/settings.local.json para isolar o OpenRouter em um projeto, sem alterar todos os seus terminais.

.claude/settings.local.jsonconfiguração por projeto

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://openrouter.ai/api",
    "ANTHROPIC_AUTH_TOKEN": "SUA_CHAVE_OPENROUTER",
    "ANTHROPIC_API_KEY": ""
  }
}

Obrigatório: proteja o arquivo

Adicione .claude/settings.local.json ao .gitignore. Caso contrário, seu repositório pode publicar a chave junto com o código.

Alternância limpa: crie dois perfis, não uma salada

Uma prática madura é separar “Claude oficial” e “Claude via OpenRouter”. No PowerShell, crie funções no seu perfil:

PowerShell Profilealternância de perfis

function Use-OpenRouter {
  $env:ANTHROPIC_BASE_URL="https://openrouter.ai/api"
  $env:ANTHROPIC_AUTH_TOKEN=$env:OPENROUTER_API_KEY
  $env:ANTHROPIC_API_KEY=""
  Write-Host "Claude Code → OpenRouter"
}

function Use-Anthropic {
  Remove-Item Env:ANTHROPIC_BASE_URL -ErrorAction SilentlyContinue
  Remove-Item Env:ANTHROPIC_AUTH_TOKEN -ErrorAction SilentlyContinue
  Remove-Item Env:ANTHROPIC_API_KEY -ErrorAction SilentlyContinue
  Write-Host "Claude Code → autenticação Anthropic"
}

Segredo fora do script

A chave OPENROUTER_API_KEY deve estar armazenada fora do script, de preferência em um gerenciador de segredos ou variável de usuário protegida.

Claude Desktop: gateway no aplicativo

O Claude Desktop recente permite uma conexão de inferência de terceiros. Aqui você usa o OpenRouter no aplicativo gráfico, não o Claude Code no terminal.

Developer Mode

Abra Help → Troubleshooting → Enable Developer Mode.

Third-Party Inference

Vá em Developer → Configure Third-Party Inference.

Gateway

Selecione o tipo de conexão Gateway.

Campo	Valor	Por quê
Gateway base URL	`https://openrouter.ai/api`	Endpoint compatível com o protocolo Anthropic.
Gateway API key	`sk-or-v1-...`	Identifica e fatura sua conta OpenRouter.
Gateway auth scheme	`bearer`	Esquema exigido pela integração.
OIDC / SSO	Em branco	Não é necessário para esta configuração local.

Apply locally.

Aplique a configuração localmente. Depois encerre o aplicativo por completo, não apenas feche a janela.

Continue with Gateway.

Ao reabrir, selecione a entrada de Gateway local. Os modelos disponíveis devem aparecer no seletor.

Sinal de sucesso

Você envia uma mensagem, recebe resposta e o consumo aparece no painel do OpenRouter.

Antigravity: uma IDE, dois agentes

O Antigravity fornece seus próprios modelos no agente nativo. A documentação atual não mostra um campo para cadastrar o OpenRouter como provedor personalizado nesse seletor.

Abra a pasta do projeto no Antigravity.

Abra o terminal integrado.

Carregue as variáveis do OpenRouter

Use o bloco do seu sistema operacional (Capítulo 03).

Execute claude.

Use o Claude Code sobre os mesmos arquivos abertos na IDE.

Agente nativo

Antigravity

Use para recursos próprios da plataforma, execução paralela, exploração visual e modelos fornecidos pela IDE.

Agente externo

Claude Code

Use para trabalho profundo no repositório, refatoração, testes, comandos e consumo dos créditos OpenRouter.

Dois chefs, uma panela

Eles podem trabalhar no mesmo projeto, mas evite mandar os dois alterarem os mesmos arquivos ao mesmo tempo. Dois chefs na mesma panela produzem conflito de Git com tempero de caos.

Modelos e custos: escolha com critério

Mudar a URL não escolhe automaticamente o modelo. O Claude Code ainda precisa de identificadores compatíveis, e o comportamento mais previsível ocorre com modelos Claude.

Tarefa rápida

Modelo econômico

Localizar arquivos, explicar código, testes simples e pequenas correções.

Trabalho principal

Sonnet

Bom equilíbrio para implementação, depuração, refatoração e tarefas agentivas do cotidiano.

Alta complexidade

Opus

Reserve para arquitetura difícil, raciocínio profundo e migrações delicadas.

Outros provedores

Teste antes

Nem todo modelo reproduz perfeitamente tool use e comportamentos esperados pelo Claude Code.

Não copie identificadores antigos de modelo

Abra a página de modelos do OpenRouter e use o ID atual. Famílias podem mudar, ser descontinuadas ou receber aliases novos.

Prática	Efeito
Defina limite por chave	Evita que um erro consuma todo o saldo.
Comece com tarefa pequena	Valida autenticação, modelo e faturamento.
Separe chaves por ferramenta	Facilita auditoria e revogação.
Monitore a atividade	Mostra custo, modelo e origem das chamadas.

A chave não é configuração. É credencial.

Faça o mínimo de sempre e evite o óbvio de nunca.

Faça

Limite de uso

Defina teto financeiro e crie uma chave exclusiva para cada ferramenta.

Faça

Revogação rápida

Se houver suspeita de vazamento, revogue primeiro. Investigue depois.

Faça

Segredo local

Use gerenciador de senhas, secret store ou variável protegida.

Evite

Git e nuvem

Não publique a chave em GitHub, Drive, Notion, screenshots ou vídeos.

Evite

Arquivos genéricos

Não presuma que qualquer .env será lido automaticamente pelo Claude Code.

Evite

Máquina corporativa

Não use gateway externo em ambiente corporativo sem autorização formal de segurança.

Quando algo quebrar, leia o sintoma

Quase todo erro pertence a uma destas camadas: chave, URL, modelo ou sessão.

Sintoma	Causa provável	Correção
401 / Unauthorized	Chave inválida, revogada ou variável errada.	Gere nova chave e confirme `ANTHROPIC_AUTH_TOKEN`.
Model not found	URL com `/v1` ou ID de modelo inválido.	Use `https://openrouter.ai/api` e confira o ID atual.
Claude ignora o gateway	Login Anthropic em cache ou terminal antigo.	Execute `/logout`, feche e reabra o terminal.
/status mostra Anthropic	Variáveis não foram carregadas.	Reaplique os comandos na mesma sessão antes de executar `claude`.
Desktop sem Gateway	Developer Mode desativado ou versão antiga.	Atualize o aplicativo e ative o modo desenvolvedor.
Sem modelos no Desktop	Sem créditos, chave inválida ou auth scheme incorreto.	Confirme saldo e use `bearer`.
Antigravity sem OpenRouter	O seletor nativo não oferece esse provedor.	Use Claude Code no terminal integrado.
MCP estranho ou limitado	Gateway não Anthropic pode mudar recursos auxiliares.	Valide cada MCP e consulte as limitações atuais do Claude Code.

Dez sinais de que está certo

Antes de considerar a configuração concluída, confira este checklist.

Criei uma chave exclusiva para Claude Code.

Defini um limite financeiro para a chave.

Usei a base URL sem /v1.

Configurei ANTHROPIC_AUTH_TOKEN.

Deixei ANTHROPIC_API_KEY vazia.

Removi o login antigo com /logout.

Validei a rota com /status.

Protegi arquivos locais no .gitignore.

Vi a chamada no painel do OpenRouter.

No Antigravity, usei o terminal integrado.

As palavras sem fumaça

Termos técnicos que aparecem o guia todo, explicados uma vez.

API Key

Credencial que autoriza e fatura chamadas.

Base URL

Endereço para o qual o cliente envia as requisições.

Gateway

Camada intermediária que autentica, roteia e mede o uso.

LLM

Modelo de linguagem que interpreta e produz a resposta.

MCP

Protocolo para conectar o agente a ferramentas e fontes.

CLI

Interface de linha de comando usada no terminal.

Provider

Empresa ou infraestrutura que serve o modelo.

Router

Lógica que escolhe ou encaminha a chamada para um modelo.

Referências

Base técnica

Conteúdo revisado em 30 de julho de 2026. Menus, modelos e limitações podem mudar.

OpenRouter · Claude Code Integration OpenRouter · Claude Desktop Integration Anthropic · Claude Code Settings Anthropic · Claude Code Authentication Anthropic · Model Configuration Google Antigravity · Models

Jaya Roberta em retrato editorial de fundo escuro para o encerramento

Nota da Jaya

Um sistema não fica poderoso porque tem muitas peças.

Fica poderoso quando cada peça sabe exatamente o que está fazendo.

@jayaroberta.ai

OpenRouter + Claude Code.

O mapa antes da estrada

Quero programar no terminal

Quero conversar no aplicativo

Crie uma chave com limites

Claude Code CLI: a rota principal

1. Instale ou atualize o Claude Code

2. Configure apenas a sessão atual

Configuração persistente por projeto

Alternância limpa: crie dois perfis, não uma salada

Claude Desktop: gateway no aplicativo

Developer Mode

Third-Party Inference

Gateway

Antigravity: uma IDE, dois agentes

Antigravity

Claude Code

Modelos e custos: escolha com critério

Modelo econômico

Sonnet

Opus

Teste antes

A chave não é configuração. É credencial.

Limite de uso

Revogação rápida

Segredo local

Git e nuvem

Arquivos genéricos

Máquina corporativa

Quando algo quebrar, leia o sintoma

Dez sinais de que está certo

As palavras sem fumaça

API Key

Base URL

Gateway

LLM

MCP

CLI

Provider

Router

Base técnica

Um sistema não fica poderoso porque tem muitas peças.