Claude Code Router — encaminhe o Claude Code para qualquer modelo ou ignore o roteador completamente

A maioria das pessoas que pesquisa por Claude Code Router quer uma de duas coisas diferentes: rotear o Claude Code entre vários provedores de modelos ou simplesmente executar o Claude Code em algum lugar mais barato do que o preço de tabela da Anthropic. Apenas a primeira precisa do router. O Claude Code lê ANTHROPIC_BASE_URL nativamente, portanto a segunda exige três variáveis de ambiente e nenhum software adicional.

Este guia aborda os dois caminhos, com os nomes exatos das variáveis, a armadilha da credencial que produz um 401 silencioso e uma lista honesta do que deixa de funcionar atrás de qualquer gateway. Se você leu recentemente outro guia sobre CCR, pule primeiro para a Opção B: o config.json que esses artigos instruem você a editar já não é a configuração que o router lê.

Qual deles você realmente precisa?

O roteador é um serviço local: mais um processo para executar, configurar e manter atualizado — e, desde 2026, um aplicativo para desktop com sua própria interface, em vez de um arquivo que você edita. Esse custo se justifica quando você realmente precisa de roteamento entre vários provedores, contabilização por solicitação ou seleção de modelos no nível do subagente. Ele não se justifica quando uma URL base teria resolvido o problema.

Opção A — trocar a URL base (sem instalação)

A Kunavo disponibiliza a Anthropic Messages API nativa em /v1/messages, que é o endpoint chamado pelo Claude Code. Aponte para ela:

export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...              # create at kunavo.com/app/keys
export ANTHROPIC_MODEL=claude-sonnet-5             # exact slug — see the table below
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5     # the opus alias and plan mode (v2.1.280+)
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5   # the sonnet alias; Sonnet 5.5 is not on Kunavo
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5   # background tasks

ANTHROPIC_BASE_URL é apenas a origem — o Claude Code acrescenta /v1/messages, portanto não inclua um caminho. Mantenha as linhas de modelo: o padrão integrado do Claude Code e seu alias opus apontam para o Opus mais recente e, se a Kunavo ainda não oferecer esse modelo, a primeira solicitação retorna 404. O alias sonnet solicita o Sonnet 5.5, que a Kunavo não oferece; portanto, sem a linha ANTHROPIC_DEFAULT_SONNET_MODEL, /model sonnet, a fase de execução de opusplan e qualquer subagente definido como model: sonnet retornam 404. O alias opus está fixado no Opus 5.5 (claude-opus-5-5), que exige o Claude Code v2.1.280 ou posterior — execute claude update se o seu for mais antigo. Obtenha a chave no dashboard após se inscrever e adicionar $10 de crédito; ela é exibida uma única vez.

Qual variável de credencial — e por que isso importa

O Claude Code envia as duas variáveis de credencial em cabeçalhos HTTP diferentes, e uma chave no cabeçalho que o servidor não lê falha com 401:

Prefira ANTHROPIC_AUTH_TOKEN por um motivo específico: ANTHROPIC_API_KEY exige uma aprovação única em uma sessão interativa, e uma chave recusada uma vez é ignorada depois, sem nova solicitação — uma falha confusa em que a variável está claramente definida e claramente não utilizada. A descoberta de modelos não decide isso na Kunavo. A descoberta de modelos do gateway do Claude Code envia somente o token bearer quando ANTHROPIC_AUTH_TOKEN está definido e usa x-api-key como alternativa; o endpoint /v1/models da Kunavo lê a chave de qualquer um dos cabeçalhos.

Faça a configuração persistir

As exportações do shell só se aplicam àquele terminal e a tudo que for iniciado a partir dele — um editor aberto pelo dock não as verá, e os agentes em segundo plano também não. Coloque os valores em um arquivo de configurações para abranger tudo:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.kunavo.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-kn-...",
    "ANTHROPIC_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
  }
}

Use ~/.claude/settings.json para todos os projetos. Nunca coloque uma chave no .claude/settings.json de um projeto — esse arquivo é versionado.

Verifique antes de confiar

