Formulário de contato

Nome

E-mail *

Mensagem *

Imagem

Claude Code com NVIDIA NIM: guia do CCR 2026

Claude Code com NVIDIA NIM: guia do CCR 2026

Publicado por em


@CanalQb no YouTube


@CanalQb

Claude Code com NVIDIA NIM: guia do CCR 2026


Leitura: ~22 min
TL;DR:
  • A NVIDIA NIM fala o formato OpenAI e o Claude Code fala o formato Anthropic, então o caminho que funcionou nos nossos testes foi colocar o CCR (Claude Code Router) no meio, em 127.0.0.1:3456.
  • Com o gateway no ar, o Claude Code respondeu, executou ferramentas (Bash) e trocou de modelo por fallback, tudo com modelos abertos do catálogo build.nvidia.com.
  • Use o CCR como padrão, guarde a chave somente em um arquivo local com permissão 600 e aceite o atraso do primeiro prompt interativo em ambiente Termux/proot.

Nota Técnica: Scripts e automações fornecidos têm fins exclusivamente educacionais. Teste sempre em ambiente controlado. @CanalQb não se responsabiliza por danos, perdas ou bloqueios decorrentes do uso indevido. Nunca publique sua chave nvapi em repositório, print ou vídeo.

Em 17 de novembro de 2026 o nosso Claude Code travou olhando para a mesma tela durante vários minutos, e o motivo era um proxy que tinha morrido em segundo plano. O resultado dessa dor foi uma mudança de arquitetura que rodou limpa depois: do LiteLLM para o CCR.

Aqui em @CanalQb validamos o caminho completo, com chave real, e o que você vai ler abaixo mistura o que deu certo, o que quebrou e o que ainda incomoda. Antes de configurar qualquer coisa, vale entender por que o atalho óbvio, apontar o Claude Code direto para a NVIDIA, não resolveu.

Quais são as soluções rápidas para os problemas mais comuns?

Os travamentos e erros deste setup vêm quase sempre de cinco pontos: proxy fora do ar, chave carregada no lugar errado, modelo sem acesso na conta, limite de requisições e configuração sem revisão. Cada item abaixo traz a correção imediata e aponta para o passo completo.

  • Claude Code travado na tela inicial: o gateway caiu. Rode o health-check do wrapper ou ccr start --daemon --no-open. ver passo completo
  • 404 model not found no /v1/messages: a NVIDIA não serve o formato Anthropic para a sua conta; use o CCR. ver passo completo
  • HTTP 409 ao salvar a configuração: falta o campo configRevision no saveConfig. ver passo completo
  • 404 Function not found for account: o modelo não está liberado na sua conta; teste um por um e use só os que devolvem 200. ver passo completo
  • 429 de limite: espere, reduza requisições paralelas ou deixe a cadeia de fallback assumir. ver passo completo

Por que usar o Claude Code com modelos da NVIDIA NIM?

Porque o Claude Code entrega o fluxo de agente, que lê arquivos, roda comandos e edita código, enquanto a NVIDIA NIM oferece em build.nvidia.com um catálogo de modelos abertos acessível por chave de desenvolvedor. O custo deixa de ser fatura e vira limite de requisições, e você escolhe qual modelo faz cada papel.

A motivação prática é separar a interface do cérebro. O Claude Code é a camada que sabe abrir um repositório, propor uma edição, pedir permissão e executar uma ferramenta. O modelo que responde por trás dessa interface pode ser outro, desde que fale com ela do jeito certo. Quem já configurou o Hermes Agent com modelos NVIDIA conhece a ideia: um agente, vários modelos hospedados, uma cadeia de reserva para quando um falha.

Há também uma razão de experimento. Nos nossos testes, o modelo principal foi o mistralai/mistral-large-4-1t-a52b, o modelo rápido para tarefas de fundo foi o nvidia/nemotron-3.5-bolt-e4b e o modelo mais pesado foi o nvidia/nemotron-3.5-lightning-30b-a3b. Ter três perfis no mesmo terminal permite comparar qualidade, latência e comportamento com ferramentas sem trocar de programa.

Agora o lado honesto: isso não transforma o Claude Code em outro produto. Recursos que dependem da infraestrutura da Anthropic, como o Remote Control e a voz, ficam indisponíveis quando a URL base não é a oficial, e a documentação do Claude Code para gateways diz que ambientes hospedados na nuvem da Anthropic também deixam de aparecer. Espere um agente local, funcional, e não uma réplica completa. A qualidade das respostas também varia por modelo, principalmente quando entram chamadas de ferramenta, e por isso o post inteiro insiste em validar cada modelo antes de fixá-lo na configuração.

