Claude Code com LiteLLM: Guia de Configuração + Quando Usar o TrueFoundry AI Gateway

O Claude Code vem bloqueado por padrão para a API da Anthropic. Isso é ótimo para desenvolvedores individuais, mas no momento em que você tem uma equipe, precisa de controles de custo, visibilidade de uso e acesso a modelos além do catálogo da Anthropic. É exatamente isso que um AI gateway oferece.

O LiteLLM é a opção open-source mais popular para isso. Aponte o Claude Code para um proxy do LiteLLM e você poderá rotear para Bedrock, Vertex AI, Azure OpenAI ou qualquer provedor sem alterar o comportamento do Claude Code no terminal. No entanto, a arquitetura autogerenciada do LiteLLM cria uma sobrecarga real em escala, e suas lacunas de recursos corporativos aparecem rapidamente.

Este guia cobre ambos os caminhos: como configurar o Claude Code com o LiteLLM hoje e quando migrar para o TrueFoundry AI Gateway faz mais sentido para a sua equipe.

Por que conectar o Claude Code a um AI Gateway?

O Claude Code expõe uma única variável de ambiente - ANTHROPIC_BASE_URL que redireciona todo o seu tráfego de API para qualquer endpoint compatível com a API Messages da Anthropic. Defina essa variável com a URL de um gateway e cada requisição feita pelo Claude Code fluirá através da sua infraestrutura em vez de ir diretamente para a api.anthropic.com.

Essa única variável desbloqueia quatro coisas que chaves de API individuais não podem oferecer:

• Visibilidade de custos. Chaves diretas da Anthropic geram gastos invisíveis até que a fatura mensal chegue. Um gateway intercepta cada requisição e oferece atribuição em tempo real por desenvolvedor, por equipe ou por projeto.
• Acesso a múltiplos provedores. Roteie tarefas de nível opus para o melhor modelo de ponta disponível, e tarefas de nível haiku para alternativas mais baratas, sem alterar uma única linha no Claude Code.
• Credenciais centralizadas. Sem chaves de API brutas da Anthropic salvas em arquivos .bash_profile nos notebooks dos desenvolvedores. O gateway armazena as credenciais do provedor; os desenvolvedores se autenticam no gateway com chaves virtuais delimitadas.
• Confiabilidade. Roteamento de fallback automático quando a Anthropic atinge limites de taxa ou sofre uma interrupção. O Claude Code nunca precisa saber que um failover ocorreu.

A questão não é se você deve usar um gateway. É qual deles escolher.

Como o Claude Code se conecta a qualquer Gateway

O mecanismo é o mesmo, independentemente de você estar usando LiteLLM, TrueFoundry ou qualquer outro proxy compatível com a Anthropic. Duas variáveis de ambiente controlam tudo:‍


Para configuração persistente entre sessões, escreva essas variáveis no settings.json do Claude Code:

O arquivo de configurações fica em ~/.claude/settings.json (global do usuário) ou .claude/settings.json na raiz do seu projeto (compartilhado pela equipe). Para implantações em equipe, o arquivo em nível de projeto é a escolha certa — ele garante que cada desenvolvedor no projeto use a mesma configuração de gateway sem necessidade de configuração por máquina.

A partir deste ponto, o Claude Code não tem ideia de que está se comunicando com um gateway em vez da Anthropic diretamente. Tudo — streaming, uso de ferramentas, aliases de modelos, conversas de vários turnos — funciona exatamente como antes.

Configurando o Claude Code com o LiteLLM

O LiteLLM roda como um proxy local ou auto-hospedado que traduz a API Messages da Anthropic para qualquer formato que cada provedor upstream espere. Aqui está a configuração padrão.

Passo 1: Instalar o LiteLLM e Criar sua Configuração

Crie um litellm-config.yaml que defina sua lista de modelos. Uma configuração mínima com Anthropic direta e AWS Bedrock como fallback fica assim:

Exporte suas chaves e inicie o proxy:‍


Passo 2: Apontar o Claude Code para o LiteLLM‍


Ou para uma configuração permanente da equipe no .claude/settings.json:‍


Execute claude no seu terminal. O Claude Code se conecta através do LiteLLM, e o LiteLLM encaminha a requisição para a Anthropic (ou para qualquer provedor que você tenha configurado).

Passo 3: Adicionar Bedrock, Vertex ou Outros Provedores

O principal motivo pelo qual as equipes adicionam o LiteLLM é rotear para o AWS Bedrock (para inferência residente em VPC) ou Google Vertex AI (para fluxos de trabalho nativos da GCP). Adicione provedores à sua lista de modelos:‍