Teste primeiro o endpoint diretamente, para que uma falha aponte para a configuração, e não para o Claude Code:

curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":1,"messages":[{"role":"user","content":"."}]}'

# A response starting with {"id":"msg_ means the URL and key both work.
# 401 -> the key is in the wrong header; see "Which credential variable" below.

Em seguida, inicie claude pelo mesmo shell e execute /status. Uma linha Anthropic base URL mostrando api.kunavo.com e uma linha Auth token identificando sua variável confirmam que as duas partes estão ativas.

Defina um modelo personalizado — escolha o slug explicitamente

A Kunavo resolve os slugs de modelo por correspondência exata e não cria aliases para nomes com sufixo de data; por isso, claude-sonnet-4-5-20250929 retorna 404, enquanto claude-sonnet-5 funciona. Sempre defina ANTHROPIC_MODEL em vez de depender do padrão integrado:

As variáveis dos aliases permitem rotear cada tarefa sem nenhum roteador: ANTHROPIC_DEFAULT_OPUS_MODEL controla o alias opus e o modo de planejamento; ANTHROPIC_DEFAULT_SONNET_MODEL controla sonnet e a fase de execução de opusplan; e ANTHROPIC_DEFAULT_HAIKU_MODEL controla haiku e o trabalho em segundo plano do Claude Code, como resumos e títulos. Ao usar a Kunavo, as duas últimas configurações são obrigatórias, pois, sem fixar os modelos, elas solicitam IDs que a Kunavo não oferece (Sonnet 5.5 e Haiku 5.5 a partir da v2.1.293). Defina a variável do Haiku como claude-haiku-4-5; isso também direciona o trabalho em segundo plano para fora do modelo principal. (ANTHROPIC_SMALL_FAST_MODEL é a forma obsoleta de escrever essa mesma configuração.)

Opcional: mostre todos os modelos no seletor

Defina CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 (Claude Code v2.1.129+) e o Claude Code consultará GET /v1/models na inicialização, adicionando o que encontrar ao seletor /model rotulado como Do gateway. A Kunavo disponibiliza esse endpoint, então todos os modelos Claude habilitados aparecem, e /model torna-se um menu atualizado, em vez de uma lista mantida manualmente. Qualquer uma das variáveis de credencial funciona para isso — veja acima.

Opção B — claude-code-router, como ele realmente funciona agora

Comece por aqui, porque quase tudo que foi escrito sobre o CCR descreve uma versão que não existe mais. O roteador costumava ser um arquivo JSON e um comando ccr code. Agora ele é um plano de controle local com aplicativo para desktop, interface de gerenciamento, registros de solicitações e um gateway de modelos — e o config.json que todos os tutoriais mostram não o configura mais.

O CCR mantém sua configuração de execução em ~/.claude-code-router/config.sqlite (%APPDATA%\claude-code-router\config.sqlite no Windows). Um config.json legado é lido uma vez, como fonte de migração, quando ainda não existe uma configuração SQLite. Depois dessa primeira execução, editá-lo não afeta a configuração em execução — sem erro nem aviso. Seu bloco Providers cuidadosamente colado simplesmente não é a configuração.

Isso inclui esta página antes de 2026-09-06: o trecho JSON que costumava aparecer aqui estava errado, e era o tipo de erro que custa uma tarde inteira, porque nada informa que ele foi ignorado. Agora a configuração acontece na interface (ou, para backup, em Configurações → Exportar dados — não copie arquivos SQLite ativos enquanto o CCR estiver em execução).

Instalar e iniciar

O CCR é distribuído de duas formas: um aplicativo para desktop pelo GitHub Releases (bandeja do sistema, atualização automática, integrações de desktop) e uma CLI npm para implantações headless ou supervisionadas. Ambos compartilham o mesmo diretório de configuração.

# CCR ships as a desktop app (GitHub Releases) or an npm CLI. Both read the
# same ~/.claude-code-router directory. The CLI needs Node.js 22+.
npm install -g @musistudio/claude-code-router
ccr ui        # management UI on :3458, model gateway on :3456