Como o Claude Code, o CCR e a NVIDIA NIM conversam entre si?

O Claude Code envia requisições no formato Anthropic Messages para a URL definida em ANTHROPIC_BASE_URL. A NVIDIA NIM responde no formato OpenAI Chat Completions. O CCR roda localmente na porta 3456, recebe o formato Anthropic e traduz para o OpenAI, devolvendo a resposta no formato que o Claude Code espera.

O fluxo ativo que usamos é este: o comando claude passa por um wrapper, o wrapper chama um script de verificação que garante o CCR no ar, o CCR escuta em 127.0.0.1:3456 e fala com https://integrate.api.nvidia.com/v1 usando o protocolo openai_chat_completions. O catálogo hospedado da NVIDIA documenta uma base única e autenticação por Bearer token, compatível com clientes OpenAI, o que explica por que o provider no CCR é cadastrado como OpenAI Chat Completions.

claude (wrapper) -> ensure-ccr.sh -> CCR 127.0.0.1:3456
                                      |  openai_chat_completions
                                      v
                          NVIDIA NIM integrate.api.nvidia.com/v1

Por que não apontar o Claude Code direto para a NVIDIA? Testamos: com a chave real, a rota POST /v1/messages devolveu 404 model not found. Sem chave, a resposta já vinha no formato de erro da Anthropic, o que sugeria que a rota existia, e foi isso que nos fez testar o caminho direto primeiro. Com a chave, o erro persistiu e o plano direto foi descartado. Já o endpoint /v1/chat/completions respondeu 200 para os três modelos principais, e o /v1/models listou 32 modelos no catálogo da nossa conta.

O ponto de atenção é a diferença de versões no tempo. Um guia de setembro de 2026 relatava 404 puro nessa rota; a nossa verificação de novembro mostrou a rota reconhecendo o formato de erro, mas ainda recusando o modelo. Isso pode mudar, e por isso o teste curl do Passo 1 da seção de validação existe: ele custa uma requisição e evita montar um gateway desnecessário se a NVIDIA passar a aceitar o formato Anthropic.

O que preciso ter instalado antes de começar?

Você precisa de Node.js com npm, do Claude Code instalado, de uma chave nvapi gerada em build.nvidia.com e de um terminal onde possa manter um processo em segundo plano. Nos nossos testes usamos o Claude Code v2.1.326, mas confira a versão atual antes de seguir.

A chave é o item mais sensível. Para gerar, entre em build.nvidia.com, entre com a conta de desenvolvedor, abra um modelo e use a opção de gerar API key. Ela começa com nvapi-. A partir daí a regra é única: a chave vive em uma variável de ambiente carregada de um arquivo local com permissão 600, e nunca no settings.json, em documentação ou em repositório. Se uma chave vazar em print de vídeo, revogue e gere outra.

O segundo requisito é conhecer os limites da conta. O catálogo é grande, mas a sua conta enxerga uma parte: o /v1/models listou 32 modelos para nós, enquanto o guia anterior do Hermes tinha encontrado cerca de 83 em outra conta. Um modelo que existe no catálogo público pode devolver 404 Function not found for account para você. Por isso nunca copie a lista de modelos de um tutorial sem testar. Reportagens e testes públicos citam um teto de aproximadamente 40 requisições por minuto no uso gratuito, mas esse número muda; verifique o seu limite na própria página da conta antes de planejar trabalho pesado.

Terceiro: um shell estável. Se você roda em Android com Termux e proot, como no nosso caso, saiba que o DNS pode falhar de forma intermitente, que o CCR cobre parte disso com tentativas de novo e fallback, e que alguns comportamentos do Claude Code se arrastam por causa da emulação, o que detalhamos na seção de limitações. Em Linux, macOS ou WSL comum, esse problema específico não deve aparecer.

ItemComo obterObservação
Node.js e npmGerenciador do seu sistemaNecessário para instalar o CCR globalmente
Claude Codenpm install -g @anthropic-ai/claude-codeTestado na v2.1.326
Chave nvapibuild.nvidia.comGuardar em arquivo local, chmod 600
CCRnpm install -g @musistudio/claude-code-routerTestado na v3.1.5; confira a atual

Como instalar e subir o CCR passo a passo?