Nota sobre o Bedrock e cabeçalhos experimentais: O Claude Code anexa cabeçalhos experimentais anthropic-beta em cada requisição. O Bedrock não aceita todos eles e pode retornar um erro 400 invalid beta flag. Defina CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 no seu bloco de ambiente ~/.claude/settings.json ao rotear através do Bedrock.

Limitações do LiteLLM em Escala Corporativa

O LiteLLM funciona bem para desenvolvedores individuais e equipes pequenas. À medida que as organizações crescem, várias lacunas se tornam significativas:

Sobrecarga de latência. O LiteLLM adiciona uma sobrecarga de proxy mensurável sob carga concorrente. Para sessões do Claude Code, onde uma única tarefa de codificação gera dezenas de chamadas de API sequenciais — isso se acumula. Em alto RPS, o LiteLLM tem dificuldades sem um dimensionamento horizontal que exige configuração manual no Kubernetes.

Sem RBAC nativo. O sistema de chaves virtuais do LiteLLM é básico. Garantir que a Equipe A só possa acessar modelos do Claude enquanto a Equipe B pode usar qualquer provedor, ou que a chave de um prestador de serviços expire após 30 dias, exige middleware customizado sobre o LiteLLM.

Fardo de infraestrutura autogerenciada. O LiteLLM é open source. Toda atualização, migração de Postgres, configuração de cache no Redis e certificado SSL é de responsabilidade da sua equipe. Para equipes de plataforma que já estão sobrecarregadas, isso se torna um custo de manutenção significativo.

A aplicação de orçamento é limitada. O LiteLLM suporta limites de orçamento por chave, mas limites proativos por desenvolvedor com alertas em tempo real antes que o limite seja atingido exigem ferramentas adicionais.

Lacunas de conformidade. Cargas de trabalho reguladas por SOC 2, HIPAA e GDPR precisam de logs de auditoria, histórico de requisições imutável e controles de residência de dados. Esses recursos não estão embutidos no plano open-source do LiteLLM.

Para equipes que executam o LiteLLM em produção e estão esbarrando nesses limites, o post sobre alternativas ao LiteLLM cobre todo o cenário. A versão resumida: o TrueFoundry AI Gateway foi construído sob medida para o caso de uso corporativo para o qual o LiteLLM nunca foi projetado.

Claude Code com TrueFoundry AI Gateway

O TrueFoundry AI Gateway é um endpoint compatível com Anthropic pronto para uso. O mesmo mecanismo de ANTHROPIC_BASE_URL que conecta o Claude Code ao LiteLLM o conecta ao TrueFoundry — sem alterações no funcionamento do Claude Code, sem novo SDK, sem reescritas no lado do cliente.

A diferença é o que acontece na camada do gateway. O TrueFoundry roda na sua VPC, lida com ~3–4 ms de sobrecarga de gateway a 350+ RPS em um único vCPU e já vem com RBAC, aplicação de orçamento, log de auditoria e roteamento multiprovedor nativos, não como add-ons que exigem configuração personalizada.

Passo 1: Obter a URL do seu TrueFoundry Gateway e a Chave Virtual

Faça login no painel de controle do TrueFoundry. Navegue até AI Gateway → Virtual Keys e crie uma chave delimitada para sua equipe ou projeto. Você receberá:

• Uma URL do painel de controle no formato https://<your-org>.truefoundry.cloud/api/llm/v1
• Uma chave virtual (delimitada a modelos específicos, provedores e limites de orçamento opcionais)

Passo 2: Conectar o Claude Code ao TrueFoundry‍


Para configuração persistente em nível de projeto, adicione ao .claude/settings.json:‍


Execute claude - o Claude Code agora flui através do TrueFoundry. Cada requisição é registrada, atribuída e governada pelas políticas que você definiu nessa chave virtual.

Passo 3: Configurar Provedores e Roteamento de Modelos no Dashboard

Diferente da configuração via arquivo YAML do LiteLLM, a configuração do provedor no TrueFoundry acontece no dashboard do Gateway. Adicione sua conta da Anthropic, conecte credenciais da AWS Bedrock ou Google Vertex e defina aliases de modelos, tudo a partir de uma interface que sua equipe de plataforma gerencia centralmente.

Os aliases de modelos integrados do Claude Code (opus, sonnet, haiku) se mapeiam perfeitamente para os modelos virtuais do TrueFoundry. Configure o mapeamento uma vez no dashboard e cada desenvolvedor usando o .claude/settings.json do projeto obtém o roteamento de modelo correto automaticamente, sem tocar em variáveis de ambiente em máquinas individuais.

O que você desbloqueia: Fluxos de trabalho corporativos com Claude Code

Assim que o Claude Code roteia através do TrueFoundry, cinco recursos se tornam disponíveis que não existem com acesso direto à Anthropic ou LiteLLM básico:

