Skip to content

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):

PropiedadValor
Provider idzai
Variable de entorno de autenticaciónZAI_API_KEY (el alias antiguo Z_AI_API_KEY sigue aceptándose y se copia automáticamente al iniciar)
Forma de la APIZ.AI Chat Completions (autenticación Bearer)
Plugin oficial@openclaw/zai-provider (plugin externo, requiere instalación)
Modelo predeterminadoCoding Plan: zai/glm-5.3; General API: zai/glm-5.2
Consola de gestión de Keyhttps://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):

Usoauth-choiceBase URLModelo predeterminado
General API · sitio internacionalzai-globalhttps://api.z.ai/api/paas/v4glm-5.2
General API · sitio nacionalzai-cnhttps://open.bigmodel.cn/api/paas/v4glm-5.2
Coding Plan · sitio internacionalzai-coding-globalhttps://api.z.ai/api/coding/paas/v4glm-5.3
Coding Plan · sitio nacionalzai-coding-cnhttps://open.bigmodel.cn/api/coding/paas/v4glm-5.3

Cómo elegir, en tres frases:

Tu situaciónElige 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 Keyzai-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-provider y configurar ZAI_API_KEY en 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.1 ya no debe usarse
  • Mantener la calma al encontrar 429 / 1302 / 1305 en horas pico: distinguir entre «limitación temporal» y «endpoint mal configurado»
  • Aprovechar las capacidades exclusivas de GLM: niveles de razonamiento /think, generación de video cogvideox-3, comprensión de imágenes glm-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 status produce 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.

  1. Abre en el navegador la consola de Z.AI https://z.ai/manage-apikey/apikey-list, regístrate / inicia sesión
  2. Crea una API Key, cópiala y pégala en un lugar seguro
  3. 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 de open.bigmodel.cn y 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):

bash
openclaw plugins install @openclaw/zai-provider

Deberí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:

bash
openclaw onboard --auth-choice zai-api-key

Orden 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):

bash
# 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-cn

Deberí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 set del paso 3
  • la antigua variable de entorno Z_AI_API_KEY sigue siendo válida: si al iniciar ZAI_API_KEY no 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):

json5
{
  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 usarQué escribir en baseUrl
Coding Plan · sitio internacionalhttps://api.z.ai/api/coding/paas/v4
Coding Plan · sitio de Chinahttps://open.bigmodel.cn/api/coding/paas/v4
General API · sitio internacionalhttps://api.z.ai/api/paas/v4
General API · sitio de Chinahttps://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 de ZAI_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:

bash
openclaw models list --all --provider zai

Deberí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 modeloContextoNotas
zai/glm-5.31,048,576Predeterminado en Coding Plan
zai/glm-5.3-flash1,048,576Multimodal (texto + imagen)
zai/glm-5.21MPredeterminado en General API
zai/glm-5-turbo200KModelo de texto optimizado de OpenClaw
zai/glm-5v-turbo200KModelo 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.3 como predeterminado; las configuraciones de General API se quedan en zai/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 necesidadElígeloSegún
Usuario de Coding Plan, no sabes qué elegirzai/glm-5.3Predeterminado oficial, contexto de 1M
Quieres que el modelo vea imágeneszai/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 completozai/glm-5.2thinking con off como predeterminado y soporta el nivel off (GLM-5.3 no se puede desactivar, ver capacidades exclusivas)

Cambiar el modelo predeterminado:

bash
openclaw models set zai/glm-5.3

Tambié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:

bash
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-provider ejecutado, 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 status se puede ver el ZAI_API_KEY de zai
  • openclaw models list --all --provider zai lista 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.1 como 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:

bash
openclaw models list --all --provider zai
openclaw config get models.providers.zai.baseUrl

Si 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:

bash
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 ​

ModeloNiveles soportadosPor defectoDetalles del mapeo
GLM-5.3 / 5.3-flashlow / high / maxmaxse mapea al campo reasoning_effort de Z.AI; off explícito se mapea a low (no se puede desactivar por completo)
GLM-5.2off / low / high / maxofflow / high se mapean a high de Z.AI, max se mapea a max, y se envían mediante reasoning_effort
Otros modelos GLMoff / low (en el selector se muestra on)offoff 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:

text
/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 verdad

La 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: true activa 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):

json5
{
  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_stream está activado por defecto. Para desactivarlo, cambia el parámetro de la configuración siguiente por tool_stream: false y la clave del modelo por el zai/<模型> correspondiente
  • Conservar el thinking (preserveThinking): desactivado por defecto——Z.AI exige reproducir el historial reasoning_content completo, lo que aumenta los tokens del prompt. Actívalo por modelo (ejemplo oficial, tal cual):
json5
{
  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 plantilla glm-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:

Tutoriales relacionados ​

gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.