Instale o pacote @musistudio/claude-code-router com npm, suba o serviço com ccr start --daemon --no-open e confirme que a porta 3456 responde. O CCR guarda a configuração em um banco SQLite na pasta ~/.claude-code-router, e a interface de gestão fica em uma porta separada.

  1. Instale o CCR globalmente. Rode o comando abaixo. Ele baixa o pacote do npm e cria o executável ccr no PATH. Sem a instalação global, os próximos comandos dão command not found. No nosso teste a versão instalada foi a 3.1.5; se aparecer versão diferente, tudo bem, mas os nomes de menu e rotas internas podem mudar.
    npm install -g @musistudio/claude-code-router
    Resultado esperado: o npm termina sem erro e ccr --version mostra a versão. Erro comum: EACCES em permissão de pasta global; use um prefixo npm do seu usuário em vez de sudo.
  2. Suba o gateway em segundo plano. O modo daemon mantém o CCR vivo depois que você fecha o terminal, e a opção --no-open impede que ele abra o navegador sozinho. Sem o daemon, o gateway morre junto com a sessão e o Claude Code volta a travar, que foi exatamente o defeito do nosso proxy anterior.
    ccr start --daemon --no-open
    Resultado esperado: o comando retorna rápido e o gateway Anthropic passa a responder em http://127.0.0.1:3456, com as rotas /v1/messages e /v1/models. Erro comum: porta ocupada por processo antigo; encerre-o antes, sem usar padrões amplos de pkill.
  3. Confirme que a configuração foi criada. No primeiro uso o CCR cria o banco SQLite em ~/.claude-code-router/config.sqlite, conforme a documentação do projeto para macOS e Linux. É nesse banco que ficam o provider, as rotas e os perfis. Se você vem de versões antigas, o config.json legado só é lido uma vez para migração quando não existe SQLite. Resultado esperado: o arquivo existe depois da primeira subida. Erro comum: editar o config.json antigo esperando efeito; no formato atual a fonte de verdade é o SQLite.
  4. Pare e reinicie quando precisar. Use ccr stop para derrubar e o mesmo comando de start para subir. Depois de qualquer mudança de configuração feita por arquivo, reiniciar é a forma segura de garantir que o serviço leu o estado novo.
    ccr stop
    ccr start --daemon --no-open
    Resultado esperado: o gateway reaparece na porta 3456. Erro comum: esquecer o --daemon e perder o serviço ao fechar o terminal.

Uma observação sobre a interface de gestão: no nosso ambiente ela ficou na porta 3458, protegida por um token local enviado no cabeçalho de autenticação. Escolha um token próprio e longo, mantenha esse acesso só em localhost e nunca copie token de exemplo de tutorial para a sua máquina.

Como cadastrar o provider NIM e as rotas dentro do CCR?

Cadastre um provider chamado nim com protocolo openai_chat_completions e base https://integrate.api.nvidia.com/v1, liste os modelos validados, crie a rota que leva os nomes claude-* para o modelo principal e monte a cadeia de fallback. A chave é lida do ambiente, não digitada na configuração.

Pela interface do CCR isso é formulário. Por RPC, é uma sequência: getConfig para ler o estado atual, ajuste, e saveConfig para gravar. O detalhe que custou tempo foi o controle de concorrência: o saveConfig exige o campo configRevision devolvido pelo getConfig, e sem ele a resposta é HTTP 409. Pense nisso como um bloqueio otimista, em que a revisão evita que duas edições simultâneas se sobrescrevam.

PeçaValor usado nos testes
Nome do providernim
Protocoloopenai_chat_completions
Basehttps://integrate.api.nvidia.com/v1
Modelos cadastradosmistralai/mistral-large-4-1t-a52b, nvidia/nemotron-3.5-bolt-e4b, nvidia/nemotron-3.5-lightning-30b-a3b
Rota claude-*regra claude-to-nim, destino nim/mistralai/mistral-large-4-1t-a52b
Fallbackcadeia de modelos: bolt, depois lightning, com uma nova tentativa

Dois cuidados que não aparecem em lugar nenhum da documentação básica. Primeiro, as regras de rota só persistiram quando foram gravadas com type igual a condition e com o campo condition preenchido; regra sem isso parecia salva e sumia. Segundo, o nome do modelo que o Claude Code envia tem o prefixo do provider: nim/ seguido do identificador da NVIDIA, e é por esse nome completo que o roteamento decide o destino.

O motivo da regra claude-* é simples. O Claude Code, por baixo, ainda pede modelos com nome de Claude em algumas chamadas internas, como as de tarefas de fundo. Sem uma regra que capture esses nomes, o gateway não saberia para onde mandar, e a requisição falharia. Nos testes, as chamadas com claude-sonnet-4-5 e claude-haiku-4-5 devolveram 200 justamente porque a regra e a rota embutida existiam.