Controle de custos. Defina orçamentos diários de tokens por desenvolvedor ou por equipe diretamente nas chaves virtuais. O gateway aplica limites proativamente - requisições além do orçamento retornam um erro antes de gerarem gastos, em vez de notificar você após a chegada da fatura.

Observabilidade. Cada requisição do Claude Code é rastreada de ponta a ponta: qual desenvolvedor a enviou, qual modelo a processou, quantos tokens foram consumidos, quanto custou. O TrueFoundry é compatível com OpenTelemetry e se integra ao Grafana, Datadog ou Prometheus sem instrumentação adicional.

Segurança e governança. Chaves virtuais substituem chaves de API brutas da Anthropic nas máquinas dos desenvolvedores. Quando um engenheiro sai da organização, você revoga a chave dele em um único lugar. As credenciais subjacentes da Anthropic nunca saem do gerenciador de segredos do gateway. Para empresas que exigem integração do Claude Code com SSO e configurações impostas por MDM, o gateway do TrueFoundry é a camada de aplicação.

Acesso multiprovedor. O Claude Code se comunica com um único endpoint. Por trás desse endpoint, o TrueFoundry roteia para Anthropic direta, AWS Bedrock, Google Vertex AI, Azure OpenAI ou modelos on-premise, com base nas políticas que você definir. Alterne de provedor sem tocar em uma única máquina de desenvolvedor.

Confiabilidade. O roteamento de fallback automático lida com limites de taxa da Anthropic de forma transparente. Se o provedor principal retornar um erro 429 ou 503, o gateway tenta novamente contra um fallback configurado antes que o Claude Code veja um erro. Para fluxos de trabalho de desenvolvedores que não podem sofrer interrupções, essa é a diferença entre um pequeno inconveniente e uma sprint bloqueada.

LiteLLM vs TrueFoundry para Claude Code

O LiteLLM é um excelente proxy para desenvolvedores individuais ou pequenas equipes realizando experimentos. O TrueFoundry é construído para o cenário em que o Claude Code é uma ferramenta para toda a equipe e a equipe de plataforma precisa governá-lo sem ter que construir essa camada de governança do zero.

FAQ

P: Como usar o Claude Code com o LiteLLM?

‍Instale o LiteLLM com pip install litellm[proxy], escreva um litellm-config.yaml definindo seus modelos e inicie o proxy com litellm --config. Em seguida, defina ANTHROPIC_BASE_URL=http://localhost:4000 e ANTHROPIC_AUTH_TOKEN com sua chave mestre do LiteLLM antes de executar o claude. A configuração completa é coberta na seção passo a passo acima.

P: O TrueFoundry é um substituto direto para o LiteLLM com o Claude Code?

‍Sim. O TrueFoundry AI Gateway expõe um endpoint compatível com Anthropic, portanto, migrar do LiteLLM para o TrueFoundry requer apenas uma alteração de uma linha: atualize ANTHROPIC_BASE_URL para a URL do gateway do TrueFoundry e troque o token de autenticação. O Claude Code não nota diferença. O que muda é tudo por trás do gateway — observabilidade, controles de custos, RBAC e infraestrutura gerenciada.

P: Quanta latência o TrueFoundry AI Gateway adiciona às requisições do Claude Code?

‍Aproximadamente ~3–4 ms de sobrecarga de gateway, lidando com 350+ RPS em um único vCPU. Em tempos de resposta do Claude Code (medidos em segundos, não milissegundos), o gateway não adiciona latência perceptível à experiência do desenvolvedor.

P: Posso implantar o TrueFoundry na minha própria VPC ou on-premises?

‍Sim. O TrueFoundry roda na sua VPC, on-premise, air-gapped, híbrido ou em múltiplos provedores de nuvem — nenhum dado sai da sua infraestrutura. Esse é o principal motivo pelo qual empresas reguladas escolhem o TrueFoundry em vez de gateways exclusivamente SaaS ou LiteLLM autogerenciado.

Conclusão

O LiteLLM é um primeiro passo comprovado para conectar o Claude Code a múltiplos provedores de IA. Se você é um desenvolvedor solo ou uma pequena equipe realizando experimentos, é uma escolha sólida que oferece roteamento multiprovedor com poucas linhas de configuração YAML.

Quando o Claude Code se torna uma ferramenta de equipe — quando você precisa aplicar orçamentos, auditar uso, governar acessos e atender a requisitos de conformidade sem construir essa infraestrutura do zero —, a complexidade de configuração e as lacunas de recursos do LiteLLM autogerenciado se tornam um custo real. O TrueFoundry AI Gateway é o endpoint compatível com Anthropic pronto para uso que cuida de tudo isso, com apenas uma alteração de variável de ambiente.

Comece a rotear o Claude Code através do TrueFoundry AI Gateway → truefoundry.com/ai-gateway