Documentação

Claude Code Router

O CCR fica entre o Claude Code e o serviço que fornece os modelos, permitindo direcionar diferentes classes de solicitações a destinos diferentes. Adicione a Kunavo como endpoint personalizado e, em seguida, use o Agent Config para mapear cada nível do Claude a um ID de modelo.

O CCR agora é um aplicativo para desktop, não um config.json: adicione a Kunavo como um endpoint de API personalizado e deixe suas regras de roteamento enviar cada classe de solicitação para um modelo diferente.

CCR Desktop

Providers → Add provider
  Preset provider   Other / custom API endpoint
  Name              Kunavo
  API endpoint      https://api.kunavo.com
  API key           sk-kn-...
  Models            claude-sonnet-5, claude-opus-5, claude-haiku-4-5

Agent Config → Add profile → Claude Code
  Model         Kunavo/claude-sonnet-5
  Opus model    Kunavo/claude-opus-5
  Haiku model   Kunavo/claude-haiku-4-5

A edição manual de config.json não surte mais efeito. O CCR mantém a configuração de execução em ~/.claude-code-router/config.sqlite e lê um arquivo config.json legado uma única vez, como origem para migração, quando ainda não existe uma configuração SQLite. Depois dessa primeira execução, as alterações no arquivo JSON são ignoradas silenciosamente. A maioria dos guias na internet — e versões anteriores do nosso próprio guia — ainda descreve o arquivo JSON.

O endpoint de API aqui é a origem sem caminho, https://api.kunavo.com: o CCR verifica o protocolo usando esse endereço, e a Kunavo oferece nativamente Anthropic Messages em /v1/messages. Se preferir que o CCR use o formato compatível com OpenAI, informe https://api.kunavo.com/v1 — as duas interfaces estão disponíveis com a mesma chave.

Ainda não tem uma chave? Crie uma conta na Kunavo, gere uma chave (ela começa com sk-kn-) e adicione crédito a partir de $10 — as chamadas são pagas com esse saldo, e chamadas malsucedidas não são cobradas. O painel então abre na configuração de Claude Code Router.

Passo a passo

Crie uma chave em /app/keys e copie-a — ela é exibida uma única vez.
No CCR Desktop, abra Provedores → Adicionar provedor, escolha a predefinição Other / custom API endpoint e preencha Nome, Endpoint de API e Chave de API.
Adicione os IDs de modelo em Modelos — use Buscar modelos para importar o catálogo ou Modelos personalizados para digitar os IDs.
Execute Verificar conexão em dois ou três modelos. Isso envia solicitações reais, então selecione apenas os modelos necessários para verificar, em vez da lista inteira.
Abra Agent Config → Adicionar perfil → Claude Code, defina Modelo e as substituições por nível de Opus / Sonnet / Haiku, salve e inicie o Claude Code pelo CCR.

Verificado em página de configuração do provedor do CCR em 6 de setembro de 2026. As configurações de terceiros podem mudar; se o nome de um campo aqui já não corresponder ao que você vê, aquela página é a autoridade, não esta.

Esta é a versão resumida. O guia completo — escolha do modelo, custo de uma sessão real e modos de falha — está em guia do Claude Code Router.

Verifique antes de depurar o cliente

Uma solicitação determina se a falha está no endpoint, na chave ou no arquivo de configuração. Se isto retornar JSON, a mesma URL base e a mesma chave funcionarão em Claude Code Router.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer sk-kn-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

Qual ID de modelo inserir no campo

Todo modelo de texto pode ser acessado como um ID de modelo — a lista atual está em GET /v1/models, e o catálogo com preços está na página de modelos. As tarifas são em USD por 1 milhão de tokens, entrada / saída.

ID do modelo	Entrada / saída da Kunavo	Onde se encaixa em Claude Code Router
`claude-opus-5`	$3.50 / $17.50	nível Opus — planejamento e edições complexas
`claude-sonnet-5`	$1.40 / $7.00	nível Sonnet e modelo padrão do perfil
`claude-haiku-4-5`	$0.70 / $3.50	nível Haiku, que recebe o volume de subagentes
`gpt-5-6-terra`	$0.70 / $4.20	uma rota para contextos longos, acessível pela mesma entrada de provedor

A cobrança é por token, usando um saldo pré-pago e sem tarifa mensal — consulte billing. Em contextos repetidos — que representam a maior parte do que um editor ou cliente de chat envia — o cache de prompt altera a conta mais do que a escolha do modelo.

Por que o mapeamento por nível é essencial

O Claude Code escolhe um modelo por nível, e não por solicitação: o ciclo principal pede o nível Sonnet ou Opus, e o trabalho em segundo plano — subagentes, pesquisa, sumarização — pede o modelo menor e mais rápido. O Agent Config do CCR expõe esses níveis em campos separados, permitindo que o modelo mais caro atenda apenas às solicitações que precisam dele, enquanto o nível de maior volume usa um ID barato. Essa divisão é o motivo principal para usar um roteador diante do Claude Code e não aparece nas próprias configurações do Claude Code.

Perguntas frequentes

Onde o Claude Code Router armazena a configuração?

Em um banco de dados SQLite: ~/.claude-code-router/config.sqlite no macOS e Linux, %APPDATA%\claude-code-router\config.sqlite no Windows. Um config.json legado é lido apenas uma vez, como origem para migração, quando ainda não existe uma configuração SQLite; depois dessa migração, editar config.json não afeta a configuração em uso. Altere as configurações pela interface desktop.

Como adiciono um endpoint de API personalizado ao Claude Code Router?

Abra Provedores, clique em Adicionar provedor e selecione a predefinição "Outro / endpoint de API personalizado" — ela aceita qualquer serviço de origem compatível com OpenAI, Anthropic ou Gemini. Preencha um Nome exclusivo, a URL base do endpoint de API e a chave de API; em seguida, adicione os IDs de modelo, importando-os ou digitando-os em Modelos personalizados. Verificar conexão envia solicitações reais de teste para confirmar que o endpoint, a chave, o protocolo e os IDs funcionam em conjunto.

O Claude Code Router pode enviar níveis diferentes do Claude para modelos diferentes?

Sim, e esse é o principal motivo para usá-lo. No Agent Config, um perfil do Claude Code tem um Modelo padrão e substituições opcionais para Fable, Opus, Sonnet e Haiku. O Claude Code solicita um nível, e não um ID específico; assim, mapear o nível Haiku para um modelo barato e o nível Opus para um modelo robusto distribui os custos de acordo com o comportamento natural do agente: trabalho frequente em segundo plano no ID barato e planejamento no modelo caro.

O Claude Code Router funciona com um gateway no formato Anthropic?

Sim. A predefinição de endpoint personalizado verifica o protocolo usando a URL fornecida e oferece suporte a Anthropic Messages como um dos protocolos; assim, é possível adicionar diretamente um gateway que exponha /v1/messages, usando sua origem como endpoint de API. Um gateway que também exponha uma interface compatível com OpenAI pode ser adicionado de qualquer uma das duas formas; a diferença está apenas no formato de transmissão usado pelo CCR para se comunicar com ele.