# Configure the provider and an Agent Config profile in that UI, then launch
# Claude Code through the profile by name:
ccr "Claude Code - Kunavo"        # npm CLI
ccr-app "Claude Code - Kunavo"    # the desktop app's own launcher

# There is no 'ccr code' in the current command reference. The service commands
# are start / ui / stop / serve / web; everything else is a profile name.

Adicionar a Kunavo exige uma entrada de provedor — Provedores → Adicionar provedor, predefinição Other / custom API endpoint, endpoint https://api.kunavo.com, sua chave sk-kn- — e um perfil Configuração do agente → Adicionar perfil → Claude Code. A versão campo a campo, incluindo Verificar conexão e a descoberta de modelos, está na página de integração do Claude Code Router. O restante desta seção aborda o que aquela página não cobre: as credenciais, a economia e os modos de falha.

Três credenciais, e a qual delas um 401 se refere

Esta é a forma mais comum de uma configuração funcional parecer estar quebrada. O CCR tem três segredos separados, que autenticam três saltos diferentes:

A combinação de portas também confunde as pessoas: o gerenciamento usa 127.0.0.1:3458 por padrão e o gateway de modelos usa 127.0.0.1:3456. Uma URL base apontada para 3458 chega à interface, não ao gateway. (O Docker deliberadamente coloca ambos atrás de um único endpoint Nginx, por isso as instruções do Docker são diferentes.) Uma interface acessível não significa que o gateway esteja funcionando: verifique /health no endereço do gateway e confirme que Servidor mostra Em execução.

O mapa por nível é o ponto principal

O Claude Code não solicita um modelo; ele solicita um nível — o loop principal quer Sonnet ou Opus, e o trabalho em segundo plano (subagentes, pesquisa, resumos, títulos de conversas) quer o modelo pequeno e rápido. Um perfil do Claude Code em Configuração do agente expõe esses itens como campos separados: um Modelo padrão, além de substituições opcionais para Fable, Opus, Sonnet e Haiku, cada uma aceitando um valor Provider/model. Deixe um nível vazio e o Claude Code o escolherá.

Leia essa tabela antes de copiar o mapa de tiers de outra pessoa, porque a divisão óbvia é a primeira alavanca: claude-sonnet-5 custa 50% menos que claude-opus-5-5 na Kunavo ($1,40 / $7,00 contra $2,80 / ). A segunda alavanca é o tier Haiku: a $0,70 / $3,50, ele é 2× mais barato que o Sonnet 5 e processa um volume que você nunca vê — cada subagente, cada triagem de arquivos e cada título gerado. claude-sonnet-4-6 não é mais o Sonnet barato: a $2,10 / $10,50, ele custa 50% mais que o Sonnet 5, por isso os snippets acima definem ANTHROPIC_MODEL=claude-sonnet-5.

Roteamento de subagentes — o que o mapa de níveis não consegue fazer

As substituições de nível fixam todos os subagentes em um único modelo. O CCR pode ser mais específico: quando uma solicitação do Claude Code corresponde à rota integrada, ele insere a lista de modelos disponíveis na descrição das ferramentas Agent / Task, e o Claude Code prefixa o prompt de cada agente criado com uma tag que identifica o modelo desejado:

<CCR-SUBAGENT-MODEL>provider/model</CCR-SUBAGENT-MODEL>

O CCR remove a tag e roteia essa solicitação de acordo com ela, permitindo que um subagente de pesquisa seja executado no Haiku enquanto um subagente de revisão roda no Opus, escolhido por tarefa em vez de fixado. A ativação é fácil de não perceber: o mecanismo fica desativado até que pelo menos um modelo tenha uma Descrição na página Modelos. Sem descrições, o CCR não insere nada e todos os subagentes retornam silenciosamente ao modelo padrão do perfil. Escreva as descrições de acordo com a adequação à tarefa — “pesquisa de código, triagem de arquivos, subagentes paralelos baratos” no Haiku; “análise de arquitetura, revisão de alto risco” no Opus. Quando funciona, os registros de solicitações mostram builtin:claude-code-subagent como motivo da rota.

Escolha do protocolo e o custo disso no cache

