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 è la piattaforma API per i modelli GLM. Fornisce API REST per GLM e utilizza chiavi API per l'autenticazione. Crea la tua chiave API nella console Z.AI. OpenClaw utilizza il provider zai con una chiave API Z.AI.

Proprietà Valore
Provider zai
Pacchetto @openclaw/zai-provider
Autenticazione ZAI_API_KEY (alias precedente: Z_AI_API_KEY)
API Completamenti chat Z.AI (autenticazione Bearer)

Modelli GLM

GLM è una famiglia di modelli, non un provider separato. In OpenClaw, i modelli GLM utilizzano riferimenti come zai/glm-5.2: provider zai, ID modello glm-5.2.

Guida introduttiva

Installa prima il Plugin del provider:

bash
openclaw plugins install @openclaw/zai-provider

Rilevamento automatico dell'endpoint

Ideale per: la maggior parte degli utenti. OpenClaw verifica gli endpoint Z.AI supportati con la tua chiave API e applica automaticamente l'URL di base corretto.

  • Esegui la configurazione iniziale

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

  • Verifica che il modello sia elencato

    bash
    openclaw models list --all --provider zai

    • Endpoint regionale esplicito

    Ideale per: gli utenti che desiderano imporre un Coding Plan specifico o una determinata superficie API generale.

  • Scegli l'opzione di configurazione iniziale corretta

    bash
    # Coding Plan globale (consigliato per gli utenti di Coding Plan)openclaw onboard --auth-choice zai-coding-global # Coding Plan CN (regione Cina)openclaw onboard --auth-choice zai-coding-cn # API generaleopenclaw onboard --auth-choice zai-global # API generale CN (regione Cina)openclaw onboard --auth-choice zai-cn

  • Verifica che il modello sia elencato

    bash
    openclaw models list --all --provider zai

    • Endpoint

    Opzione di configurazione iniziale URL di base Modello predefinito
    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

    zai-api-key rileva automaticamente uno di questi quattro endpoint provando la tua chiave con l'API dei completamenti chat di ciascun endpoint, controllando gli endpoint generali (zai-global, quindi zai-cn) prima degli endpoint Coding Plan (zai-coding-global, quindi zai-coding-cn) e arrestandosi al primo endpoint che accetta una richiesta. Usa un valore --auth-choice esplicito per imporre un endpoint Coding Plan se la tua chiave funziona con entrambi.

    Esempio di configurazione

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

    Catalogo integrato

    Il Plugin del provider zai distribuisce il proprio catalogo nel manifesto del Plugin, quindi l'elenco in sola lettura può mostrare le righe GLM note senza caricare il runtime del provider:

    bash
    openclaw models list --all --provider zai

    Il catalogo basato sul manifesto include attualmente:

    Riferimento modello Note
    zai/glm-5.2 Predefinito di Coding Plan; contesto di 1M
    zai/glm-5.1 Predefinito dell'API generale
    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

    Livelli di ragionamento

    GLM-5.2

    Intervallo completo: off, low, high, max (valore predefinito off). OpenClaw associa low e high al livello di ragionamento high di Z.AI e max al livello max di Z.AI, tramite reasoning_effort nel payload della richiesta.

    Altri modelli GLM

    Solo opzione binaria: off e low (visualizzato come on nei selettori), valore predefinito off. Impostando il ragionamento su off viene inviato thinking: { type: "disabled" }; qualsiasi altro livello lascia invariato il payload della richiesta (si applica il comportamento di ragionamento predefinito di Z.AI).

    Impostare il ragionamento su off evita risposte che consumano il budget di output per reasoning_content prima del testo visibile.

    Configurazione avanzata

    Risoluzione futura dei modelli GLM-5 sconosciuti

    Gli ID glm-5* sconosciuti vengono comunque risolti in modo prospettico nel percorso del provider, sintetizzando metadati di proprietà del provider dal modello glm-4.7 quando l'ID corrisponde alla forma corrente della famiglia GLM-5.

    Streaming delle chiamate agli strumenti

    tool_stream è abilitato per impostazione predefinita per lo streaming delle chiamate agli strumenti di Z.AI. Per disabilitarlo:

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

    La conservazione del ragionamento è opzionale perché Z.AI richiede di riprodurre l'intero reasoning_content storico, aumentando il numero di token del prompt. Abilitala per ogni modello:

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

    Quando è abilitata e il ragionamento è attivo, OpenClaw invia thinking: { type: "enabled", clear_thinking: false } e riproduce il reasoning_content precedente per la stessa trascrizione compatibile con OpenAI. La chiave del parametro in snake_case preserve_thinking funziona come alias.

    Gli utenti avanzati possono comunque sovrascrivere il payload esatto del provider con params.extra_body.thinking.

    Comprensione delle immagini

    Il Plugin Z.AI registra la comprensione delle immagini.

    Proprietà Valore
    Modello glm-4.6v

    La comprensione delle immagini viene risolta automaticamente dall'autenticazione Z.AI configurata: non è necessaria alcuna configurazione aggiuntiva.

    Dettagli sull'autenticazione
    • Z.AI utilizza l'autenticazione Bearer con la tua chiave API.
    • L'opzione di configurazione iniziale zai-api-key rileva automaticamente l'endpoint Z.AI corrispondente provando gli endpoint supportati con la tua chiave.
    • Usa le opzioni regionali esplicite (zai-coding-global, zai-coding-cn, zai-global, zai-cn) quando desideri imporre una superficie API specifica.
    • La variabile di ambiente precedente Z_AI_API_KEY è ancora accettata; OpenClaw la copia in ZAI_API_KEY all'avvio se ZAI_API_KEY non è impostata.

    Contenuti correlati

    Selezione del modello

    Scelta dei provider, dei riferimenti ai modelli e del comportamento di failover.
    Riferimento per la configurazione

    Schema di configurazione completo di OpenClaw, incluse le impostazioni di provider e modelli.
    Was this useful?
    On this page

    On this page