Claude Code Router: execute o Claude Code com outros modelos (e quando um gateway é mais simples)

O que o Claude Code Router faz

O Claude Code Router da musistudio, frequentemente abreviado como CCR, descreve-se como um “gateway local de modelos e plano de controle para agentes de programação”. Ele fornece um endpoint local estável para o Claude Code e outros clientes, com credenciais de provedores, regras de roteamento, novas tentativas, alternativas de contingência ordenadas e logs de requisições.

O v3.1.1 README lista suporte aos formatos OpenAI Chat e Responses, Anthropic Messages e Gemini Generate Content e Interactions. A adaptação de protocolos é o que permite executar o Claude Code com outros modelos por meio do CCR.

O CCR é licenciado sob a licença MIT, com copyright da musistudio de 2025, e fornecido “NO ESTADO EM QUE SE ENCONTRA”. A permissão para usar o software não torna gratuita a inferência nos provedores de origem. As cobranças e franquias dos provedores permanecem separadas; os preços históricos dos provedores e as franquias em dólares do OpenCode Go não foram verificados para esta data de publicação.

A versão relevante do Claude Code Router 3.1

A versão 3.1.1 foi lançada em 16 de setembro de 2026. Ela adiciona suporte nativo à importação local do OpenCode Go, expõe tentativas individuais malsucedidas do gateway e corrige os preços de uso dos modelos roteados.

A versão também aceita --daemon em start e serve, corrige o worker do corpo dos logs na interface do Docker e fornece versões para macOS Apple Silicon e Intel, um instalador para Windows e um AppImage para Linux. A configuração abaixo usa a distribuição npm e a documentação fixada na v3.1.1.

Instale o CCR e conecte o Claude Code

A distribuição npm exige Node.js 22 ou mais recente. O guia da CLI com versão fixada documenta estes comandos:

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

Para iniciar sem abrir um navegador:

ccr ui --no-open

A interface de gerenciamento e o gateway de modelos têm endereços padrão separados:

Manter essas funções claras ajuda a verificar onde uma conexão falhou. Uma página de gerenciamento funcionando não comprova, por si só, que o gateway de modelos aceitou sua configuração.

Adicione um provedor e uma chave de cliente

Abra Provedores → Adicionar provedor, escolha uma predefinição ou Outro / endpoint de API personalizado, e insira o endpoint e a chave de API. O CCR detecta protocolos e modelos; Configurações avançadas permite selecionar um protocolo manualmente.

Use Verificar conexão para testar o provedor. Isso envia uma requisição real, portanto pode consumir tokens ou parte da franquia de requisições do provedor.

Crie uma chave de cliente do CCR em Chaves de API para requisições de modelos. Essa chave é separada do token da interface de gerenciamento/RPC: trate o acesso de clientes e o acesso de gerenciamento como itens de configuração distintos.

Crie um perfil do Claude Code

Em Configuração de agentes, crie um perfil habilitado para Claude Code, selecione um modelo como Provider/model, e salve-o. Para um perfil chamado “Claude Code - Trabalho”, inicie com:

ccr "Claude Code - Work"

Os comandos de inicialização gerados pelo aplicativo de desktop usam ccr-app. O guia de perfis do Claude Code distingue dois escopos:

• Somente ao abrir pelo CCR aplica a configuração às inicializações pelo CCR.
• Padrão do sistema também afeta as inicializações diretas do Claude Code.

Os perfis permitem substituir as configurações de Fable, Opus, Sonnet e Haiku. Verifique a seleção ativa com /model, depois inspecione os Logs de requisições do CCR para ver as requisições que passam pelo gateway. Mantenha guia de modelos do Claude Code por perto ao planejar essas seleções.

Configure o roteamento, as novas tentativas e as alternativas de contingência

As regras de roteamento do CCR podem inspecionar request.header e request.body, e podem reescrever request.body.model. Isso permite controlar a seleção de modelos com base na requisição recebida, além do modelo escolhido em um perfil de agente.

A configuração de alternativas de contingência usa mode, models e retryCount. Os três modos são off, retry e model-chain.

A distinção entre elegibilidade para nova tentativa e elegibilidade para contingência é importante. Uma resposta que não se qualifica para uma nova tentativa ainda pode se qualificar para um destino de contingência.