Por fim, o perfil do Claude Code dentro do CCR (modelo principal, haiku, sonnet, opus e subagente) permite aplicar tudo de uma vez: ao aplicar o perfil, o CCR escreve o bloco env e o apiKeyHelper no ~/.claude/settings.json, que é o assunto da próxima seção.

Como apontar o Claude Code para o gateway no settings.json?

Edite o ~/.claude/settings.json, no bloco env, definindo ANTHROPIC_BASE_URL como http://127.0.0.1:3456 e os modelos por tier com o prefixo nim/. Use apiKeyHelper para a credencial. A documentação do Claude Code descreve exatamente esse mecanismo para gateways: variáveis de ambiente em arquivo de configurações valem em qualquer lugar onde o Claude Code rodar.

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:3456",
    "NO_PROXY": "127.0.0.1,localhost,::1",
    "ANTHROPIC_MODEL": "nim/mistralai/mistral-large-4-1t-a52b",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "nim/nvidia/nemotron-3.5-bolt-e4b",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "nim/mistralai/mistral-large-4-1t-a52b",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "nim/nvidia/nemotron-3.5-lightning-30b-a3b",
    "CLAUDE_CODE_SUBAGENT_MODEL": "nim/nvidia/nemotron-3.5-bolt-e4b",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1"
  },
  "apiKeyHelper": "~/.claude-code-router/bin/ccr-claude-code-api-key-default-claude-code"
}

Cada variável tem função. ANTHROPIC_BASE_URL manda as requisições para o gateway local. NO_PROXY impede que um proxy de sistema intercepte o tráfego local. As três variáveis ANTHROPIC_DEFAULT_*_MODEL fixam qual modelo atende cada tier, e CLAUDE_CODE_SUBAGENT_MODEL define o modelo dos subagentes. A variável de descoberta de modelos do gateway deixa o seletor mais útil. O apiKeyHelper é um executável que devolve a credencial local do gateway, e é o CCR que o gera, assim a sua chave nvapi nunca passa por esse arquivo.

Um ponto de documentação que costuma morder: vários guias de gateways, incluindo os de provedores como Portkey e Hivenet, orientam não colocar /v1 no final da URL base, porque o Claude Code acrescenta o caminho /v1/messages sozinho. No nosso caso, a base é o endereço do CCR sem sufixo, o que respeita essa regra. Se você apontar para algo com /v1 e ver erros estranhos de rota, comece por aí.

Atenção também para a precedência de credenciais. Os guias de gateway lembram que um ANTHROPIC_API_KEY definido no ambiente tem prioridade sobre ANTHROPIC_AUTH_TOKEN e pode desviar o tráfego do gateway. Em caso de comportamento duvidoso, rode /status dentro do Claude Code e confirme qual URL e qual credencial estão ativas.

Como validar cada modelo antes de confiar nele?

Faça um teste hello world por modelo, primeiro direto na NVIDIA e depois pelo gateway. Só entra em uso o modelo que responde 200 com conteúdo. Em seguida, teste uma chamada de ferramenta, porque o Claude Code depende disso para executar comandos e editar arquivos.

A validação em três camadas foi o que nos poupou de surpresas. Na primeira, o catálogo: um GET em /v1/models com o cabeçalho Authorization mostra o que a sua conta enxerga. Na segunda, o chat direto: um POST em /v1/chat/completions com o modelo desejado e a frase de teste. Na terceira, o gateway: um POST em http://127.0.0.1:3456/v1/messages com o nome nim/... do modelo.

curl -sS https://integrate.api.nvidia.com/v1/chat/completions \
  -H "Authorization: Bearer $NVIDIA_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"nvidia/nemotron-3.5-bolt-e4b","max_tokens":64,
       "messages":[{"role":"user","content":"Say exactly: hello world"}]}'

Resultado esperado: HTTP 200 e o texto hello world dentro da resposta. Alguns modelos, como o mistral-large-4, devolvem blocos de raciocínio antes do texto; isso é normal e o gateway preserva. Se aparecer 401, a chave está errada ou a variável não foi carregada. Se aparecer 404 Function not found for account, o modelo existe no catálogo mas não está liberado para você, e ele deve ser tirado da lista.