O CCR testa o endpoint e escolhe um protocolo de comunicação. Forneça a origem simples https://api.kunavo.com e ele usará Anthropic Messages; forneça https://api.kunavo.com/v1 e ele usará o formato compatível com OpenAI. As duas interfaces estão ativas com a mesma chave, e você pode substituir a detecção automática nas configurações avançadas.

Prefira o formato Anthropic Messages. Ele mantém cache_control na comunicação, permitindo que o cache de prompts chegue ao modelo e que a entrada em cache seja cobrada a 10% da taxa de entrada (como funciona) — em um loop de agente que reenvia um prefixo estável a cada etapa, é a maior economia individual disponível. A ressalva honesta é que um roteador no caminho ainda edita as solicitações: o CCR remove a mensagem de sistema do cabeçalho de cobrança que o Claude Code injeta e adiciona a lista de modelos às descrições das ferramentas quando o roteamento de subagentes está ativado. Ambos ficam antes dos seus pontos de interrupção do cache, portanto cada alteração nesse conteúdo custa uma falha de cache enquanto o novo prefixo é aquecido. Depois disso, ele fica estável — mas esse é um motivo real para a Opção A ter um cache marginalmente melhor que a Opção B, além de exigir menos execução.

Mesmo assim, o cache de prompts também chega ao modelo no formato compatível com OpenAI. Em um prompt longo, a Kunavo define ela mesma os pontos de interrupção do cache nessa rota: no prompt do sistema, nas definições de ferramentas e na última mensagem assim que a conversa contém um turno do assistente. Um cache_control que chegue em uma mensagem ou em uma definição de ferramenta é mantido.

Alternativa: tentar novamente ou fazer failover

Vale a pena definir padrão em caso de falha na página Roteamento antes de precisar disso. Tentar novamente reenvia para o mesmo modelo em 408, 409, 429 e 5xx, respeitando Retry-After e, caso contrário, aumentando exponencialmente o intervalo de 1s até o limite de 30s. Destinos de fallback percorre uma lista ordenada de modelos de backup e é acionado para qualquer 4xx ou 5xx, partindo da ideia de que um modelo não encontrado ou uma rejeição do provedor pode afetar apenas o destino atual. Regras individuais podem substituir a configuração global. Quando um fallback é executado, a resposta inclui x-ccr-fallback-attempts e x-ccr-fallback-model, para que você possa identificar isso posteriormente.

Verifique se ele está realmente no caminho

Inicie o Claude Code pelo perfil, envie uma mensagem e abra Registros de solicitações no CCR. A linha mostra request model (o que o Claude Code solicitou), resolved provider e resolved model (para onde foi) — esse trio é a prova. Dentro da CLI, /model lista os modelos expostos pelo CCR. Se o Claude Code responder, mas nenhuma linha aparecer nos registros, você iniciou o Claude Code por conta própria, e o escopo do perfil é Somente aberto pelo CCR.

Quanto custa uma sessão de programação

O Claude Code reenvia o prompt do sistema, a conversa e o contexto de arquivos atualizado a cada etapa, portanto a taxa por token se acumula rapidamente. Nas tarifas da Kunavo para claude-sonnet-5:

Isso representa aproximadamente 30% de desconto no modelo principal, antes do cache de prompts. As tarifas completas estão no guia de preços da Claude API, e a calculadora de custos usa suas próprias contagens de tokens.

O que ainda funciona — e o que não funciona

Apontar o Claude Code para qualquer gateway altera algumas coisas. A lista é curta e vale a pena conhecê-la antes de confirmar:

Na última linha: a contagem de tokens é o único endpoint que a especificação do gateway da própria Anthropic marca como opcional, e o Claude Code estima localmente o uso do contexto quando ele está ausente. A Kunavo não disponibiliza /v1/messages/count_tokens atualmente, portanto o valor de /context é uma estimativa, não uma contagem exata. Nada se degrada além desse número — a compactação automática e a própria sessão não são afetadas.

Solução de problemas

O caminho da URL base

…e quando o roteador está no caminho

As correções específicas para cada erro da própria API estão nas páginas de solução de problemas chave de API inválida e limite de taxa.

Perguntas frequentes