Verifique qual modelo realmente atendeu à requisição

Uma cadeia de modelos pode alterar o modelo que atende à requisição no final. Os logs do CCR mostram o provedor e o modelo finais, portanto use esses logs ao verificar comportamentos ou usos inesperados.

Comece com um perfil cujo provedor e modelo você consiga identificar. Adicione regras de roteamento e destinos de contingência de forma deliberada e verifique o destino final depois de acioná-los. Isso facilita associar uma mudança na resposta ou no padrão de custos à configuração de roteamento.

A versão 3.1.1 também expõe tentativas individuais malsucedidas do gateway. Esses registros ajudam a distinguir uma resposta final bem-sucedida das tentativas que a precederam.

Use a importação do OpenCode Go na v3.1.1

A versão v3.1.1 do Claude Code Router da musistudio adiciona suporte nativo à importação local do OpenCode Go. A integração separa o Zen, identificado como opencode, do Go, identificado como opencode-go, incluindo suas credenciais e os IDs de modelos que se sobrepõem.

O importador lê a configuração do OpenCode, auth.json, e os metadados de modelos em cache. OPENCODE_API_KEY aplica-se a ambos os serviços; OPENCODE_GO_API_KEY fornece uma substituição específica para o Go. A descoberta filtra os modelos por protocolo e concilia os metadados em cache com os resultados em tempo real de /models .

Por que o cabeçalho de sessão é importante

O O PR de integração do OpenCode Go registra que as solicitações para https://opencode.ai/zen/go/v1 exigem x-opencode-session. Sem ele, o endpoint retorna 400 MissingSessionID.

O CCR seleciona o valor da sessão nesta ordem: configuração explícita, um cabeçalho explícito do cliente, cabeçalhos de sessão do Claude, metadata.user_ide, por fim, um valor estável de fallback do processo. A injeção do cabeçalho é restrita ao endpoint oficial do Go.

Isso explica por que inserir apenas um endpoint e uma credencial pode ser insuficiente para o Go. A exigência de sessão faz parte da integração com o provedor.

Atualizar a descoberta e consultar os limites de uso

Se a importação do Go estiver indisponível, conecte o OpenCode Go no OpenCode, atualize o cache local de modelos e execute uma nova varredura no CCR.

O CCR obtém os dados de uso de GET https://opencode.ai/zen/go/v1/usage e exibe os percentuais restantes para períodos de cinco horas, semanais e mensais. A documentação fixada não especifica franquias em dólares. Interprete esses valores como percentuais restantes para os períodos indicados; eles não representam um saldo monetário.

Diagnosticar a conexão por etapas

O material de solução de problemas do CCR aborda roteamento ignorado, falhas de autenticação, modelos ausentes, seleção inesperada de modelos, picos de custo, tempos limite e rastros de agentes ausentes. Uma sequência útil de diagnóstico acompanha a solicitação desde a configuração de inicialização até o provedor final.

O Claude Code ignora o CCR

Verifique se o perfil desejado de Agent Config está ativado e se você iniciou por meio dele. Um perfil definido como Somente ao abrir pelo CCR limita sua configuração às inicializações pelo CCR; as inicializações diretas são afetadas quando Padrão do sistema está selecionado.

Use /model e os logs de solicitações do CCR em conjunto para verificar a configuração. O referência da CLI do Claude Code oferece uma referência mais abrangente para trabalhar com o cliente.

Erros de autenticação ou modelos ausentes

Para erros 401/403, revise as credenciais em cada camada relevante: a chave de API do provedor, a chave de cliente do CCR para solicitações de modelos e o token de gerenciamento separado. Essas credenciais têm funções diferentes.

Para model not found, revise os modelos detectados, o protocolo selecionado e a seleção de provedor/modelo do perfil. Com o OpenCode Go, atualize o cache local e execute uma nova varredura se a importação estiver indisponível.

Falhas de inicialização e de tempo limite

A versão 3.1.1 aumenta o tempo de aceitação da configuração do gateway de cinco segundos para 30 segundos. Isso resolve casos em que a interface de gerenciamento inicia, mas o gateway falha sob carga no host, especialmente no Windows.