Depois dos testes de resposta, validamos ferramentas. Pelo gateway, um pedido com a ferramenta Bash e o comando echo TOOL-OK retornou um bloco tool_use. No Claude Code em modo não interativo, o comando claude -p com o mesmo pedido executou a ferramenta e mostrou a saída. Na mesma linha, os testes de ponta a ponta do dia 17 de novembro de 2026 terminaram assim: hello world com exit 0, E2E-OK com exit 0, e uma ressurreição do gateway em cerca de 1 segundo depois de matarmos o CCR de propósito.

O que fazer quando um modelo passa no hello world e falha com ferramentas? Troque o papel dele. Um modelo que só gera texto limpo e rápido pode servir de haiku ou de subagente simples, e um modelo que faz boas chamadas de ferramenta deve ficar com o tier principal. Documentação e testes públicos da própria NVIDIA e de terceiros convergem num aviso: a qualidade de function calling varia bastante entre os modelos do catálogo.

Como fazer o gateway subir sozinho com um wrapper?

Crie um script de verificação que testa a porta 3456 e, se ela estiver fechada, sobe o CCR; depois faça o comando claude do seu PATH chamar esse script antes de executar o binário real. Assim o Claude Code nunca encontra um gateway morto, que era a causa do travamento.

O desenho é de dois arquivos. O primeiro, que chamamos de ensure-ccr, faz só uma coisa: verifica se há algo respondendo em 127.0.0.1:3456 e, se não houver, executa ccr start --daemon --no-open e espera a porta abrir. O segundo, o wrapper chamado claude, fica num diretório que vem antes no PATH, chama o primeiro e então executa o binário verdadeiro repassando todos os argumentos. Quando matamos o CCR de propósito, o wrapper reviveu o gateway em cerca de 1 segundo e o comando seguinte respondeu normalmente.

#!/usr/bin/env bash
# modelo de referencia: adapte caminhos e teste no seu ambiente
if ! curl -fsS -o /dev/null http://127.0.0.1:3456/v1/models; then
  ccr start --daemon --no-open
  for i in 1 2 3 4 5 6 7 8 9 10; do
    curl -fsS -o /dev/null http://127.0.0.1:3456/v1/models && break
    sleep 1
  done
fi

Esse trecho é um modelo escrito para ilustrar a lógica, não o nosso script exato, então teste antes de depender dele. Dois cuidados valem ouro. Primeiro, a chave NVIDIA deve ser carregada de um arquivo local com permissão 600 por quem precisa dela, e não impressa nem exportada em arquivo versionado. Segundo, evite o pkill com padrões que também aparecem no seu próprio script: o padrão casa com o shell em execução e ele se mata.

Para o PATH, coloque o diretório do wrapper antes do diretório do binário real no seu perfil de shell. Teste com which claude: se apontar para o wrapper, está certo. Se você atualizar o Claude Code pelo npm, o wrapper continua funcionando porque ele só repassa a execução, mas confira a versão com claude --version depois da atualização.

Por que isso importa mais do que parece? Porque a falha silenciosa é a pior de todas: o comando abre, não dá erro e simplesmente fica parado. Com o health-check embutido, o defeito de infraestrutura vira um custo de 1 segundo no início, e não um terminal congelado que o iniciante interpreta como erro de configuração.

Por que o LiteLLM foi substituído e quando ele ainda vale?

O LiteLLM funcionou nos testes, com 200 em /v1/messages e ferramentas OK, mas o processo proxy morria em segundo plano e travava o Claude Code. O CCR resolveu o problema operacional com daemon e auto-start. O LiteLLM ainda vale se você quer uma cadeia de fallback longa declarada em um arquivo YAML.

O primeiro plano alternativo era um proxy LiteLLM em localhost:4000, traduzindo Anthropic para OpenAI com o prefixo nvidia_nim. A configuração que usamos tinha oito modelos nomeados (nim-primary, nim-bolt, nim-lightning, nim-ultra, nim-glm, nim-gemma, nim-minimax e nim-nano), com drop_params ligado, duas tentativas, tempo limite de 180 segundos e uma cadeia em que o primário cai para os demais na ordem listada.

litellm_settings:
  drop_params: true
  num_retries: 2
  request_timeout: 180
  fallbacks:
    - nim-primary: [nim-bolt, nim-lightning, nim-ultra,
                    nim-glm, nim-gemma, nim-minimax, nim-nano]

