Integración de Zhipu GLM: los dos endpoints de Z.AI y el Coding Plan
OpenClaw con GLM (Zhipu) es la tercera parada de la página dedicada a modelos nacionales. En las dos lecciones anteriores, DeepSeek funcionó con una sola variable de entorno y Qwen hizo una elección entre tres; la pregunta de GLM es aún más sencilla: General API o Coding Plan, multiplicada una vez más por el sitio internacional api.z.ai o el sitio nacional open.bigmodel.cn. Si eliges el endpoint equivocado, la Key será rechazada y el modelo predeterminado tampoco coincidirá. Todo el proceso toma unos 8 minutos (el registro en Z.AI no está incluido).
Primero, aquí tienes una tabla de vista rápida; toda la configuración de esta lección parte de ella (propiedades y valores tomados textualmente de la documentación oficial):
| Propiedad | Valor |
|---|---|
| Provider id | zai |
| Variable de entorno de autenticación | ZAI_API_KEY (el alias antiguo Z_AI_API_KEY sigue aceptándose y se copia automáticamente al iniciar) |
| Forma de la API | Z.AI Chat Completions (autenticación Bearer) |
| Plugin oficial | @openclaw/zai-provider (plugin externo, requiere instalación) |
| Modelo predeterminado | Coding Plan: zai/glm-5.3; General API: zai/glm-5.2 |
| Consola de gestión de Key | https://z.ai/manage-apikey/apikey-list |
Algo que debes saber primero: GLM es una familia de modelos, no un provider independiente (textual de la documentación oficial: "GLM is a model family, not a separate provider"). Las referencias a los modelos siempre empiezan por zai/, como zai/glm-5.3: el provider es zai y el id del modelo es glm-5.3.
Cuatro endpoints; toda la lección se basa en esta tabla (auth-choice y endpoints tomados textualmente de la documentación oficial):
| Uso | auth-choice | Base URL | Modelo predeterminado |
|---|---|---|---|
| General API · sitio internacional | zai-global | https://api.z.ai/api/paas/v4 | glm-5.2 |
| General API · sitio nacional | zai-cn | https://open.bigmodel.cn/api/paas/v4 | glm-5.2 |
| Coding Plan · sitio internacional | zai-coding-global | https://api.z.ai/api/coding/paas/v4 | glm-5.3 |
| Coding Plan · sitio nacional | zai-coding-cn | https://open.bigmodel.cn/api/coding/paas/v4 | glm-5.3 |
Cómo elegir, en tres frases:
| Tu situación | Elige esto |
|---|---|
| Tienes una suscripción a GLM Coding Plan (cuota mensual para programar) | zai-coding-global / zai-coding-cn, con modelo predeterminado directamente glm-5.3 |
| Pago por uso (pay-as-you-go) | zai-global / zai-cn, con modelo predeterminado glm-5.2 |
| No estás seguro de qué endpoint puede usar esta Key | zai-api-key: OpenClaw prueba los endpoints uno a uno con la Key y usa el primero que la acepte |
Dos datos adicionales que se usarán más adelante en la resolución de problemas:
- Z.AI tiene además otro endpoint de Coding Plan compatible con Anthropic,
https://api.z.ai/api/anthropic: está pensado para clientes que hablan directamente el formato Anthropic Messages; la opción zai de OpenClaw no lo utiliza, sino que usa el endpoint OpenAI Chat Completions de la tabla anterior. - En el endpoint de Coding Plan, las solicitudes de GLM-5.2 / GLM-5.1 son enrutadas por Z.AI a GLM-5.3.
💡 Para quienes llegan buscando desde «智谱清言»
«智谱清言» es el producto de chat de Zhipu orientado a usuarios comunes; OpenClaw no necesita esa entrada de chat, sino la API Key del modelo GLM——obtenla desde la consola de Z.AI (sitio internacional) o open.bigmodel.cn (región de China). Esta página solo trata la integración de la API.
Este tutorial se basa en OpenClaw v2026.10.9.
Qué podrás hacer al terminar
- Instalar el complemento oficial de GLM
@openclaw/zai-providery configurarZAI_API_KEYen OpenClaw——elige entre tres rutas: detección automática, endpoint explícito o configuración manual - Distinguir los dos endpoints, General API y Coding Plan, × las dos regiones, China / internacional, y elegir el auth-choice correcto según tu Key
- Entender el catálogo integrado de GLM: la posición de cada uno de
glm-5.3,glm-5.3-flash,glm-5.2, y por quéglm-5.1ya no debe usarse - Mantener la calma al encontrar
429/1302/1305en horas pico: distinguir entre «limitación temporal» y «endpoint mal configurado» - Aprovechar las capacidades exclusivas de GLM: niveles de razonamiento
/think, generación de videocogvideox-3, comprensión de imágenesglm-4.6v
🎒 Preparativos antes de empezar
- Has completado Conexión de modelos: panorama general: el sistema de providers y el cambio de modelo: tienes claros los tres pasos «instalar complemento → configurar credenciales → elegir modelo» y las reglas de referencia de
provider/model - OpenClaw está instalado y el Gateway está en ejecución:
openclaw gateway statusproduce salida (el complemento surte efecto automáticamente en un Gateway en ejecución; si no está corriendo, surte efecto en el próximo inicio) - Sabes si tu Key es de Coding Plan o de pago por uso, y si fue emitida por el sitio de China o el internacional
- Si optas por un despliegue en servidor / demonio, sabes dónde está
~/.openclaw/.env——la Key terminará viviendo ahí
Hazlo conmigo
Paso 1: crear una API Key en la consola de Z.AI
Por qué: OpenClaw solo se encarga de las llamadas; la Key debe obtenerse primero del lado de Z.AI — y además el tipo de tu cuenta (suscripción / pago por uso) determina qué endpoint elegir en el paso 2.
- Abre en el navegador la consola de Z.AI
https://z.ai/manage-apikey/apikey-list, regístrate / inicia sesión - Crea una API Key, cópiala y pégala en un lugar seguro
- Usuarios de China: la plataforma de la región de China es
open.bigmodel.cn; las cuentas de China gestionan sus Keys en su propia consola (la documentación de OpenClaw solo ofrece el enlace directo a la consola del sitio internacional; para el sitio de China, entra al sitio oficial deopen.bigmodel.cny busca la página de gestión de API Keys)
Deberías ver: una API Key copiable. ¿No estás seguro del tipo de cuenta? Echa un vistazo a tu plan actual en la página de suscripción https://z.ai/subscribe.
Paso 2: conectar OpenClaw con GLM——primero instala el complemento, luego configura ZAI_API_KEY
Por qué: zai, al igual que DeepSeek y Qwen, es un complemento oficial externo (no viene integrado en el núcleo), lo que añade un paso de «instalación» respecto a los complementos integrados; una vez instalado, el auth-choice determina qué endpoint se utiliza.
Primero instala el complemento (primer paso común a ambas formas):
openclaw plugins install @openclaw/zai-providerDeberías ver: instalación exitosa. Surte efecto automáticamente en un Gateway en ejecución; si el Gateway no está corriendo, surte efecto en el próximo inicio.
Forma A (recomendada): guía de onboarding
Lo más cómodo es la detección automática——OpenClaw prueba los endpoints uno por uno con tu Key:
openclaw onboard --auth-choice zai-api-keyOrden de detección (tal como figura en la documentación oficial): primero prueba los endpoints General (zai-global → zai-cn), luego los endpoints de Coding Plan (zai-coding-global → zai-coding-cn), se usa el primero que acepte la solicitud.
Para forzar un endpoint concreto (a los usuarios de Coding Plan se les recomienda elegirlo explícitamente; el motivo está en el aviso de errores comunes):
# Coding Plan · 国际站 / 国内站(Coding Plan 用户推荐)
openclaw onboard --auth-choice zai-coding-global
openclaw onboard --auth-choice zai-coding-cn
# General API · 国际站 / 国内站
openclaw onboard --auth-choice zai-global
openclaw onboard --auth-choice zai-cnDeberías ver: primero pide introducir la API Key, la valida y guarda las credenciales; el modelo predeterminado se posiciona según el endpoint——Coding Plan es zai/glm-5.3, General API es zai/glm-5.2.
Tres garantías (la documentación oficial lo indica explícitamente):
- el onboarding conserva tus entradas de modelo existentes——re-ejecutarlo no borra la configuración de otros providers
- añadir credenciales de un nuevo provider no cambia tu modelo predeterminado actual——para cambiarlo, usa el
openclaw models setdel paso 3 - la antigua variable de entorno
Z_AI_API_KEYsigue siendo válida: si al iniciarZAI_API_KEYno está definida, OpenClaw la copia automáticamente
Forma B: editar manualmente el archivo de configuración
El complemento oficial en principio no necesita entradas models.providers——basta con instalar el complemento, configurar el auth y elegir el modelo; solo se escribe si hay que sobrescribir el baseUrl predeterminado (por ejemplo, fijar manualmente el endpoint de Coding Plan o del sitio de China). Ejemplo de configuración oficial (tal cual):
{
env: { vars: { ZAI_API_KEY: "sk-..." } },
models: {
providers: {
zai: {
// GLM-5.3 uses the Coding Plan endpoint.
baseUrl: "https://api.z.ai/api/coding/paas/v4",
},
},
},
agents: { defaults: { model: { primary: "zai/glm-5.3" } } },
}Sustituye el baseUrl según lo que necesites (con la tabla de cuatro endpoints de arriba):
| Qué endpoint quieres usar | Qué escribir en baseUrl |
|---|---|
| Coding Plan · sitio internacional | https://api.z.ai/api/coding/paas/v4 |
| Coding Plan · sitio de China | https://open.bigmodel.cn/api/coding/paas/v4 |
| General API · sitio internacional | https://api.z.ai/api/paas/v4 |
| General API · sitio de China | https://open.bigmodel.cn/api/paas/v4 |
Dónde poner la Key: en un shell interactivo con export ZAI_API_KEY="<你的 API Key>", o escríbela en ~/.openclaw/.env (los despliegues como demonio deben pasar por aquí; ver la advertencia de abajo).
⚠️ ¿El Gateway corre como demonio? No pongas la Key en el shell interactivo
Cuando el Gateway se ejecuta como servicio de launchd / systemd, no ve las variables de entorno que definiste con export en tu terminal. Escribe ZAI_API_KEY en ~/.openclaw/.env, o proporciónasela a ese proceso mediante env.shellEnv en la configuración.
- En el resumen de credenciales de
openclaw models status, en la línea de zai se puede ver el origen deZAI_API_KEY
Paso 3: elegir un modelo GLM y validar
Por qué: el modelo predeterminado se posiciona según el endpoint (Coding Plan → glm-5.3, General → glm-5.2); si te sirve, primero hazlo funcionar; pero los seis modelos del catálogo tienen funciones distintas, échales un vistazo antes de decidir.
Primero mira el catálogo:
openclaw models list --all --provider zaiDeberías ver: el catálogo GLM integrado en el manifiesto del complemento (extracto tal cual de la documentación oficial; este catálogo va con el manifest del complemento, una lista de solo lectura que no requiere cargar el runtime del provider):
| Referencia del modelo | Contexto | Notas |
|---|---|---|
zai/glm-5.3 | 1,048,576 | Predeterminado en Coding Plan |
zai/glm-5.3-flash | 1,048,576 | Multimodal (texto + imagen) |
zai/glm-5.2 | 1M | Predeterminado en General API |
zai/glm-5-turbo | 200K | Modelo de texto optimizado de OpenClaw |
zai/glm-5v-turbo | 200K | Modelo de coding multimodal |
zai/glm-5.1 | — | Obsoleto; no se muestra si no está configurado; la recomendación oficial es usar GLM-5.2 |
El comportamiento de los tres catálogos está claro en la Note oficial:
- Las configuraciones nuevas de Coding Plan tienen
zai/glm-5.3como predeterminado; las configuraciones de General API se quedan enzai/glm-5.2 - En los endpoints de Coding Plan, cuando la Key o el endpoint regional no exponen directamente GLM-5.3, la detección automática hace fallback siguiendo
glm-5.1,glm-4.7 - Cuando Coding Plan recibe una solicitud de GLM-5.2 / GLM-5.1, Z.AI la enruta a GLM-5.3
Cómo elegir, en tres frases:
| Tu necesidad | Elígelo | Según |
|---|---|---|
| Usuario de Coding Plan, no sabes qué elegir | zai/glm-5.3 | Predeterminado oficial, contexto de 1M |
| Quieres que el modelo vea imágenes | zai/glm-5.3-flash (1M) / zai/glm-5v-turbo (200K) | Marcados como multimodales en el directorio |
| Pago por uso, y quieres poder desactivar el razonamiento por completo | zai/glm-5.2 | thinking con off como predeterminado y soporta el nivel off (GLM-5.3 no se puede desactivar, ver capacidades exclusivas) |
Cambiar el modelo predeterminado:
openclaw models set zai/glm-5.3También puedes cambiarlo temporalmente en el chat: /model zai/glm-5.2 solo afecta a la sesión actual; para la familia de comandos, consulta Guía rápida de comandos de chat.
Verificación final — envía un mensaje de prueba:
openclaw agent --agent main --model zai/glm-5.3 --message "用一句话介绍你自己"(openclaw agent requiere al menos un selector de sesión; --agent main apunta al agent predeterminado — en instalaciones con onboarding completado existe por defecto main; o ejecuta openclaw dashboard para abrir la Control UI y enviarlo directamente en el cuadro de chat.)
Deberías ver: el modelo responde con normalidad, sin errores de credenciales faltantes o modelo inexistente. Con esto, la integración de OpenClaw con GLM queda funcionando.
El precio en una frase: GLM-5.3 es actualmente un modelo de Coding Plan, con cost cero en el directorio local — la suscripción usa la cuota del plan, sin facturación por token; el directorio de pago por uso sigue la tarifa actual de la API de Z.AI, y GLM-5.3 Flash usa el precio del directorio de pago por uso (los descuentos temporales no afectan el precio del directorio). Los precios y la disponibilidad de los planes se rigen por la página de suscripción de Z.AI https://z.ai/subscribe.
- El mensaje de prueba recibió una respuesta de GLM
Punto de control ✅
openclaw plugins install @openclaw/zai-providerejecutado, el plugin está en la lista- auth-choice (o baseUrl) coincide con tu tipo de Key y región: la Key de Coding Plan va al endpoint coding, la Key de pago por uso va al endpoint general
- En el resumen de credenciales de
openclaw models statusse puede ver elZAI_API_KEYde zai openclaw models list --all --provider zailista los modelos de la serie GLM- Tras enviar el mensaje de prueba se recibió una respuesta de GLM
- No se ha configurado
zai/glm-5.1como predeterminado (obsoleto)
Aviso de errores comunes
❌ La Key de Coding Plan se configuró en el endpoint General (o al revés)
Causa: la guía oficial de resolución de problemas lo dice sin rodeos — la Key de Coding Plan debe usarse con el endpoint de Coding Plan (como https://api.z.ai/api/coding/paas/v4), y la Key de General API con el endpoint General (como https://api.z.ai/api/paas/v4). Si la misma Key + el mismo endpoint fallan de forma persistente, es más probable un rechazo del lado del provider o una restricción del plan, no una limitación normal por hora pico.
Solución correcta: revisa primero el endpoint, luego lo demás:
openclaw models list --all --provider zai
openclaw config get models.providers.zai.baseUrlSi el endpoint no es el correcto, vuelve a ejecutar onboard y elige auth-choice explícitamente, o edita manualmente models.providers.zai.baseUrl.
❌ La Key funciona en ambos lados, pero la detección automática acabó en General
Causa: el orden de detección de zai-api-key es primero General (zai-global → zai-cn) y luego Coding Plan (zai-coding-global → zai-coding-cn); usa el primero que acepte. Si la Key es válida en ambos tipos de endpoint, se asigna a General — el modelo predeterminado pasa a ser glm-5.2 en lugar de glm-5.3.
Solución correcta: la misma indicación oficial — cuando la Key funciona en ambos lados, si quieres usar Coding Plan especifícalo explícitamente:
openclaw onboard --auth-choice zai-coding-global # 国际站
openclaw onboard --auth-choice zai-coding-cn # 国内站❌ En horas pico aparecen errores 429 / 1305 y crees que la configuración se rompió
Causa: Z.AI oficialmente clasifica las herramientas de agent de uso general (incluida OpenClaw) como servicio de capacidad gestionada, best-effort — en periodos de alta carga de inferencia (según la versión oficial: aproximadamente de las 2–6 de la tarde, hora de Singapur) algunas solicitudes se limitan temporalmente; los límites de velocidad y concurrencia de Coding Plan dependen del nivel del plan y se ajustan dinámicamente según los recursos; fuera de horas pico la concurrencia puede ser mayor.
El significado de los códigos de error está en la documentación oficial de códigos de API: 1302 = la solicitud alcanzó el límite de velocidad; 1305 = sobrecarga temporal del servicio, inténtalo de nuevo más tarde.
Solución correcta: ante un 429 / 1305 temporal en horas pico, basta con esperar y reintentar. Solo si sigue fallando de forma persistente fuera de horas pico, o si los fallos se concentran en un solo endpoint / modelo / tipo de solicitud, vuelve a revisar la configuración (los dos comandos del error anterior).
❌ /think off no desactiva el razonamiento de GLM-5.3
Causa: GLM-5.3 / GLM-5.3-flash solo soporta los tres niveles low / high / max (predeterminado max), no admite desactivarlo por completo — un /think off explícito se mapea a reasoning_effort: "low".
Lo correcto: si necesitas desactivar el thinking por completo (para ahorrar presupuesto de salida), cambia a zai/glm-5.2——soporta off / low / high / max completos, y el valor por defecto es precisamente off. Ver las capacidades exclusivas más abajo.
❌ Sigues usando zai/glm-5.1
Motivo: glm-5.1 está obsoleto; si no se configura en el catálogo, no aparece; la recomendación oficial es cambiar a GLM-5.2. En el endpoint del Coding Plan, las solicitudes a 5.2 / 5.1 son redirigidas por Z.AI a GLM-5.3——el modelo que crees estar usando y el que realmente se ejecuta no son el mismo.
Lo correcto: en la General API cambia a zai/glm-5.2; en el Coding Plan usa directamente zai/glm-5.3.
❌ Tras instalar Gateway como demonio, la Key exportada «no surte efecto»
Motivo: los servicios de launchd / systemd no ven las variables de entorno del shell interactivo——algo que la documentación de cada provider recalca una y otra vez.
Lo correcto: escribe ZAI_API_KEY en ~/.openclaw/.env, o proporciónalo mediante env.shellEnv en la configuración; reinicia el servicio de Gateway tras cambiar la Key.
🔧 Capacidades exclusivas de GLM (opcional)
Una vez instalado el plugin, llegan cuatro capacidades exclusivas de GLM.
Niveles de thinking: tres conjuntos de mapeos
| Modelo | Niveles soportados | Por defecto | Detalles del mapeo |
|---|---|---|---|
| GLM-5.3 / 5.3-flash | low / high / max | max | se mapea al campo reasoning_effort de Z.AI; off explícito se mapea a low (no se puede desactivar por completo) |
| GLM-5.2 | off / low / high / max | off | low / high se mapean a high de Z.AI, max se mapea a max, y se envían mediante reasoning_effort |
| Otros modelos GLM | off / low (en el selector se muestra on) | off | off envía thinking: { type: "disabled" }; los demás niveles no tocan el cuerpo de la solicitud y siguen el comportamiento de razonamiento por defecto de Z.AI |
Úsalo directamente en el chat:
/think max # nivel por defecto de GLM-5.3
/think off # en GLM-5.3 en realidad es low; solo en GLM-5.2 se desactiva de verdadLa razón oficial: configurar el thinking en off evita que la respuesta gaste primero el presupuesto de salida en reasoning_content y que el cuerpo visible quede más corto.
Generación de vídeo: zai/cogvideox-3
El mismo plugin y la misma ZAI_API_KEY (o Z_AI_API_KEY) también pueden impulsar la herramienta de generación de vídeo, con el modelo zai/cogvideox-3:
- Entrada: un prompt de texto, o una imagen PNG / JPEG (los archivos locales se envían como data URI, máximo 5 MB); no admite referencias a vídeos
- Duración: se normaliza a 5 o 10 segundos
- Dimensiones: se mapean a la dimensión soportada más cercana——
1280x720,720x1280,1024x1024,1920x1080,1080x1920,2048x1080,3840x2160 - Por defecto 720P horizontal, sin audio;
audio: trueactiva el sonido - Avanzado:
providerOptions.quality(speed/quality),providerOptions.fps(30/60)
Configurarlo como proveedor de vídeo por defecto (ejemplo oficial de configuración, tal cual):
{
agents: {
defaults: {
mediaModels: {
video: { primary: "zai/cogvideox-3" },
},
},
},
}⚠️ El vídeo pasa por el endpoint General; la suscripción del Coding Plan no lo cubre directamente
La generación de vídeo usa el endpoint General /api/paas/v4 de la región que hayas configurado (internacional / China); el endpoint de chat del Coding Plan se mapea al endpoint General de vídeo de la misma región——el vídeo requiere acceso a la API y facturación de ese endpoint, no viene incluido en la cuota mensual del Coding Plan.
Si quieres explorar de forma sistemática imágenes, voz y vídeo, consulta Imágenes y voz: ilustrar contenido y convertir artículos en voz.
Comprensión de imágenes: glm-4.6v
El plugin de Z.AI registra la capacidad de comprensión de imágenes, con el modelo glm-4.6v——se resuelve automáticamente a partir de las credenciales de Z.AI que hayas configurado, sin configuración adicional.
::: Detalles avanzados: tool_stream, preserveThinking e ids GLM-5 desconocidos
- Streaming de llamadas a herramientas:
tool_streamestá activado por defecto. Para desactivarlo, cambia el parámetro de la configuración siguiente portool_stream: falsey la clave del modelo por elzai/<模型>correspondiente - Conservar el thinking (preserveThinking): desactivado por defecto——Z.AI exige reproducir el historial
reasoning_contentcompleto, lo que aumenta los tokens del prompt. Actívalo por modelo (ejemplo oficial, tal cual):
{
agents: {
defaults: {
models: {
"zai/glm-5.3": {
params: { preserveThinking: true },
},
},
},
},
}Al activarlo, durante el thinking se envía thinking: { type: "enabled", clear_thinking: false } y se reproduce el historial reasoning_content de la misma transcripción compatible con OpenAI (preserve_thinking en snake_case es un alias). Los usuarios avanzados pueden usar params.extra_body.thinking para sobrescribir con precisión el payload del provider.
- Resolución anticipada de ids GLM-5 desconocidos: los ids
glm-5*que no estén en el catálogo, siempre que coincidan con la forma de la familia GLM-5 actual, se resuelven porque el provider sintetiza metadatos con la plantillaglm-4.7:::
Siguiente paso
Con esto completas la configuración de OpenClaw GLM de Zhipu. Continúa en las páginas dedicadas a los modelos nacionales:
- Siguiente lección Conectar Kimi: los dos plugins Moonshot y Kimi Coding: por qué Moonshot y Kimi Coding son dos plugins y dos Keys
- Las demás páginas de modelos (MiniMax, Doubao, Hunyuan / Qianfan, modelos de reenvío y locales) se acceden desde el temario de Resumen de conexión de modelos
- ¿Ya configuraste los modelos? Para el uso diario, empieza por Uso diario: convive eficientemente con tu Claw——Control UI, comandos de chat y sistema de memoria están en ese capítulo