CCR_GATEWAY_CONFIG_TIMEOUT_MS substitui o tempo limite. Valores inválidos ou inferiores a 1,000 milissegundos fazem com que o valor padrão seja usado.

A configuração fica em ~/.claude-code-router no macOS/Linux e em %APPDATA%\claude-code-router no Windows. Os arquivos relevantes incluem config.sqlite, o arquivo gerado gateway.config.json e service.json. Os comandos do serviço incluem ccr start, ccr stope, em primeiro plano, ccr serve.

Quando um gateway hospedado é mais simples

O CCR atende a fluxos de trabalho que precisam de gerenciamento local de provedores, roteamento baseado em solicitações, pools de credenciais ou cadeias explícitas de fallback. Um gateway hospedado pode exigir menos etapas de configuração local quando seu objetivo imediato é conectar o Claude Code a um serviço upstream.

O anúncio do OpenRouter de 4 de agosto de 2026 documenta estas configurações de conexão:

ANTHROPIC_BASE_URL=https://openrouter.ai/api
ANTHROPIC_AUTH_TOKEN=<openrouter-api-key>
ANTHROPIC_API_KEY=

O anúncio também especifica configurações adicionais de modelos e recursos. Essas três variáveis são as configurações de conexão, e não uma configuração completa para todos os modelos. O OpenRouter alerta que a maioria dos modelos abertos não oferece suporte à busca de ferramentas, portanto as configurações variam conforme o modelo.

Sua Ori CLI automatiza a configuração por meio de:

ori login
ori claude

Os mesmos fluxos de trabalho também podem ser executados por meio de um gateway de API como o AI Prime Tech, um serviço independente sem afiliação com a Anthropic ou a OpenAI; consulte o guia sobre como usar o Claude Code com uma chave de API.

Escolha com base nos controles de que você precisa. O CCR oferece um ambiente local para gerenciar rotas, inspecionar tentativas e configurar fallbacks; a abordagem hospedada documentada elimina a necessidade de operar o CCR localmente.

Principais conclusões

• O Claude Code Router conecta o Claude Code e outros clientes a provedores por meio de um endpoint local estável com adaptação de protocolo.
• A distribuição npm exige Node.js 22+, e a interface de gerenciamento e o gateway de modelos usam portas padrão separadas.
• O escopo de Agent Config determina se um perfil se aplica apenas às inicializações pelo CCR ou também às inicializações diretas.
• Os fallbacks podem alterar o modelo que atende à solicitação; inspecione os logs de solicitações para identificar o provedor e o modelo finais.
• A v3.1.1 adiciona a importação do OpenCode Go com credenciais separadas e o tratamento obrigatório do cabeçalho de sessão.
• Um gateway hospedado pode reduzir a configuração local quando você não precisa dos controles de roteamento local do CCR.

Perguntas frequentes

O Claude Code Router é gratuito?

O Claude Code Router é licenciado sob a licença MIT, que concede permissão para usar o software. Isso não significa que a inferência upstream seja gratuita, e os preços históricos de provedores ou as franquias em dólares do OpenCode Go não são verificados aqui.

Posso usar o Claude Code com outros modelos por meio do CCR?

Sim. O CCR oferece adaptação de protocolo e seleção de provedor/modelo, e seus perfis do Claude Code permitem selecionar um modelo como Provider/model. Os formatos upstream compatíveis incluem OpenAI Chat/Responses, Anthropic Messages e Gemini Generate Content/Interactions.

O que mudou no Claude Code Router 3.1.1?

Lançada em 16 de setembro de 2026, a v3.1.1 adiciona suporte nativo à importação local do OpenCode Go, visibilidade de cada tentativa com falha e preços de uso corrigidos para modelos roteados. Ela também aumenta o tempo de aceitação da configuração do gateway para 30 segundos e aceita --daemon em start e serve.

Por que o OpenCode Go retorna MissingSessionID?

O endpoint oficial do OpenCode Go exige o cabeçalho x-opencode-session e retorna 400 MissingSessionID quando ele está ausente. A integração do Go no CCR seleciona um valor de sessão por meio de uma ordem de precedência definida e injeta o cabeçalho apenas no endpoint oficial do Go.