Do ponto de vista de capacidade, o LiteLLM é mais declarativo: a cadeia inteira de oito modelos fica num arquivo que você versiona sem segredos, já que a chave vem de os.environ. Do ponto de vista de operação, ele foi pior para nós: sem um supervisor, o processo caiu e a ferramenta ficou parada. A instalação também exigiu cuidados específicos de ambiente, como Python 3.12 em vez de 3.14 e a opção UV_LINK_MODE=copy porque o sistema de arquivos do Android não aceitou hardlinks.

A regra que adotamos: use o CCR como caminho principal quando o Claude Code é o centro do seu fluxo, e considere o LiteLLM quando você já tem um proxy central na equipe, quando precisa de uma cadeia grande com muitos modelos ou quando quer servir outros clientes além do Claude Code. Se escolher o LiteLLM, defina CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 para evitar erros 400 com campos beta que o backend não conhece, e evite as versões 1.82.7 e 1.82.8, que tinham bugs conhecidos quando fizemos o teste.

Por fim, não deixe os dois ativos ao mesmo tempo. O LiteLLM usava a porta 4000 e o CCR usa a 3456; se o settings.json ainda apontar para a porta antiga, o sintoma é um Claude Code que parece vivo e nunca responde.

Qual modelo usar em cada papel do Claude Code?

Use um modelo grande e com boa chamada de ferramentas no papel principal, um modelo pequeno e rápido para haiku e subagentes, e um modelo pesado no papel de opus. Nos nossos testes: mistral-large-4 como principal, nemotron-3.5-bolt-e4b como rápido e nemotron-3.5-lightning-30b-a3b como pesado.

O Claude Code distribui trabalho por tiers. O tier principal cuida da conversa e da edição, o tier haiku recebe tarefas de fundo e curtas, o tier opus entra quando a tarefa pede raciocínio mais longo, e os subagentes têm variável própria. Mapear cada tier para um modelo diferente é a forma de gastar o limite de requisições com inteligência: o modelo rápido absorve volume, o grande absorve dificuldade.

PapelModelo (prefixo nim/)Comportamento observado
Principal e sonnetmistralai/mistral-large-4-1t-a52bRespondeu com bloco de raciocínio e texto
Haiku e subagentenvidia/nemotron-3.5-bolt-e4bRápido, texto limpo
Opusnvidia/nemotron-3.5-lightning-30b-a3bRespondeu com raciocínio e texto

No catálogo da nossa conta, outros cinco modelos também responderam no chat e podem entrar como reserva: nemotron-3-ultra-550b-a55b, glm-5.3-flash da z-ai, gemma-4-31b-it do Google, minimax-m3.1-flash e a variante nano com raciocínio. O llama-3.2-90b-vision-instruct, que aparecia no guia anterior, estava fora do catálogo desta conta, o que reforça o aviso: lista de modelo é por conta, não universal.

Uma decisão prática para o leitor. Comece com apenas dois modelos, um principal e um rápido, e só acrescente mais quando tiver motivo mensurável. Cada modelo novo é um ponto a mais de falha de ferramenta e um comportamento a mais para depurar. A cadeia de fallback, por sua vez, deve ser curta no CCR: bolt e depois lightning foi suficiente nos testes, e uma cadeia longa só adiciona latência quando a causa do erro é a conta inteira, e não o modelo.

Lembre ainda que o seletor /model do Claude Code, por padrão, só lista nomes que contêm claude ou anthropic. Para escolher modelos NIM sem mexer no arquivo, use a opção --model com o nome completo, por exemplo --model nim/nvidia/nemotron-3.5-bolt-e4b, ou habilite a descoberta de modelos do gateway.

Quais limitações reais você vai encontrar nesse setup?

As limitações são três: o primeiro prompt do modo interativo pode demorar cerca de 15 segundos em ambiente Termux com proot, um aviso de modelo não reconhecido aparece no início, e recursos dependentes da Anthropic ficam indisponíveis. O gateway e as respostas em si funcionaram, e o aviso é só cosmético.

O atraso do primeiro prompt foi a parte mais cara de investigar, e vale o relato completo porque é o nosso insight inédito deste post. No modo interativo, o Claude Code sempre roda uma indexação de arquivos do projeto; no modo não interativo (claude -p) essa etapa nunca aparece nos logs. Em Android com proot, o disparo dos processos git e rg pelo Bun pendura por 12 a 26 segundos antes de falhar. Medimos o contexto assentado em 14,8 segundos, o git ls-files em 15,7 segundos, a atualização de cache em 23 segundos, o primeiro byte da API em 2,3 segundos e o fim do turno com a resposta em 4,2 segundos de API. Ou seja: o atraso é do ambiente, não do CCR nem da NVIDIA.

