Instalar o ZCode leva minutos e funciona desde a primeira inicialização, porque traz um provedor integrado. O problema aparece quando a chave que você tem pertence a um gateway que serve várias famílias de modelos: o cartão integrado fixa endereço, protocolo e lista de modelos, e nenhum dos três coincide com seu endpoint. O cartão nunca vai reconhecê-lo, por mais vezes que você o edite.
A saída é um provedor personalizado. O formulário tem seis campos, mas apenas quatro decidem se a conexão funciona, e a parte difícil não é preenchê-los mas saber de onde vem cada valor.
Contexto: dois objetos que a interface não junta
Nas configurações, um provedor é um conjunto de parâmetros de conexão mais uma lista de modelos. Uma conversa é apenas um ponteiro para um desses provedores. Estão em telas distintas e não se sincronizam sozinhos: criar um provedor não muda nenhuma conversa aberta.
Essa separação explica as duas falhas mais comuns. Uma é ter escrito o endereço com o path incluído deixando o formato padrão. A outra é ter tudo certo e continuar enviando requisições com o provedor anterior, porque a conversa não mudou de grupo. A segunda não produz nenhuma mensagem de erro, e por isso custa mais.
O que testei e com o quê
Tudo o que segue vem de uma única máquina com Windows 11, a versão do cliente de outubro de 2026 e um único gateway. Os passos de instalação e de interface foram observados diretamente; os limites de contexto, a velocidade e as variantes de modelo são os que publica o editor em seu catálogo, não uma medição própria.
| Elemento | Valor usado |
|---|---|
| Sistema | Windows 11 |
| Cliente | ZCode desktop, interface de outubro de 2026 |
| Modelo de exemplo | glm-5.3 |
| Campos que importam | Base URL, formato de API, API key, ID do modelo |
O cliente é baixado de https://zcode.z.ai/ para Windows, macOS e Linux.
Passo 1: instalação e duas telas
Ao abrir pela primeira vez aparecem duas telas. A primeira pergunta a área de trabalho, com doze opções; a resposta só influencia como o cliente redige suas sugestões. Embaixo à esquerda está「跳过」(omitir). A segunda oferece conectar uma conta: o dropdown aponta ao serviço integrado e embaixo há um campo para sua chave, que não é a sua. Embaixo, 「暂时跳过」(omitir por enquanto).
Nenhuma das duas é configuração. Os provedores são adicionados depois, na mesma janela de configurações, então não precisa voltar atrás.
Passo 2: a chave
ZCode guarda um token do gateway, não a senha da conta. No console do provedor se cria o token, se lhe coloca um nome reconhecível e se copia nesse momento: a maioria dos consoles mostra o valor completo uma única vez.
Os limites, a validade e as permissões por modelo vivem no console. O cliente apenas transporta a chave em cada requisição. A cobrança costuma ser por uso, e as condições vigentes são as que figuram no console no dia que as consultar.
O exemplo usa Crazyrouter; o mapeamento dos quatro campos é o mesmo para qualquer gateway compatível.
Passo 3: criar o provedor
Nas configurações, a coluna esquerda separa o geral (常规, 外观, 模型设置 ou configurações de modelo, 浏览器控制 e outros) do bloco Agent, com memória, subagentes, plugins, servidores MCP, skills, comandos e hooks.
Dentro de「模型设置」se clica em「新增供应商」(adicionar provedor) acima à direita. O painel tem duas metades: acima os cartões integrados, que apenas pedem chave; abaixo, em「其他」, uma lista de provedores habituais cujo primeiro elemento é「创建自定义供应商」(criar provedor personalizado).
A diferença é quem define os parâmetros de conexão. O cartão os traz fixos; o provedor personalizado os pede. Qualquer gateway ou servidor próprio passa por aqui.
Passo 4: os quatro campos
O formulário pede nome, interruptor de ativação, Base URL, formato de API, API key e lista de modelos.
Nome: é apenas a etiqueta da lista. Um como「团队网关」evita confusões ao escolher modelo na conversa.
Base URL: a raiz do gateway, sem path.
https://api.crazyrouter.com
Nem /v1 nem /messages. O endereço e o protocolo são campos distintos, e o path o decide o seletor de formato. Adicioná-lo manualmente é a via mais direta para o 404.
Formato de API: a opção que contém /v1/messages. Decide ao mesmo tempo a rota da requisição e a forma de ler a resposta, então deve coincidir com o que o gateway expõe. Um erro aqui retorna 400 ou 404, nunca 401: a requisição é rejeitada antes de validar a chave. Além disso, /v1/messages e /v1/chat/completions são estruturas distintas; um endereço correto não compensa um formato errado.
API key: o token do passo 2. O ícone do olho serve para verificá-lo: um espaço na frente ou um final cortado dão 401 e parecem uma chave inválida. A chave é salva localmente e não deve acabar em um chat nem em uma captura.
Lista de modelos: se clica em「+ 新增模型」e se cola o ID. Com uma linha basta para começar; as demais compartilham endereço e chave. Cada linha tem seu interruptor: um modelo desativado não aparece no seletor.
Antes de sair, verificar que o interruptor do provedor está ativo. Um formulário sem salvar não cria nada, e esse é outro motivo pelo qual “a configuração não foi aplicada”.
Passo 5: modelos e verificação
Os IDs são copiados, não escritos. No catálogo do console, buscar glm deixa dez resultados entre 170 modelos. Cada cartão tem o link de detalhes e um ícone de copiar à direita; se usa esse ícone e não se muda o uso de maiúsculas.
Um mesmo par endereço + chave pode servir vários modelos: o par escolhe o gateway, o ID escolhe o modelo dentro dele. Adicionar um segundo modelo não requer outra chave nem outro provedor.
Depois de salvar, abrir uma conversa nova, escolher primeiro o grupo do provedor e depois o modelo, e enviar uma instrução curta. Se há resposta, o nome do modelo aparece embaixo à direita da caixa de entrada junto ao nível de raciocínio.
A armadilha principal: a configuração está certa, o modelo responde, mas a requisição continua saindo com o provedor anterior porque a conversa aberta não mudou. É preciso mudar o grupo no seletor inferior; só então a requisição leva sua chave.
Erros e o que significam
-
404: quase sempre um path adicionado à Base URL. Deixar apenas o domínio.
-
400 ou 404: formato incompatível com o gateway. Revisar
/v1/messages, não o endereço. -
401: chave com espaço, cortada ou expirada.
-
O modelo não aparece: interruptor do provedor, interruptor da linha ou formulário sem salvar. Se os três estão certos, sair das configurações e voltar a entrar para recarregar a lista.
-
O modelo funciona mas com a chave antiga: a conversa não mudou de grupo.
Convém lembrar que os três códigos cobrem três causas distintas mas distribuídas de forma pouco intuitiva: dois códigos compartilham dois erros e apenas um é anunciado com clareza.
Modelos
Os nomes da família glm seguem uma gramática: versão e sufixo. flash é o nível econômico, flashx sua versão rápida (cerca de 200 tokens/s), v a visão, ocr a análise de documentos e legal o jurídico.
-
glm-5.3: topo de gama para desenvolvimento completo, contexto 1M e saída 128K. -
glm-5.3-flash: multimodal e mais barato, também 1M/128K. -
glm-5.3-flashx: variante rápida, cerca de 200 tokens/s. -
glm-5.3-flashx-legal: contratos, busca de regulamentação. -
glm-5.2: geração anterior, se não quer tocar em um fluxo que já funciona. -
glm-ocr: imagens de até 10MB, PDF de até 50MB, até 100 páginas. -
glm-5v-turbo: multimodal antigo, limites conforme a ficha.
Os IDs antigos glm-5.1, glm-5, glm-5-turbo e glm-3-turbo continuam funcionando, mas são gerações anteriores. glm-5.3 sempre raciocina e usa três níveis (low, high, max); esse texto junto ao nome do modelo é o nível ativo.
Limites dessa experiência
Não testei macOS nem Linux, então a hierarquia de menus pode variar. Tampouco verifiquei vários gateways ao mesmo tempo: a relação entre códigos de erro e causas pode diferir em outro provedor. Os números de contexto e velocidade são os publicados pelo editor na data indicada, não uma medição independente, e tanto os IDs quanto as janelas de contexto mudam com as versões.
Discussão
Vale a pena o provedor personalizado se você usa apenas um serviço? Provavelmente não: os cartões integrados têm menos campos e menos lugares para errar. Se justifica quando uma única chave deve cobrir vários modelos e a mudança de modelo não deveria implicar mudar de credenciais.
A conclusão prática é que a configuração não termina ao salvar o formulário, mas ao mudar a conversa de grupo. Esse é o único passo que, se omitido, não mostra nenhum erro.