Claude Code Router 3.1.1: instalação, rotas e solução de erros

Você quer usar DeepSeek, OpenRouter, Gemini, Kimi, Z.AI/GLM ou outro endpoint compatível no Claude Code, mas o tutorial encontrado ainda manda editar config.json e executar ccr code. Ou a interface abre, porém o gateway em 127.0.0.1:3456 não sobe. Este guia segue o fluxo atual da versão 3.1.1, da instalação até um perfil de Claude Code validado, e separa cada falha comum em uma sequência prática de diagnóstico.

Comece pela versão: a 3.1.1 não é mais centrada em um config.json manual

Configure provedores, rotas e Agent Profiles pela Web UI em vez de copiar um JSON antigo. Em 26 de setembro de 2026, a tag latest do npm aponta para a versão 3.1.1. O pacote atual guarda a configuração principal em config.sqlite e gera gateway.config.json para o gateway em execução, conforme os metadados do registro npm e o README atual do projeto.

Essa diferença também explica dois becos sem saída. A referência atual da CLI inicia um agente com ccr <profile-name-or-id> e não lista ccr code. Além disso, gateway.config.json é gerado pelo sistema, não é a fonte que você deve manter à mão. Se um tutorial exigir config.json ou ccr code, confira a geração do CCR antes de tratar o erro como problema de instalação.

Prepare Node.js, um provedor upstream e o Claude Code

Você precisa de Node.js 22 ou mais recente, acesso a um serviço de modelos e o Claude Code instalado localmente. O CCR roteia requisições; ele não instala o Claude Code e o acesso por API não é o mesmo produto que uma assinatura Claude.ai ou Claude Max.

Verifique primeiro o Node.js:

node --version

Atualize o Node.js se a versão principal for menor que 22. O upstream pode ser um preset integrado, como OpenRouter, DeepSeek, Gemini, Moonshot/Kimi ou Z.AI, ou um endpoint personalizado que implemente um protocolo OpenAI-compatible ou Anthropic-compatible aceito.

Instale a CLI do npm e valide o comando antes de configurar

Execute a ajuda logo após a instalação global. Isso separa um problema de npm ou PATH de um problema de Provider ou Routing.

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

Para atualizar ou remover:

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

Remover o pacote npm não apaga a configuração nem os bancos locais. O diretório de dados é ~/.claude-code-router no macOS/Linux e %APPDATA%\claude-code-router no Windows.

Configure nesta ordem: Provider → Check Connection → Client Key → Routing → Server → Profile → teste ponta a ponta

Faça uma rota padrão funcionar antes de adicionar condições ou modelos fallback. Ao configurar vários provedores, rewrites, retries e fallbacks de uma vez, fica difícil distinguir um 401, um Model ID inválido ou um protocolo incompatível.

Abra a interface de gerenciamento:

ccr ui

A UI usa por padrão http://127.0.0.1:3458, enquanto o gateway de modelos usa http://127.0.0.1:3456. Use a URL autenticada impressa ou aberta pelo CCR. Se a porta 3458 estiver ocupada, o CCR pode escolher outra porta de gerenciamento e mostrar o endereço real.

1. Adicione o upstream em Providers

Prefira um preset quando ele existir; use custom endpoint apenas quando necessário. Em Providers → Add Provider, selecione o serviço, informe a API Key desse próprio provedor, escolha o protocolo correto e adicione Model ID realmente disponíveis para sua conta.

Não deduza o protocolo pelo nome comercial do modelo. Anthropic Messages, OpenAI Chat/Responses e Gemini usam formatos diferentes. Base URL, protocolo e Model ID precisam seguir a documentação atual do upstream.

Depois de salvar o Provider, execute Check Connection. Essa é apenas uma verificação do upstream; ela não comprova o caminho completo Claude Code → CCR gateway → Routing → Provider.

2. Crie uma CCR client key em API Keys

Uma CCR client key não é o management token. O management token protege a Web UI e a RPC API; a client key autentica as requisições que o Claude Code envia ao gateway. Trate qualquer URL com ccr_web_token como senha e não a cole em logs, tickets ou conversas.

3. Defina primeiro uma rota padrão

Aponte a rota padrão para um único Provider que passou no Check Connection e para um modelo desse Provider. Salve a rota, mas ainda não envie a requisição pelo Claude Code; primeiro inicie o gateway e crie o Agent Profile.

Depois que a requisição ponta a ponta da etapa 6 funcionar, adicione condições, retries, rewrites ou fallbacks ordenados em Routing. Acrescente um comportamento por vez e teste novamente. O modelo fallback também precisa aceitar as ferramentas, o contexto e o protocolo exigidos pela tarefa; dois modelos não são intercambiáveis apenas porque ambos conversam.