Testamos de tudo para eliminá-lo. Variáveis de ambiente como CLAUDE_CODE_USE_NATIVE_FILE_SEARCH=0 e CLAUDE_CODE_REMOTE=true não pularam a indexação interativa. Wrapper de git não adiantou, porque o travamento acontece no disparo do processo, não no git em si. E patch no binário claude.exe foi pior: trocas de string com mudança de tamanho corromperam o executável, e a troca de mesmo tamanho gerou Bus error 135. A conclusão firme é: não patche o binário, e se já mexeu, restaure do backup.

Sobre o aviso unrecognized_model, a mensagem diz que o Claude Code assume uma janela de contexto de 1 milhão para um modelo que ele não conhece. É só aviso: o modelo funciona. O terceiro ponto é o escopo: com URL base fora da Anthropic, Remote Control e voz ficam indisponíveis. Para o seu caso, três caminhos restam: aceitar o atraso residual, rodar fora do proot se o ambiente permitir ou esperar a correção do reaping de processos no Bun.

Em Linux, macOS ou WSL nativos, não esperamos o problema do proot, mas não testamos nesses ambientes, então trate isso como hipótese e meça o seu tempo com claude --debug se notar demora.

Como depurar quando algo para de funcionar?

Comece pelo gateway, depois pela chave, depois pelo modelo. Confirme se a porta 3456 responde, se a variável da chave está carregada e se o modelo ainda devolve 200 direto na NVIDIA. Só depois olhe o Claude Code. Os logs de depuração do Claude Code mostram o que acontece no primeiro turno.

Essa ordem economiza tempo porque cada camada tem um sintoma típico. Gateway fora do ar parece Claude Code congelado. Chave ausente produz 401. Modelo sem acesso produz 404 com a mensagem de função não encontrada. Limite de requisições produz 429. Um modelo que responde mas não usa ferramentas produz sessões que conversam e não agem.

CLAUDE_CODE_DEBUG_LOGS_DIR=/tmp/cc-logs \
CLAUDE_CODE_DEBUG_LOG_LEVEL=debug claude --debug

# modo nao interativo, com log em ~/.claude/debug/
claude -p "Reply with exactly: E2E-OK" --debug

Para o CCR, há dois sistemas de log descritos na documentação do projeto: os logs de servidor, com requisições HTTP e chamadas de API, em ~/.claude-code-router/logs/, e os logs da aplicação, com decisões de roteamento, em um arquivo claude-code-router.log na mesma pasta. Versões recentes também trazem uma página de observabilidade com provedor, modelo, latência e uso de tokens por requisição, o que ajuda a descobrir se o fallback entrou em ação.

Um hábito útil: depois de qualquer mudança, rode o mesmo teste mínimo, claude -p com a frase pedindo uma resposta exata. Se esse comando responde e sai com código 0, o encadeamento claude, gateway e NVIDIA está inteiro, e qualquer problema restante está na tarefa que você pediu, não na infraestrutura.

Perguntas frequentes sobre Claude Code com NVIDIA NIM

Dá para usar o Claude Code direto com a NVIDIA, sem CCR?
Na nossa conta, não. Em novembro de 2026 a rota /v1/messages da NVIDIA devolveu 404 model not found mesmo com chave válida, enquanto a rota /v1/chat/completions respondeu 200. Como o Claude Code fala o formato Anthropic, é preciso um tradutor no meio. O CCR cumpriu esse papel. Vale repetir o teste curl de tempos em tempos, porque isso pode mudar. Veja também nosso conteúdo sobre NVIDIA NIM.
A chave nvapi pode ficar no settings.json?
Não é o caminho recomendado. Guarde a chave em um arquivo local, fora de qualquer pasta versionada, com permissão 600, e carregue como variável de ambiente só no processo do CCR. No settings.json fica apenas a URL do gateway local e o apiKeyHelper, que devolve uma credencial local. Assim, se você compartilhar o arquivo ou fizer um print, a chave da NVIDIA continua protegida. Se vazar, revogue e gere outra no build.nvidia.com. Mais em nossos guias de Claude Code.
Por que o seletor /model não mostra os modelos da NVIDIA?
O seletor do Claude Code filtra por nomes com claude ou anthropic, e os modelos NIM têm outros nomes. Há duas saídas: passar o modelo na linha de comando com --model nim/nvidia/nemotron-3.5-bolt-e4b, ou fixar os modelos por tier nas variáveis ANTHROPIC_DEFAULT_*_MODEL do bloco env. A variável de descoberta de modelos do gateway também ajuda em alguns cenários. Para uso no dia a dia, o mapeamento por tier costuma ser o mais estável.
O que fazer quando aparece unrecognized_model?
Nada, na maioria dos casos. O aviso significa que o Claude Code não conhece o identificador do modelo custom e assume uma janela de contexto de 1 milhão. Ele não impede o funcionamento: os nossos testes com resposta, ferramentas e fallback passaram com o aviso presente. Só investigue se, além do aviso, houver erro de contexto, truncamento de respostas longas ou falha real de requisição. Nesse caso, valide o modelo direto na NVIDIA e revise o roteamento no CCR.
Esse setup serve para o Hermes Agent também?
A ideia é a mesma, mas a ligação é diferente. O Hermes tem provider nvidia nativo e usa base_url no config.yaml, então fala direto com a NVIDIA em formato OpenAI. Já o Claude Code precisa do tradutor Anthropic para OpenAI. Os modelos validados são parecidos, mas a lista depende da conta. Veja o passo a passo do Hermes com modelos NVIDIA e compare as duas abordagens.

