Instalar ZCode lleva minutos y funciona desde el primer arranque, porque trae un proveedor integrado. El problema aparece cuando la clave que tienes pertenece a una pasarela que sirve varias familias de modelos: la tarjeta integrada fija dirección, protocolo y lista de modelos, y ninguno de los tres coincide con tu endpoint. La tarjeta nunca lo va a reconocer, por muchas veces que la edites.
La salida es un proveedor personalizado. El formulario tiene seis campos, pero solo cuatro deciden si la conexión funciona, y la parte difícil no es rellenarlos sino saber de dónde sale cada valor.
Contexto: dos objetos que la interfaz no junta
En los ajustes, un proveedor es un conjunto de parámetros de conexión más una lista de modelos. Una conversación es solo un puntero a uno de esos proveedores. Están en pantallas distintas y no se sincronizan solos: crear un proveedor no cambia ninguna conversación abierta.
Esa separación explica las dos fallas más comunes. Una es haber escrito la dirección con el path incluido dejando el formato por defecto. La otra es tener todo bien y seguir enviando peticiones con el proveedor anterior, porque la conversación no se cambió de grupo. La segunda no produce ningún mensaje de error, y por eso cuesta más.
Qué probé y con qué
Todo lo que sigue viene de una sola máquina con Windows 11, la versión del cliente de octubre de 2026 y una sola pasarela. Los pasos de instalación y de interfaz se observaron directamente; los límites de contexto, la velocidad y las variantes de modelo son los que publica el editor en su catálogo, no una medición propia.
| Elemento | Valor usado |
|---|---|
| Sistema | Windows 11 |
| Cliente | ZCode desktop, interfaz de octubre de 2026 |
| Modelo de ejemplo | glm-5.3 |
| Campos que importan | Base URL, formato de API, API key, ID de modelo |
El cliente se descarga desde https://zcode.z.ai/ para Windows, macOS y Linux.
Paso 1: instalación y dos pantallas
Al abrir por primera vez aparecen dos pantallas. La primera pregunta el área de trabajo, con doce opciones; la respuesta solo influye en cómo el cliente redacta sus sugerencias. Abajo a la izquierda está「跳过」(omitir). La segunda ofrece conectar una cuenta: el desplegable apunta al servicio integrado y debajo hay un campo para su clave, que no es la tuya. Abajo, 「暂时跳过」(omitir por ahora).
Ninguna de las dos es configuración. Los proveedores se añaden después, en la misma ventana de ajustes, así que no hay que volver atrás.
Paso 2: la clave
ZCode guarda un token de la pasarela, no la contraseña de la cuenta. En la consola del proveedor se crea el token, se le pone un nombre reconocible y se copia en ese momento: la mayoría de consolas muestra el valor completo una sola vez.
Los límites, la caducidad y los permisos por modelo viven en la consola. El cliente solo transporta la clave en cada petición. El cobro suele ser por uso, y las condiciones vigentes son las que figuren en la consola el día que las consultes.
El ejemplo usa Crazyrouter; el mapeo de los cuatro campos es el mismo para cualquier pasarela compatible.
Paso 3: crear el proveedor
En ajustes, la columna izquierda separa lo general (常规, 外观, 模型设置 o ajustes de modelo, 浏览器控制 y otros) del bloque Agent, con memoria, subagentes, plugins, servidores MCP, skills, comandos y hooks.
Dentro de「模型设置」se pulsa「新增供应商」(añadir proveedor) arriba a la derecha. El panel tiene dos mitades: arriba las tarjetas integradas, que solo piden clave; abajo, en「其他」, una lista de proveedores habituales cuyo primer elemento es「创建自定义供应商」(crear proveedor personalizado).
La diferencia es quién define los parámetros de conexión. La tarjeta los trae fijos; el proveedor personalizado los pide. Cualquier pasarela o servidor propio pasa por aquí.
Paso 4: los cuatro campos
El formulario pide nombre, interruptor de activación, Base URL, formato de API, API key y lista de modelos.
Nombre: solo es la etiqueta de la lista. Uno como「团队网关」evita confusiones al elegir modelo en la conversación.
Base URL: la raíz de la pasarela, sin path.
https://api.crazyrouter.com
Ni /v1 ni /messages. La dirección y el protocolo son campos distintos, y el path lo decide el selector de formato. Añadirlo a mano es la vía más directa al 404.
Formato de API: la opción que contiene /v1/messages. Decide a la vez la ruta de la petición y la forma de leer la respuesta, así que debe coincidir con lo que la pasarela expone. Un error aquí devuelve 400 o 404, nunca 401: la petición se rechaza antes de validar la clave. Además /v1/messages y /v1/chat/completions son estructuras distintas; una dirección correcta no compensa un formato equivocado.
API key: el token del paso 2. El icono del ojo sirve para comprobarlo: un espacio delante o un final cortado dan 401 y parecen una clave inválida. La clave se guarda en local y no debe acabar en un chat ni en una captura.
Lista de modelos: se pulsa「+ 新增模型」y se pega el ID. Con una línea basta para empezar; las demás comparten dirección y clave. Cada línea tiene su interruptor: un modelo desactivado no aparece en el selector.
Antes de salir, comprobar que el interruptor del proveedor está activo. Un formulario sin guardar no crea nada, y ese es otro motivo por el que «la configuración no se aplicó».
Paso 5: modelos y verificación
Los ID se copian, no se escriben. En el catálogo de la consola, buscar glm deja diez resultados entre 170 modelos. Cada tarjeta tiene el enlace de detalles y un icono de copiar a la derecha; se usa ese icono y no se cambia el uso de mayúsculas.
Un mismo par dirección + clave puede servir varios modelos: la pareja elige la pasarela, el ID elige el modelo dentro de ella. Añadir un segundo modelo no requiere otra clave ni otro proveedor.
Después de guardar, abrir una conversación nueva, elegir primero el grupo del proveedor y luego el modelo, y enviar una instrucción corta. Si hay respuesta, el nombre del modelo aparece abajo a la derecha del cuadro de entrada junto al nivel de razonamiento.
La trampa principal: la configuración está bien, el modelo responde, pero la petición sigue saliendo con el proveedor anterior porque la conversación abierta no se cambió. Hay que cambiar el grupo en el selector inferior; solo entonces la petición lleva tu clave.
Errores y qué significan
-
404: casi siempre un path añadido a la Base URL. Dejar solo el dominio.
-
400 o 404: formato incompatible con la pasarela. Revisar
/v1/messages, no la dirección. -
401: clave con espacio, cortada o caducada.
-
El modelo no aparece: interruptor del proveedor, interruptor de la línea o formulario sin guardar. Si los tres están bien, salir de ajustes y volver a entrar para recargar la lista.
-
El modelo funciona pero con la clave vieja: la conversación no se cambió de grupo.
Conviene recordar que los tres códigos cubren tres causas distintas pero repartidas de forma poco intuitiva: dos códigos comparten dos errores y solo uno se anuncia con claridad.
Modelos
Los nombres de la familia glm siguen una gramática: versión y sufijo. flash es el nivel económico, flashx su versión rápida (unos 200 tokens/s), v la visión, ocr el análisis de documentos y legal lo jurídico.
-
glm-5.3: tope de gama para desarrollo complejo, contexto 1M y salida 128K. -
glm-5.3-flash: multimodal y más barato, también 1M/128K. -
glm-5.3-flashx: variante rápida, alrededor de 200 tokens/s. -
glm-5.3-flashx-legal: contratos, búsqueda de normativa. -
glm-5.2: generación anterior, si no quieres tocar un flujo que ya funciona. -
glm-ocr: imágenes de hasta 10MB, PDF de hasta 50MB, hasta 100 páginas. -
glm-5v-turbo: multimodal antiguo, límites según la ficha.
Los ID antiguos glm-5.1, glm-5, glm-5-turbo y glm-3-turbo siguen funcionando, pero son generaciones previas. glm-5.3 siempre razona y usa tres niveles (low, high, max); ese texto junto al nombre del modelo es el nivel activo.
Límites de esta experiencia
No probé macOS ni Linux, así que la jerarquía de menús puede variar. Tampoco verifiqué varias pasarelas a la vez: la relación entre códigos de error y causas puede diferir en otro proveedor. Los números de contexto y velocidad son los publicados por el editor en la fecha indicada, no una medición independiente, y tanto los ID como las ventanas de contexto cambian con las versiones.
Discusión
¿Merece la pena el proveedor personalizado si solo usas un servicio? Probablemente no: las tarjetas integradas tienen menos campos y menos lugares donde equivocarse. Se justifica cuando una sola clave debe cubrir varios modelos y el cambio de modelo no debería implicar cambiar de credenciales.
La conclusión práctica es que la configuración no termina al guardar el formulario, sino al cambiar la conversación de grupo. Ese es el único paso que, si se omite, no muestra ningún error.