4. Inicie e valide o gateway em Server

A UI aberta não prova que o gateway da porta 3456 está utilizável. Em Server, inicie o gateway e anote a URL voltada ao cliente exibida. O padrão é http://127.0.0.1:3456; use a URL real mostrada pelo CCR. Se o início falhar, rode o CCR em primeiro plano para expor o erro:

ccr serve

A saída no terminal ajuda a diferenciar conflito de porta, Provider incompleto, modelo ausente e problema de permissão em arquivo local.

5. Crie e habilite um Agent Profile do Claude Code

A CLI atual inicia o Claude Code por meio de um Agent Profile habilitado. Em Agent Profiles, crie um perfil do Claude Code, selecione o modelo usado pela rota padrão do Provider que passou no Check Connection, salve e habilite. No modo CCR, o Claude Code se conecta ao CCR gateway exibido em Server (padrão http://127.0.0.1:3456), e não à URL do Provider upstream. O nome é livre, por exemplo Claude - Review.

Inicie por nome ou ID:

ccr "Claude - Review"

Coloque argumentos específicos do Claude Code depois de -- para que o CCR não os interprete como opções próprias:

ccr "Claude - Review" cli -- --model sonnet

Substitua Claude - Review pelo nome ou ID real do seu perfil.

6. Envie uma requisição pelo Claude Code e confira Logs

Agora ocorre o primeiro teste ponta a ponta real. No Profile iniciado, envie uma requisição simples pelo Claude Code e confirme em Logs que o Provider e o modelo esperados foram escolhidos e que o status foi bem-sucedido.

O Check Connection do Provider cobre apenas a conexão upstream. A requisição real também valida a CCR client key, o gateway, Routing, o Agent Profile e a chamada ao modelo.

Entenda ccr start, ui, serve e stop

Use ccr ui ou ccr start no dia a dia e ccr serve para diagnóstico.

Comando	Melhor uso	Comportamento
ccr start	Serviço persistente em segundo plano	Inicia o serviço de gerenciamento e o gateway em modo detached e imprime uma URL autenticada
ccr ui	Configuração interativa local	Reaproveita ou inicia o serviço em segundo plano e abre a UI
ccr serve	Diagnóstico ou process supervisor	Fica em primeiro plano e mostra erros de início e requisições; ccr web é um alias
ccr stop	Recriar opções do serviço	Para o serviço detached iniciado por start ou ui

start, ui e serve aceitam --host, --port, --open/--no-open e --gateway/--no-gateway. A opção --port indica a porta preferida de gerenciamento, não automaticamente a porta 3456 do gateway de modelos.

Corrija “ccr: command not found” verificando Node e o bin global do npm

Confira runtime e prefixo global antes de reinstalar repetidamente. Execute:

node --version
npm prefix -g

Confirme Node.js 22 ou superior e verifique se o diretório global de executáveis do npm está no PATH do shell atual. Abra um novo terminal após a instalação, pois alguns shells armazenam caminhos de comandos em cache.

Se você também instalou o app desktop, ele fornece o comando relacionado ccr-app. O pacote npm instala ccr; a existência de ccr-app não prova que a CLI npm esteja no PATH.

Corrija um gateway que não escuta em 127.0.0.1:3456

Primeiro descubra se o gateway falhou ao iniciar ou se outro processo já ocupa a porta. Uma UI saudável em 3458 não diz nada sobre 3456.

No macOS/Linux:

lsof -nP -iTCP:3456 -sTCP:LISTEN

No Windows:

netstat -ano | findstr :3456

Se um CCR antigo ou outro programa estiver com a porta, identifique o PID antes de interromper o processo. Depois execute ccr serve, volte a Server e confirme a presença de Provider, modelo e client key antes de iniciar o gateway novamente.

Corrija 401, model not found e erros de protocolo com três verificações

Revise credenciais, protocolo e Model ID nessa ordem. Erros frequentes incluem usar o management token como client key, colocar uma CCR client key no Provider upstream ou chamar um endpoint Anthropic-compatible com uma rota OpenAI-compatible.

Siga a sequência:

1. O Claude Code se autentica no CCR com uma CCR client key, não com ccr_web_token.
2. A entrada de Provider armazena a API Key do próprio upstream.
3. O protocolo selecionado corresponde ao endpoint.
4. O Model ID roteado existe para esse provedor e essa conta.
5. Logs resolve o Provider e o modelo esperados.

Não dependa apenas da mensagem final do Claude Code. CCR Logs mostra se a falha ocorreu na autenticação do cliente, resolução da rota, autenticação upstream ou requisição ao modelo.

Corrija perfis ausentes e serviços em segundo plano com opções antigas

Apenas Agent Profiles habilitados podem ser iniciados. A comparação de nomes ignora maiúsculas e aceita nomes normalizados, mas um nome ambíguo exige o ID. Salve novamente o perfil se o launcher gerado estiver ausente.

Um processo em segundo plano reaproveitado não assume novas opções de host, port ou gateway. Pare e recrie:

ccr stop
ccr start --host 127.0.0.1 --port 3458

Isso explica por que um comando pode terminar sem erro e o serviço continuar usando os ajustes anteriores.

Use ANTHROPIC_BASE_URL diretamente quando houver apenas um endpoint

A configuração direta costuma ser mais simples com um único endpoint Anthropic-compatible, um modelo principal e sem necessidade de rota condicional, fallback, logs compartilhados ou vários perfis. Siga a documentação de Claude Code do provedor para definir ANTHROPIC_BASE_URL, a variável de autenticação e o mapeamento de modelo, sem adicionar um gateway local.

O CCR passa a ser mais adequado quando:

• você alterna entre DeepSeek, OpenRouter, Gemini, Kimi, Z.AI ou endpoints personalizados;
• tarefas ou perfis diferentes devem usar modelos diferentes;
• precisa de retries, condições, rewrites ou fallback ordenado;
• quer inspecionar rota resolvida, status, tokens, latência e erros em um só lugar;
• vários clientes devem compartilhar um gateway local.

Situação	Prefira
Um endpoint Anthropic-compatible estável	ANTHROPIC_BASE_URL direto
Vários provedores, modelos ou perfis	CCR
Você precisa enxergar a rota de cada requisição	CCR
Quer apenas o caminho mais rápido para um serviço	Comece direto e migre para CCR quando o fluxo crescer

Exemplo de endpoint compatível: adicionar BetterToken ao CCR

BetterToken é uma opção de Provider Anthropic-compatible personalizado, não a única resposta. Em Providers do CCR, informe https://bettertoken.ai no campo upstream API endpoint/Base URL —não na Base URL do Claude Code— e não acrescente /v1. Selecione explicitamente Anthropic Messages, informe sua própria BetterToken API Key e um Model ID disponível, salve o Provider e execute Check Connection.

Ao usar CCR, o Claude Code se conecta ao CCR gateway mostrado em Server, normalmente http://127.0.0.1:3456. Inicie o Agent Profile, envie uma requisição e confirme em Logs que ela foi roteada ao modelo BetterToken esperado. Não aponte o Claude Code diretamente para https://bettertoken.ai nesse modo, pois isso contornaria o CCR.

Somente se você decidir ignorar o CCR e se conectar diretamente a esse único endpoint deve seguir a documentação do BetterToken para Claude Code e definir a Base URL no macOS/Linux:

export ANTHROPIC_BASE_URL="https://bettertoken.ai"

No PowerShell:

$env:ANTHROPIC_BASE_URL="https://bettertoken.ai"

Nesse modo direto, a variável de autenticação e o mapeamento do modelo continuam vindo da documentação atual. Não use no Claude Code a Base URL OpenAI-compatible https://www.bettertoken.ai/v1.

Proteja credenciais locais e faça backup com segurança

Mantenha o listener de gerenciamento em 127.0.0.1 a menos que o acesso remoto seja intencional. Para acesso remoto, use firewall ou rede privada e TLS em um reverse proxy confiável. Não exponha o gateway externamente sem CCR client keys.

Credenciais upstream, logs e bancos de runtime ficam no diretório local do CCR. Não edite nem copie config.sqlite enquanto o CCR estiver escrevendo. Use a exportação da UI ou pare o CCR antes de fazer uma cópia pelo sistema de arquivos.

Valide o caminho inteiro, não apenas a interface

Sucesso significa que uma requisição do Claude Code percorreu a rota esperada e recebeu resposta normal. Confira:

• node --version mostra 22 ou superior;
• ccr --help funciona;
• Providers contém ao menos um upstream que passou no Check Connection;
• API Keys contém uma CCR client key;
• Server mostra o gateway em execução e a URL voltada ao cliente (padrão http://127.0.0.1:3456);
• o Agent Profile está salvo e habilitado;
• ccr <profile-name-or-id> inicia o Claude Code;
• uma requisição real foi enviada pelo Claude Code e Logs mostra Provider, modelo e status esperados;
• cada rota ou fallback novo foi testado de novo.

Seguir essa ordem mantém instalação, autenticação, Routing e início do agente como camadas separadas. Quando algo falha, você corrige a camada responsável em vez de reinstalar o CCR ou editar aleatoriamente um config.json obsoleto.