{Erros e Soluções}

Estes são os erros que de fato apareceram nos nossos testes entre 14 e 17 de novembro de 2026, com a mensagem como ela surge, a causa técnica e a correção. Se o seu sintoma não estiver aqui, siga a ordem de depuração: gateway, chave, modelo.

404 {"error":{"message":"model not found","type":"not_found_error"},"type":"error"}

Causa: chamada direta ao /v1/messages da NVIDIA; a rota reconhece o formato de erro Anthropic, mas não resolve o modelo para a conta.

Solução: use o CCR (ou outro tradutor) entre o Claude Code e a NVIDIA, e valide o modelo no /v1/chat/completions com curl.

Prevenção: repita o teste direto de vez em vez, porque o suporte da NVIDIA pode mudar.

HTTP 409 ao chamar saveConfig

Causa: o saveConfig foi enviado sem o configRevision devolvido pelo getConfig, ou com uma revisão antiga.

Solução: leia a configuração de novo com getConfig, pegue o configRevision atual e reenvie o saveConfig com ele.

Prevenção: sempre faça getConfig imediatamente antes de salvar e não reaproveite revisões antigas.

401 Invalid JWT

Causa: chave nvapi incorreta ou variável NVIDIA_API_KEY não carregada no processo que fala com a NVIDIA.

Solução: reabra o terminal, confirme que o arquivo local da chave foi carregado e repita o hello world direto no /v1/chat/completions.

Prevenção: carregue a chave sempre do mesmo arquivo com permissão 600, no mesmo ponto de início do wrapper.

404 Function not found for account

Causa: o modelo está no catálogo público, mas não liberado para a sua conta.

Solução: retire o modelo da configuração e dos fallbacks; fique só com os que devolvem 200 com conteúdo no teste hello world.

Prevenção: nunca copie lista de modelos de tutorial sem testar; a sua conta pode enxergar apenas parte do catálogo.

429 Too Many Requests

Causa: limite de requisições por minuto da conta atingido, comum quando subagentes e tarefas de fundo disparam em paralelo.

Solução: espere o minuto virar, reduza a paralelização e confirme que a cadeia de fallback do CCR está ativa para desviar a carga.

Prevenção: use um modelo rápido para haiku e subagentes e mantenha a cadeia curta, de dois modelos.

Claude Code parado na tela inicial, sem erro

Causa: o gateway ou proxy morreu em segundo plano; no nosso caso, o LiteLLM na porta 4000.

Solução: suba o CCR com ccr start --daemon --no-open e confirme a porta 3456; revise se o settings.json não aponta para a porta antiga.

Prevenção: use o wrapper com health-check descrito neste post para que o gateway seja reiniciado antes de cada execução.

Gostou do guia? Veja os testes ao vivo no canal @CanalQb no YouTube e continue no blog.

Conformidade Global: As informações refletem o que foi testado e verificado em 17 e 18 de novembro de 2026. Termos de uso, limites e catálogos de serviços de terceiros mudam. Consulte as autoridades locais de proteção de dados e o IAPP Global Privacy Directory. Este conteúdo não constitui aconselhamento jurídico.

Fontes e Referências

Marcadores: Automação Claude Code Tutorial

© novembro 18, 2026 CanalQb — Python, Scripts, Automação, Airdrops e Criptomoedas | Web3 e Tech na Prática



SEO Dashboard @CanalQb

Carregando dados...

Dados GA4 + Search Console | Atualizar | gerado via API Google