OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Providers

Z.AI

Z.AI es la plataforma de API para los modelos GLM. Proporciona API REST para GLM y utiliza claves de API para la autenticación. Cree su clave de API en la consola de Z.AI. OpenClaw utiliza el proveedor zai con una clave de API de Z.AI.

Propiedad Valor
Proveedor zai
Paquete @openclaw/zai-provider
Autenticación ZAI_API_KEY (alias heredado: Z_AI_API_KEY)
API Finalizaciones de chat de Z.AI (autenticación Bearer)

Modelos GLM

GLM es una familia de modelos, no un proveedor independiente. En OpenClaw, los modelos GLM utilizan referencias como zai/glm-5.2: proveedor zai, id. de modelo glm-5.2.

Primeros pasos

Instale primero el plugin del proveedor:

bash
openclaw plugins install @openclaw/zai-provider

Detectar automáticamente el endpoint

Recomendado para: la mayoría de los usuarios. OpenClaw prueba los endpoints compatibles de Z.AI con su clave de API y aplica automáticamente la URL base correcta.

  • Ejecutar la incorporación

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

  • Verificar que el modelo aparezca en la lista

    bash
    openclaw models list --all --provider zai

    • Endpoint regional explícito

    Recomendado para: usuarios que deseen forzar un Coding Plan específico o una superficie de API general.

  • Elegir la opción de incorporación correcta

    bash
    # Coding Plan global (recomendado para usuarios de Coding Plan)openclaw onboard --auth-choice zai-coding-global # Coding Plan de China (región de China)openclaw onboard --auth-choice zai-coding-cn # API generalopenclaw onboard --auth-choice zai-global # API general de China (región de China)openclaw onboard --auth-choice zai-cn

  • Verificar que el modelo aparezca en la lista

    bash
    openclaw models list --all --provider zai

    • Endpoints

    Opción de incorporación URL base Modelo predeterminado
    zai-global https://api.z.ai/api/paas/v4 glm-5.1
    zai-cn https://open.bigmodel.cn/api/paas/v4 glm-5.1
    zai-coding-global https://api.z.ai/api/coding/paas/v4 glm-5.2
    zai-coding-cn https://open.bigmodel.cn/api/coding/paas/v4 glm-5.2

    Z.AI también publica la URL base de Coding Plan compatible con Anthropic https://api.z.ai/api/anthropic. Las opciones de Z.AI de OpenClaw utilizan los endpoints documentados de finalizaciones de chat de OpenAI anteriores; la URL de Anthropic es para clientes que se comunican directamente mediante Anthropic Messages.

    zai-api-key detecta automáticamente uno de estos cuatro al probar su clave con la API de finalizaciones de chat de cada endpoint; comprueba los endpoints generales (zai-global, y después zai-cn) antes que los endpoints de Coding Plan (zai-coding-global, y después zai-coding-cn) y se detiene en el primer endpoint que acepta una solicitud. Utilice un --auth-choice explícito para forzar un endpoint de Coding Plan si su clave funciona en ambos.

    Límites de frecuencia y sobrecargas

    Z.AI documenta Coding Plan y las herramientas de agente de uso general como servicios con capacidad administrada. Según la propia documentación de Z.AI:

    • Las herramientas de agente de uso general, incluido OpenClaw, se proporcionan según la disponibilidad. Durante una carga de inferencia elevada, normalmente entre las 2 y las 6 p. m., hora de Singapur, algunas solicitudes pueden estar sujetas a límites de frecuencia temporales.
    • Los límites de frecuencia y concurrencia de Coding Plan están vinculados al nivel del plan y pueden ajustarse dinámicamente según la disponibilidad de recursos. Las horas de menor demanda pueden ofrecer una concurrencia mayor.
    • El código de error de la API 1302 significa «Se alcanzó el límite de frecuencia de solicitudes». El código de error de la API 1305 significa «El servicio puede estar temporalmente sobrecargado; inténtelo de nuevo más tarde».

    Si aparece una respuesta temporal 429 o 1305 durante un periodo de alta demanda, espere y vuelva a intentar la solicitud. Si los fallos se repiten fuera de los periodos de máxima demanda o solo se producen con un endpoint, modelo o formato de solicitud, compruebe primero el endpoint y el modelo configurados:

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

    Las claves de Coding Plan deben utilizar un endpoint de Coding Plan como https://api.z.ai/api/coding/paas/v4; las claves de la API general deben utilizar un endpoint de la API general como https://api.z.ai/api/paas/v4. Los fallos persistentes con la misma clave y el mismo endpoint pueden indicar un rechazo del proveedor o una limitación del plan, no una limitación normal por carga máxima.

    Ejemplo de configuración

    json5
    {  env: { ZAI_API_KEY: "sk-..." },  models: {    providers: {      zai: {        // GLM-5.2 utiliza el endpoint de Coding Plan.        baseUrl: "https://api.z.ai/api/coding/paas/v4",      },    },  },  agents: { defaults: { model: { primary: "zai/glm-5.2" } } },}

    Catálogo integrado

    El plugin del proveedor zai incluye su catálogo en el manifiesto del plugin, por lo que el listado de solo lectura puede mostrar las filas conocidas de GLM sin cargar el entorno de ejecución del proveedor:

    bash
    openclaw models list --all --provider zai

    El catálogo respaldado por el manifiesto incluye actualmente:

    Referencia del modelo Notas
    zai/glm-5.2 Valor predeterminado de Coding Plan; contexto de 1M
    zai/glm-5.1 Valor predeterminado de la API general
    zai/glm-5
    zai/glm-5-turbo
    zai/glm-5v-turbo
    zai/glm-4.7
    zai/glm-4.7-flash
    zai/glm-4.7-flashx
    zai/glm-4.6
    zai/glm-4.6v
    zai/glm-4.5
    zai/glm-4.5-air
    zai/glm-4.5-flash
    zai/glm-4.5v

    Los metadatos de coste por token del catálogo siguen los precios actuales de pago por uso de Z.AI. Las suscripciones de Coding Plan utilizan la cuota del plan en lugar de la facturación por token; consulte la página de suscripción activa para conocer los precios y la disponibilidad de los planes.

    Niveles de razonamiento

    GLM-5.2

    Intervalo completo: off, low, high, max (valor predeterminado: off). OpenClaw asigna low y high al esfuerzo de razonamiento high de Z.AI, y max al esfuerzo max de Z.AI, mediante reasoning_effort en la carga útil de la solicitud.

    Otros modelos GLM

    Solo conmutador binario: off y low (se muestra como on en los selectores), con valor predeterminado off. Establecer el razonamiento en off envía thinking: { type: "disabled" }; cualquier otro nivel deja intacta la carga útil de la solicitud (se aplica el comportamiento de razonamiento predeterminado de Z.AI).

    Establecer el razonamiento en off evita respuestas que consuman el presupuesto de salida en reasoning_content antes del texto visible.

    Configuración avanzada

    Resolución anticipada de modelos GLM-5 desconocidos

    Los identificadores glm-5* desconocidos siguen resolviéndose de forma anticipada en la ruta del proveedor mediante la síntesis de metadatos propiedad del proveedor a partir de la plantilla glm-4.7 cuando el identificador coincide con el formato actual de la familia GLM-5.

    Transmisión de llamadas a herramientas

    tool_stream está habilitado de forma predeterminada para la transmisión de llamadas a herramientas de Z.AI. Para deshabilitarlo:

    json5
    {  agents: {    defaults: {      models: {        "zai/<model>": {          params: { tool_stream: false },        },      },    },  },}
    Razonamiento conservado

    El razonamiento conservado es opcional porque Z.AI exige que se reproduzca el reasoning_content histórico completo, lo que aumenta los tokens del prompt. Habilítelo para cada modelo:

    json5
    {  agents: {    defaults: {      models: {        "zai/glm-5.2": {          params: { preserveThinking: true },        },      },    },  },}

    Cuando está habilitado y el razonamiento está activado, OpenClaw envía thinking: { type: "enabled", clear_thinking: false } y reproduce los reasoning_content anteriores para la misma transcripción compatible con OpenAI. La clave de parámetro en snake_case preserve_thinking funciona como alias.

    Los usuarios avanzados aún pueden sustituir la carga útil exacta del proveedor mediante params.extra_body.thinking.

    Comprensión de imágenes

    El plugin de Z.AI registra la comprensión de imágenes.

    Propiedad Valor
    Modelo glm-4.6v

    La comprensión de imágenes se resuelve automáticamente a partir de la autenticación configurada de Z.AI; no se necesita ninguna configuración adicional.

    Detalles de autenticación
    • Z.AI utiliza autenticación Bearer con su clave de API.
    • La opción de incorporación zai-api-key detecta automáticamente el endpoint de Z.AI correspondiente al probar los endpoints compatibles con su clave.
    • Utilice las opciones regionales explícitas (zai-coding-global, zai-coding-cn, zai-global, zai-cn) cuando desee forzar una superficie de API específica.
    • La variable de entorno heredada Z_AI_API_KEY todavía se acepta; OpenClaw la copia a ZAI_API_KEY al iniciarse si ZAI_API_KEY no está definida.

    Contenido relacionado

    Selección de modelos

    Selección de proveedores, referencias de modelos y comportamiento de conmutación por error.
    Referencia de configuración

    Esquema completo de configuración de OpenClaw, incluidos los ajustes de proveedores y modelos.
    Was this useful?
    On this page

    On this page