Claude Code trava com Zhipu: três causas e três correções

O problema

O cenário é clássico: você acabou de configurar o Claude Code (um assistente de programação de IA) para rodar com a Zhipu (um serviço de modelos de IA) usando o LiteLLM (uma ferramenta que funciona como um “tradutor” para conectar diferentes IAs). Você fez a instalação seguindo o setup do LiteLLM e está empolgado.

Você pede para ele criar um componente React (uma parte da interface de um site). Ele começa a “pensar” e… crash. O programa fecha sozinho, sem dar nenhuma mensagem de erro útil.

Ou pior: ele fica preso em um loop infinito (tentando repetidamente sem parar) mostrando a mensagem "RateLimit exceeded" (um aviso de que você atingiu o limite de requisições permitidas), e a única saída é fechar o processo na força bruta.

Levei umas três sessões de trabalho para perceber que isso não era a Zhipu “sendo um serviço ruim”. Na verdade, eram três erros de configuração distintos que eu estava confundindo como se fossem um problema só. Este artigo é o mapa que eu gostaria de ter recebido: ele separa os três erros, porque a solução de um não resolve os outros.

1. O endpoint errado (a causa mais comum)

Um endpoint é como se fosse o “endereço Web” exato para onde o seu computador envia os pedidos para a API (o sistema da IA). A API da Zhipu tem vários desses endereços, dependendo de como você paga pelo serviço.

Se você assina o Developer (Coding) Plan (um plano mensal) e, no seu arquivo de configurações (config.yaml do LiteLLM), colocou este endereço:

api_base: https://open.bigmodel.cn/api/paas/v4

…o Claude Code vai travar.

Esse endereço acima é o do sistema pay-as-you-go (onde você paga por uso, usando créditos pré-pagos avulsos). Se a sua conta não tem créditos avulsos comprados, a API entende que você está sem saldo ou atinge um RateLimit exceeded contínuo. Como o Claude Code não sabe diferenciar “atingi um limite temporário” de “a configuração de cobrança está errada”, ele fica tentando de novo infinitamente (retry) até fechar sozinho.

A correção é ajustar apenas uma palavra no endereço (URL):

api_base: https://open.bigmodel.cn/api/coding/paas/v4

A inclusão da palavra /coding/ redireciona o seu pedido para os servidores dedicados aos assinantes do plano, ignorando a trava de saldo avulso. Parece um detalhe bobo, mas foi o erro que mais me tomou tempo. Detalhei o motivo completo no artigo sobre cotas e billing.

Como saber se o seu caso é este: se o erro acontece sempre, logo na primeira pergunta que você faz, é um problema de configuração (esta causa 1). Se o erro só acontece depois que você já fez várias perguntas, provavelmente é uma das duas causas abaixo.

2. O crash dos subagentes invisíveis

Esse foi o problema mais interessante de investigar. Imagine que você pede ao Claude Code: “analisa a pasta src/ e muda as cores para azul”.

Para você, parece que fez apenas um pedido. Mas, nos bastidores, não é assim que funciona. O Claude Code “terceiriza” o trabalho criando subagentes (pequenos ajudantes virtuais que rodam em paralelo):

Ele executa o comando ls para listar os arquivos (gastando tokens, que são as “unidades de texto” que a IA consome).
Percebe que precisa ler 5 arquivos e dispara 5 subagentes ao mesmo tempo para ler cada um (gastando ainda mais tokens, tudo no mesmo segundo).

Tudo isso acontece de forma invisível para você — você só vê a resposta final.

O problema ocorre se, no seu arquivo config.yaml, você configurou o modelo desses subagentes (claude-haiku) apontando para um modelo muito “pesado” da Zhipu (como o GLM-4-Plus com Deep Thinking). Nesse caso, você estará disparando 5 tarefas de raciocínio super intensas simultaneamente. Como a Zhipu limita quantas conexões simultâneas uma conta pode fazer, ela rejeita os pedidos por limite de taxa (RateLimit). O Claude Code entra em pânico com as recusas e trava.

A solução é configurar os subagentes para usarem modelos leves, rápidos e baratos:

- model_name: claude-haiku-4-5
  litellm_params:
    model: openai/glm-4-airx   # leve, rápido, limite paralelo alto

Na maioria das vezes, esses ajudantes (subagentes) só fazem tarefas simples e mecânicas — como “ler este arquivo e me devolver o texto”. Eles não precisam de um raciocínio profundo. Usar modelos como GLM-Turbo ou GLM-4-AirX para eles resolve o gargalo de várias requisições ao mesmo tempo (concorrência) sem perder qualidade.

3. Tarefas fantasmas em background

A terceira causa é a mais rara, mas também me pegou. Quando o Claude Code fecha de repente (trava), ele pode deixar “processos órfãos” rodando escondidos no seu sistema — ou seja, tarefas que deveriam ter sido fechadas, mas continuam rodando em segundo plano (background), como instâncias do LiteLLM que não foram encerradas, buscas gigantescas no seu disco ou subagentes travados.

Sintoma: o seu terminal (a tela de comandos) começa a ficar lento ou travando depois do crash, mesmo que você não esteja rodando mais nada. O uso do processador (CPU) dispara e a memória RAM do computador não para de subir.

Como diagnosticar e resolver pelo terminal:

# Procurar por LiteLLM órfãos
ps aux | grep litellm

# Matar o processo se necessário (substitua o PID pelo número do processo)
kill -9 PID

Para quem utiliza o Antigravity (AGY), a própria verificação de tarefas em background da ferramenta faz essa checagem em um único comando.

Como diagnosticar na ordem certa

A ordem da investigação é fundamental, pois cada problema exige um conserto diferente:

O erro acontece logo na primeira tentativa? É o endereço de endpoint incorreto (Causa 1). Corrija a linha api_base.
O erro só acontece depois de várias requisições seguidas? São os subagentes sobrecarregando o sistema (Causa 2). Mapeie o modelo haiku para uma opção mais leve.
O computador ou terminal ficou lento logo após o crash? É uma tarefa fantasma rodando em segundo plano (Causa 3). Finalize os processos órfãos.

Eu perdi bastante tempo tentando resolver tudo como se fosse a Causa 2 quando, na verdade, era a Causa 1 — tudo porque o sintoma visível (a mensagem de erro RateLimit) parecia exatamente o mesmo. O segredo para diferenciar é prestar atenção no momento em que o erro acontece, e não apenas na mensagem de erro na tela.

O que aprendi

A grande lição que fica para além deste caso específico é: três problemas diferentes podem gerar a mesma mensagem de erro, e tentar aplicar a mesma solução para todos é perda de tempo.

Antes de tentar qualquer conserto, eu teria economizado horas se tivesse parado para classificar o comportamento do erro: quando ele aparece? Com qual frequência? Foi logo após qual ação? O Claude Code não vai te dar esse diagnóstico mastigado — você precisa observar o comportamento do sistema.

Esse hábito de “diagnosticar a fundo antes de tentar consertar” virou minha regra padrão para qualquer ferramenta que depende de APIs externas. O sintoma que aparece na tela raramente é a verdadeira causa do problema.