Como usar o Claude Code com a Zhipu AI (GLM-5) via LiteLLM

O problema

Eu queria usar o Claude Code — uma ferramenta incrível da Anthropic para programar usando a CLI (que é a famosa tela preta de comandos do terminal) — mas não queria pagar a assinatura do plano Pro deles. Não é mão de vaca: é que eu já pago uma assinatura para programação na Zhipu AI (uma empresa chinesa que desenvolve os modelos de inteligência artificial chamados GLM), e queria reaproveitar esse crédito que eu já tinha lá. A pergunta era simples: tem como fazer o Claude Code conversar com a Zhipu em vez de falar com a Anthropic?

A resposta curta é sim, mas não de forma direta. O Claude Code fala a “língua” (o formato de API) da Anthropic. Já a Zhipu fala a “língua” da OpenAI. Para fazer dois sistemas que falam línguas diferentes se entenderem, precisamos de um tradutor no meio do caminho — e é exatamente esse o papel do LiteLLM.

Eu levei uma tarde inteira para fazer essa engrenagem funcionar. Não porque o processo seja difícil, mas porque os tutoriais que encontrei na internet pulavam um detalhe técnico crucial: o endereço correto de acesso (o endpoint /api/coding/paas/v4). Eu só descobri que o meu estava errado quando comecei a receber a mensagem de erro RateLimit exceeded (“limite de uso excedido”) do nada. Este artigo é o guia claro e direto que eu gostaria de ter lido antes.

As três peças (e por que precisa das três)

Antes de sairmos instalando coisas, vale a pena entender a função de cada peça nesse quebra-cabeça. Eu pulei essa explicação teórica na minha primeira tentativa e acabei sem saber o que tinha quebrado quando deu errado.

Componente	O que faz	Por que precisa
Claude Code	A CLI da Anthropic — a interface visual no terminal onde você digita	É o “cliente” (o aplicativo); ele nem desconfia que não está falando com a Anthropic
LiteLLM	Proxy local (um tradutor que roda no seu computador) convertendo o formato Anthropic → OpenAI	Sem ele, a Zhipu não consegue entender o que o Claude Code está enviando
Zhipu AI (GLM-5)	O modelo de Inteligência Artificial que realmente processa os pedidos	É o “cérebro”; é por ele que você está pagando, e não para a Anthropic

O caminho completo da informação funciona assim:

Você → Claude Code → LiteLLM (localhost:4001) → API da Zhipu → GLM-5

O Claude Code acha que está conversando diretamente com os servidores da Anthropic. O LiteLLM intercepta a conversa, traduz as mensagens nos bastidores e as repassa para a Zhipu. A Zhipu responde, o LiteLLM traduz a resposta de volta e o Claude Code a mostra na sua tela. No fim, o sistema funciona perfeitamente sem que um saiba da “gambiarra” do outro.

Pré-requisitos

• Uma conta na Zhipu AI com o plano Developer (Coding) Plan ativo (precisa ser este plano específico, e não o pagamento por uso comum pay-as-you-go — isso fará toda a diferença mais para frente)
• Node.js versão 22 ou superior instalado (ambiente para rodar programas em JavaScript)
• Python versão 3.8 ou superior com o gerenciador pip instalado

1. Instalar o Claude Code

Vamos instalar a ferramenta do Claude no terminal de forma global (disponível em qualquer pasta):

npm install -g @anthropic-ai/claude-code

Depois que a instalação terminar, confirme se o seu sistema operacional consegue encontrar o comando (se ele está no seu PATH):

claude --version

2. Instalar o LiteLLM

Agora vamos instalar o LiteLLM com o recurso de proxy:

pip install 'litellm[proxy]'

O LiteLLM funciona como um “proxy”, ou seja, um pequeno servidor que roda localmente na sua máquina. Ele lê um arquivo de configuração no qual ensinamos: “quando pedirem tal modelo da Anthropic, substitua pelo modelo equivalente do outro provedor”. É essa regra de tradução que faz a mágica acontecer.

3. Criar o arquivo de configuração do LiteLLM

Primeiro, crie a pasta onde o arquivo vai ficar:

mkdir -p ~/claude-gemini

Agora crie o arquivo de texto ~/claude-gemini/config.yaml. Ele é o coração de toda a configuração:

model_list:
  # Modelo principal (claude-sonnet → GLM-5.0)
  - model_name: claude-sonnet-4-5
    litellm_params:
      model: openai/glm-4-flash
      api_base: https://open.bigmodel.cn/api/coding/paas/v4
      api_key: os.environ/ZHIPU_API_KEY

  # Modelo pesado (claude-opus → GLM-5.1)
  - model_name: claude-opus-4-5
    litellm_params:
      model: openai/glm-4-plus
      api_base: https://open.bigmodel.cn/api/coding/paas/v4
      api_key: os.environ/ZHIPU_API_KEY

  # Modelo leve para subagentes (claude-haiku → GLM-Turbo)
  - model_name: claude-haiku-4-5
    litellm_params:
      model: openai/glm-4-airx
      api_base: https://open.bigmodel.cn/api/coding/paas/v4
      api_key: os.environ/ZHIPU_API_KEY

litellm_settings:
  drop_params: true

Repare no papel deste arquivo: ele instrui o LiteLLM dizendo “toda vez que chegar um pedido para o claude-sonnet-4-5, redirecione para o glm-4-flash da Zhipu”. O Claude Code pede o modelo claude-sonnet achando que ele existe ali; o LiteLLM faz a ponte e entrega o modelo da Zhipu.

