O Claude Code roteia todas as suas requisições através de qualquer endpoint compatível com a Anthropic para o qual você o apontar. Altere uma variável de ambiente e você estará executando Qwen, DeepSeek, GLM ou MiniMax através do fluxo agêntico completo do Claude Code — incluindo chamadas de ferramentas MCP, edição de arquivos e execução em bash — sem tocar no resto da sua configuração.
Este guia aborda como o roteamento funciona, como configurar o endpoint da Novita AI como seu backend, como as chamadas de ferramentas MCP fluem através de uma configuração roteada e como executar ferramentas de forma segura no Agent Sandbox da Novita.
O Que é um Roteador Claude Code?
Nos termos do Claude Code, um “roteador” é qualquer endpoint compatível com a API Anthropic para o qual o Claude Code envia suas requisições. Por padrão, esse endpoint é a própria API da Anthropic em api.anthropic.com. Ao definir ANTHROPIC_BASE_URL, você redireciona essas requisições para um provedor diferente — um que aceita o mesmo formato de API e retorna respostas na mesma estrutura.
Vale a pena entender isso claramente: o Claude Code não sabe nem se importa qual provedor está por trás do endpoint configurado. Ele envia uma requisição de mensagem no formato Anthropic, lê uma resposta no formato Anthropic e continua. O roteador — seja a Novita AI, um proxy auto-hospedado ou um agregador de terceiros — lida com a seleção do modelo, inferência e formatação da resposta de forma transparente.
Três razões práticas para usar um roteador:
- Acesso a modelos: Modelos de peso aberto como Qwen3-Coder, MiniMax M2.7 e GLM-4.7 não estão disponíveis no endpoint da Anthropic. Roteando através da Novita AI, você obtém acesso a todos eles dentro do mesmo fluxo de trabalho do Claude Code.
- Gestão de custos: Modelos de peso aberto através de provedores como a Novita geralmente custam significativamente menos por milhão de tokens do que os modelos fechados da Anthropic. Para sessões agênticas de alto volume onde o modelo faz centenas de chamadas de ferramentas, essa diferença se acumula.
- Capacidades especializadas: Alguns modelos de peso aberto são especificamente treinados para chamada de funções e uso de ferramentas em múltiplas etapas, que é exatamente o que a integração MCP do Claude Code exige. Escolher um modelo ajustado para precisão em chamadas de ferramentas em vez de um modelo de propósito geral pode reduzir chamadas de ferramentas malformadas ou falhas em fluxos de trabalho complexos.
Como Funciona o Roteamento no Claude Code
Três variáveis de ambiente controlam o roteamento:
| Variável | Propósito |
|---|---|
ANTHROPIC_BASE_URL |
O endpoint da API. Altere para rotear através de um provedor diferente. |
ANTHROPIC_AUTH_TOKEN |
A chave de API para autenticação no endpoint de destino. |
ANTHROPIC_MODEL |
O ID do modelo a ser usado. Deve corresponder à convenção de nomenclatura do provedor de destino. |
Quando ANTHROPIC_BASE_URL está definida, o Claude Code envia todas as requisições de inferência para essa URL em vez de https://api.anthropic.com. O endpoint de destino deve implementar o formato de API de mensagens da Anthropic — a mesma estrutura de requisição e resposta que os modelos nativos do Claude usam.
Um detalhe importante: os aliases de modelo da Anthropic (sonnet, opus, haiku) só são resolvidos corretamente contra o próprio endpoint da Anthropic. Ao usar um roteador de terceiros, defina ANTHROPIC_MODEL para o ID específico do modelo do provedor, em vez de um alias. Um alias como sonnet passado para um endpoint não-Anthropic irá falhar ou retornar um modelo inesperado.
ANTHROPIC_SMALL_FAST_MODEL é um segundo slot de modelo para tarefas internas em segundo plano do Claude Code: sumarização, compressão de contexto e raciocínio leve entre etapas. Apontar isso para um modelo mais rápido e barato reduz os custos da sessão sem afetar a qualidade das respostas do seu modelo principal.
Configurando a Novita AI como Seu Roteador
O endpoint compatível com Anthropic da Novita AI está em https://api.novita.ai/anthropic. Ele aceita o mesmo formato de requisição que o Claude Code envia nativamente e suporta uma ampla gama de modelos de peso aberto, incluindo especialistas em codificação e variantes otimizadas para chamada de ferramentas.
Passo 1: Obtenha sua chave de API da Novita
- Cadastre-se em novita.ai — créditos de teste gratuitos estão incluídos no cadastro.
- Abra Gerenciamento de Chaves no seu painel.
- Clique em Criar Nova Chave, copie a chave imediatamente (ela é mostrada apenas uma vez) e armazene-a de forma segura.
Passo 2: Configure o ambiente
macOS / Linux:
export ANTHROPIC_BASE_URL="https://api.novita.ai/anthropic"
export ANTHROPIC_AUTH_TOKEN="<sua-chave-api-novita>"
export ANTHROPIC_MODEL="qwen/qwen3-coder-480b-a35b-instruct"
export ANTHROPIC_SMALL_FAST_MODEL="deepseek/deepseek-v4-flash"
Windows (PowerShell):
$env:ANTHROPIC_BASE_URL = "https://api.novita.ai/anthropic"
$env:ANTHROPIC_AUTH_TOKEN = "<sua-chave-api-novita>"
$env:ANTHROPIC_MODEL = "qwen/qwen3-coder-480b-a35b-instruct"
$env:ANTHROPIC_SMALL_FAST_MODEL = "deepseek/deepseek-v4-flash"
Windows (Command Prompt):
set ANTHROPIC_BASE_URL=https://api.novita.ai/anthropic
set ANTHROPIC_AUTH_TOKEN=<sua-chave-api-novita>
set ANTHROPIC_MODEL=qwen/qwen3-coder-480b-a35b-instruct
set ANTHROPIC_SMALL_FAST_MODEL=deepseek/deepseek-v4-flash
Passo 3: Inicie o Claude Code
claude .
O Claude Code inicia no diretório atual e roteia toda a inferência através da Novita AI. As ferramentas MCP, edição de arquivos e execução em bash se comportam de forma idêntica a uma configuração nativa da Anthropic.
Modelos disponíveis na Novita AI
| Modelo | ID do modelo Novita | Principal ponto forte |
|---|---|---|
| Qwen3-Coder 480B | qwen/qwen3-coder-480b-a35b-instruct |
Geração de código, raciocínio de contexto longo |
| MiniMax M2.7 | minimax/minimax-m2.7 |
Precisão em chamadas de ferramentas agênticas |
| DeepSeek V4 Flash | deepseek/deepseek-v4-flash |
Iteração rápida, eficiência de custo |
| GLM-4.7 | zai-org/glm-4.7 |
Codificação e tarefas agênticas em múltiplas etapas |
| Kimi K2 Instruct | moonshotai/kimi-k2-instruct |
Uso de ferramentas, bases de código com foco matemático |
Esses modelos de peso aberto são executados em infraestrutura GPU moderna, mas seu custo por token é tipicamente muito menor. Em tarefas como sessões de refatoração estendidas ou geração automatizada de testes — onde o Claude Code faz dezenas de chamadas de ferramentas — essa diferença no custo por token importa na prática.
Verifique novita.ai/llm-api para a lista atual de modelos e IDs verificados antes de finalizar sua configuração. A disponibilidade e os IDs dos modelos podem mudar à medida que os provedores adicionam ou atualizam ofertas.
Roteando Chamadas de Ferramentas Através do MCP
A camada de chamada de ferramentas do Claude Code é o MCP — o Model Context Protocol. Quando você adiciona um servidor MCP com claude mcp add, o Claude Code se conecta a ele no início da sessão e carrega as ferramentas que ele expõe. Durante uma sessão, o LLM roteado decide quando chamar essas ferramentas, quais argumentos passar e como agir com base nos resultados.
A divisão do roteamento é importante: o backend LLM (seu roteador Novita AI) lida com todo o raciocínio — quais ferramentas invocar, em qual sequência e com quais argumentos. O servidor MCP lida com a execução — ele recebe as chamadas de ferramentas, executa a ação subjacente e retorna os resultados. O Claude Code coordena entre eles.
Na prática, isso significa que a qualidade do suporte a chamadas de ferramentas do seu roteador determina quão confiavelmente tarefas complexas de múltiplas etapas são concluídas. Um modelo que gera argumentos de chamada de função malformados ou falha ao continuar após erros de ferramenta irá parar no meio de uma tarefa. Modelos especificamente ajustados em fluxos de trabalho de chamada de funções — como Qwen3-Coder e MiniMax M2.7 — lidam com essas sequências de forma mais consistente.
Adicionando um servidor MCP a uma configuração roteada
# Servidor local (escopo do projeto) — Claude Code inicia o processo
claude mcp add meu-servidor -- python meu_servidor.py
# Servidor HTTP remoto — conecta a um servidor já em execução
claude mcp add servidor-remoto --transport http https://seu-servidor.exemplo.com/mcp
A opção HTTP remota conecta-se a um servidor em execução independente. Essa é a arquitetura para a qual o Novita Agent Sandbox foi construído: o servidor MCP permanece em execução e cria instâncias sandbox sob demanda à medida que as chamadas de ferramentas chegam.
Executando Ferramentas no Agent Sandbox
Quando suas ferramentas MCP envolvem executar código, processar arquivos ou chamar sistemas externos, você quer que essa execução ocorra em um ambiente isolado, em vez de em sua máquina de desenvolvimento. O Novita Agent Sandbox fornece isso como um serviço gerenciado em nuvem.
Uma instância Sandbox é um contêiner isolado de curta duração que seu servidor MCP cria quando o Claude Code aciona uma ferramenta de execução de código. Cada contêiner fornece:
- Sistema de arquivos isolado: separado do host, nada vaza entre sessões
- Ambiente pré-instalado: Python com pacotes comuns de ciência de dados e scripting
- Inicialização rápida: inicialização a frio abaixo de 200ms, adequada para sequências de chamadas de ferramentas de baixa latência
- Faturamento por segundo: você paga apenas pelo tempo de execução ativo
- Execução em shell e Python: acesso completo à linha de comando para fluxos de trabalho em várias linguagens
O fluxo de dados em uma configuração roteada do Claude Code com Sandbox se parece com isso:
Claude Code
→ envia requisições de raciocínio para a API LLM Novita (o roteador)
→ recebe decisões de chamadas de ferramentas do modelo
→ encaminha chamadas de ferramentas para o servidor MCP
→ servidor MCP cria uma instância Novita Sandbox
→ Sandbox executa o código e retorna a saída
→ servidor MCP retorna resultados para o Claude Code
→ API LLM Novita raciocina sobre os resultados, decide o próximo passo
Essa separação mantém a execução de código não confiável contida, enquanto dá ao roteador LLM visibilidade total dos resultados para raciocínio em múltiplas etapas.
Para usar o Novita Sandbox de dentro de um manipulador de ferramentas MCP, instale o SDK:
pip install novita-sandbox
Em seguida, crie e use uma instância sandbox dentro da sua implementação de ferramenta:
from novita_sandbox.code_interpreter import Sandbox
def run_code_tool(code: str, api_key: str) -> dict:
sandbox = Sandbox.create(
template="code-interpreter-v1",
api_key=api_key,
domain="sandbox.novita.ai",
timeout=300,
)
result = sandbox.run_code(code, language="python")
sandbox.kill()
return {
"output": result.logs,
"error": result.error,
}
O template code-interpreter-v1 vem pré-instalado com pandas, numpy, matplotlib e outros pacotes comumente usados, então a maioria das tarefas de análise de dados e scripting são executadas sem etapas adicionais de configuração.
Escolhendo um Modelo para Fluxos de Trabalho com Muitas Ferramentas
A escolha do modelo afeta duas coisas em uma configuração roteada do Claude Code: a qualidade do raciocínio para decidir o que fazer e a confiabilidade das chamadas de ferramentas para executá-lo corretamente. Esses dois aspectos nem sempre se correlacionam — um modelo que raciocina bem em tarefas abertas pode gerar esquemas de chamada de função inconsistentes quando as ferramentas têm tipos de argumento complexos.
Qwen3-Coder 480B tem um bom desempenho em tarefas de codificação de longo horizonte onde o Claude Code precisa ler muitos arquivos, planejar uma abordagem e executar uma sequência de edição em várias etapas. Sua capacidade de lidar com contexto longo significa que é menos provável perder o rastro de resultados de ferramentas anteriores no meio de uma tarefa complexa.
MiniMax M2.7 é ajustado para precisão agêntica — especificamente, é projetado para minimizar invocações incorretas de ferramentas e lidar com sequências de ferramentas de múltiplas voltas onde cada etapa se baseia no resultado anterior. Para configurações MCP com várias ferramentas interdependentes, essa precisão reduz o número de loops de recuperação necessários.
DeepSeek V4 Flash é a escolha prática para ANTHROPIC_SMALL_FAST_MODEL. É rápido e barato, e as tarefas que o Claude Code descarrega para o modelo pequeno — sumarização de sessão, compressão de contexto — não exigem a mesma profundidade de raciocínio que as tarefas principais de codificação.
Uma observação prática: se você estiver construindo um servidor MCP personalizado com ferramentas que possuem muitos parâmetros opcionais ou esquemas aninhados, teste a precisão das chamadas do modelo com exemplos representativos antes de implantar em uma sessão de longa duração. Erros de chamada de ferramentas são menos prejudiciais quando detectados precocemente.
FAQ
Posso usar qualquer roteador LLM com o Claude Code, não apenas a Novita AI?
Sim. Qualquer serviço que implemente a API de mensagens Anthropic em sua URL base funciona. Isso inclui LiteLLM configurado com o formato Anthropic, proxies auto-hospedados ou outros serviços de roteamento comerciais. Defina ANTHROPIC_BASE_URL para esse endpoint, ANTHROPIC_AUTH_TOKEN para a chave apropriada e ANTHROPIC_MODEL para o ID do modelo que o endpoint reconhece.
As ferramentas MCP funcionam ao rotear através de um provedor não-Anthropic?
Sim. O MCP opera na camada do Claude Code, não no nível da API. O roteador afeta apenas qual modelo faz o raciocínio sobre o uso da ferramenta. Desde que o modelo suporte chamada de funções no formato de mensagens Anthropic, as ferramentas MCP funcionam da mesma forma independentemente do provedor.
Por que o alias sonnet não funciona ao rotear através da Novita AI?
Os aliases de modelo da Anthropic (sonnet, opus, haiku) são resolvidos pelo endpoint da Anthropic, não pelo Claude Code. Quando você roteia através de um provedor terceiro, a resolução de alias da Anthropic não está envolvida. Defina ANTHROPIC_MODEL para um ID de modelo específico do seu provedor.
Como faço para voltar aos modelos nativos da Anthropic?
Desative as variáveis de roteamento para a sessão atual:
unset ANTHROPIC_BASE_URL
unset ANTHROPIC_AUTH_TOKEN
unset ANTHROPIC_MODEL
unset ANTHROPIC_SMALL_FAST_MODEL
O Claude Code volta ao que está no seu arquivo de configurações ou ao padrão da API Anthropic na próxima inicialização.
Há sobrecarga de latência ao usar um roteador de terceiros?
Há um pequeno salto adicional de rede. Para sessões interativas, isso geralmente não é perceptível. Para pipelines automatizados sensíveis à latência, verifique os números de latência publicados pelo provedor antes de se comprometer. A Novita AI publica métricas de latência e throughput de inferência através do seu console de Métricas LLM.
O Agent Sandbox requer uma chave de API separada do roteador LLM?
Não. A chave de API da Novita AI funciona tanto para a API LLM quanto para o Agent Sandbox. A mesma chave que você usa para ANTHROPIC_AUTH_TOKEN é o que você passa para Sandbox.create() na sua implementação de ferramenta MCP.
Artigos Recomendados
- Comando Claude MCP Add: Como Instalar Servidores MCP no Claude Code
- Modelo Padrão do Claude Code: Como Alterar, Trocar e Escolher o Correto
- Construa um Servidor MCP de Execução Remota de Código com Novita Sandbox e a Biblioteca mcp-use
Fontes verificadas em 16 de julho de 2026: Documentação de variáveis de ambiente do Claude Code, API LLM Novita AI, Novita Agent Sandbox.