O detalhe técnico que me custou uma tarde inteira: a linha api_base precisa terminar obrigatoriamente em /api/coding/paas/v4, e NÃO em /api/paas/v4 (que é o endereço padrão que aparece na documentação geral da Zhipu). O trecho /coding/ é a porta de entrada exclusiva para quem assina o plano Developer. Se você esquecer essa palavra, vai acessar o plano errado e esgotar toda a sua cota em poucos minutos. Foi exatamente esse erro que cometi.

4. Configurar o .bashrc

Em vez de abrir o servidor tradutor manualmente toda vez, a ideia aqui é criar um único comando personalizado, o claude-glm. Ele vai: ligar o LiteLLM em segundo plano, abrir o Claude Code apontando para ele e, quando você fechar a ferramenta, desligar o LiteLLM sozinho.

Abra o arquivo de configurações do seu terminal (~/.bashrc) e adicione as seguintes linhas no final dele:

# Chave da API Zhipu (pegue em bigmodel.cn → API Keys)
export ZHIPU_API_KEY="sua_chave_aqui"

# Comando para iniciar o LiteLLM + Claude Code
claude-glm() {
  local LITELLM_PID
  litellm --config ~/claude-gemini/config.yaml --port 4001 &>/dev/null &
  LITELLM_PID=$!
  sleep 2

  ANTHROPIC_BASE_URL=http://localhost:4001 \
  ANTHROPIC_API_KEY=fake-key \
  claude "$@"

  kill $LITELLM_PID 2>/dev/null
}

Para fazer o terminal carregar essas novas regras imediatamente, execute:

source ~/.bashrc

5. Testar

Agora é só rodar o novo comando que criamos:

claude-glm

Se tudo deu certo, a interface do Claude Code vai abrir normalmente na sua tela. Todas as perguntas e comandos que você digitar passarão pelo LiteLLM e serão respondidos pela Zhipu — sem gastar absolutamente nenhum centavo na Anthropic.

Por que usamos ANTHROPIC_API_KEY=fake-key?

Essa etapa me deixou meio confuso no início. Acontece que o Claude Code exige que a variável de senha da Anthropic esteja preenchida com qualquer coisa para sequer aceitar inicializar — é uma checagem simples do próprio aplicativo. Mas, como o nosso tradutor (LiteLLM) está interceptando todo o tráfego, a única chave de acesso real que importa é a ZHIPU_API_KEY. O valor fake-key serve apenas como um “passe livre falso” para enganar a validação inicial. Ele nunca é enviado para a internet.

Os erros que eu cometi (pra você não cometer)

Erro: “RateLimit exceeded” logo no início.
Aconteceu porque eu estava usando a URL /api/paas/v4 (sem o termo /coding/). Esse endereço cobrava a minha conta como se fosse o plano comum (pago por uso), que possui limites de requisições extremamente baixos. A solução foi ajustar o endereço para /api/coding/paas/v4. Explico todo o diagnóstico desse problema no artigo sobre cotas e billing.

Erro: o Claude Code abre, mas fica travado sem responder.
Significa que o tradutor LiteLLM não conseguiu ser iniciado em segundo plano. Para testar se ele está rodando na sua máquina, digite:

curl http://localhost:4001/health

Se não houver resposta, revise o caminho do arquivo config.yaml e confirme se a sua chave ZHIPU_API_KEY foi carregada no ambiente (rode echo $ZHIPU_API_KEY no terminal para verificar se o código da sua chave aparece na tela).

Erro: “O modelo Fable/Haiku não aparece na lista.”
Isso ocorre porque o comando claude-glm roda em um ambiente isolado do claude original. A lista de modelos que ele exibe depende exclusivamente do que foi mapeado no arquivo config.yaml. Se você configurou apenas o claude-sonnet, somente ele estará disponível. Quer ver mais modelos? Adicione novas linhas na seção model_list.

Demora para iniciar.
Isso é normal — o servidor do LiteLLM leva cerca de 2 segundos para subir totalmente e ficar pronto. A instrução sleep 2 dentro do nosso script serve justamente para dar esse tempo de espera. Se o seu computador for mais antigo ou lento, vale aumentar essa linha para sleep 3.

O que aprendi

A grande lição técnica que fica para qualquer projeto é: a documentação genérica de um sistema nem sempre é a documentação aplicável ao seu caso. A Zhipu possui dois endereços de API praticamente iguais: um para o público geral e outro dedicado a desenvolvedores de código. A única diferença entre eles é uma simples palavra no meio do link. Nenhum tutorial da internet explicava isso — só descobri lendo os logs de erro e cruzando dados com o painel da minha conta.

Quando uma API estourar o limite de uso rápido demais ou falhar sem um motivo óbvio, a primeira coisa a checar é: o seu código está conversando exatamente com o endereço (endpoint) correto para a sua conta? Criar esse hábito me salvou horas de trabalho em várias outras APIs desde então.

---

Continua no próximo artigo: LiteLLM — o tradutor invisível, onde explico em detalhes a arquitetura interna do proxy e como o modo de raciocínio (“Thinking Mode”) do Claude Code é traduzido.

Leia também

• Modelos em julho de 2026: GLM-5, DeepSeek V4 e o que vem aí
• Perdi minha chave da Zhipu na migração da VM?
• Os 10 maiores modelos open-source em parâmetros