---
read_when:
    - Vous souhaitez utiliser les modèles Z.AI / GLM dans OpenClaw
    - Vous avez besoin d’une configuration simple de `ZAI_API_KEY`
summary: Utiliser Z.AI (modèles GLM) avec OpenClaw
title: Z.AI
x-i18n:
    generated_at: "2026-07-16T13:42:22Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: 7f7adf0e2f436f9081891013c0092ce4717bf302b2a4a2e997d9561d7d40211a
    source_path: providers/zai.md
    workflow: 16
---

Z.AI est la plateforme d’API pour les modèles **GLM**. Elle fournit des API REST pour GLM et
utilise des clés d’API pour l’authentification. Créez votre clé d’API dans la console Z.AI.
OpenClaw utilise le fournisseur `zai` avec une clé d’API Z.AI.

| Propriété   | Valeur                                       |
| ----------- | -------------------------------------------- |
| Fournisseur | `zai`                           |
| Paquet      | `@openclaw/zai-provider`                           |
| Auth        | `ZAI_API_KEY` (ancien alias : `Z_AI_API_KEY`) |
| API         | Complétions de chat Z.AI (authentification Bearer) |

## Modèles GLM

GLM est une famille de modèles, et non un fournisseur distinct. Dans OpenClaw, les modèles GLM utilisent
des références telles que `zai/glm-5.2` : fournisseur `zai`, identifiant de modèle `glm-5.2`.

## Bien démarrer

Installez d’abord le Plugin du fournisseur :

```bash
openclaw plugins install @openclaw/zai-provider
```

<Tabs>
  <Tab title="Détection automatique du point de terminaison">
    **Idéal pour :** la plupart des utilisateurs. OpenClaw teste les points de terminaison Z.AI pris en charge avec votre clé d’API et applique automatiquement l’URL de base correcte.

    <Steps>
      <Step title="Exécuter l’intégration initiale">
        ```bash
        openclaw onboard --auth-choice zai-api-key
        ```
      </Step>
      <Step title="Vérifier que le modèle figure dans la liste">
        ```bash
        openclaw models list --all --provider zai
        ```
      </Step>
    </Steps>

  </Tab>

  <Tab title="Point de terminaison régional explicite">
    **Idéal pour :** les utilisateurs qui souhaitent imposer une surface d’API Coding Plan ou générale précise.

    <Steps>
      <Step title="Choisir l’option d’intégration initiale appropriée">
        ```bash
        # Coding Plan mondial (recommandé pour les utilisateurs de Coding Plan)
        openclaw onboard --auth-choice zai-coding-global

        # Coding Plan CN (région Chine)
        openclaw onboard --auth-choice zai-coding-cn

        # API générale
        openclaw onboard --auth-choice zai-global

        # API générale CN (région Chine)
        openclaw onboard --auth-choice zai-cn
        ```
      </Step>
      <Step title="Vérifier que le modèle figure dans la liste">
        ```bash
        openclaw models list --all --provider zai
        ```
      </Step>
    </Steps>

  </Tab>
</Tabs>

### Points de terminaison

| Option d’intégration initiale | URL de base                                   | Modèle par défaut |
| ----------------------------- | --------------------------------------------- | ----------------- |
| `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` détecte automatiquement l’un de ces quatre points de terminaison en testant votre clé auprès de l’API
de complétions de chat de chacun d’eux. Il vérifie les points de terminaison généraux (`zai-global`,
puis `zai-cn`) avant ceux de Coding Plan (`zai-coding-global`, puis
`zai-coding-cn`) et s’arrête au premier point de terminaison qui accepte une requête.
Utilisez un `--auth-choice` explicite pour imposer un point de terminaison Coding Plan si votre clé
fonctionne avec les deux.

## Limites de débit et surcharges

La documentation de Z.AI décrit Coding Plan et les outils d’agent polyvalents comme des services
à capacité gérée. Selon la documentation de Z.AI :

- [Les outils d’agent polyvalents](https://docs.z.ai/devpack/tool/others),
  notamment OpenClaw, sont fournis dans la mesure du possible. Lors des fortes charges
  d’inférence, généralement entre 14 h et 18 h, heure de Singapour, certaines requêtes peuvent être soumises à des
  limites de débit temporaires.
- [Les limites de débit et de concurrence de Coding Plan](https://docs.z.ai/devpack/usage-policy)
  dépendent du niveau du forfait et peuvent être ajustées dynamiquement en fonction de la disponibilité
  des ressources. La concurrence peut être plus élevée pendant les heures creuses.
- [Le code d’erreur d’API `1302`](https://docs.z.ai/api-reference/api-code) signifie « Limite
  de débit atteinte pour les requêtes ». Le code d’erreur d’API `1305` signifie « Le service est peut-être
  temporairement surchargé. Veuillez réessayer ultérieurement ».

Si vous recevez une réponse temporaire `429` ou `1305` pendant une période de forte activité, attendez et
réessayez la requête. Si les échecs se reproduisent en dehors des périodes de pointe ou ne
concernent qu’un point de terminaison, un modèle ou une forme de requête, vérifiez d’abord le point de terminaison
et le modèle configurés :

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

Les clés Coding Plan doivent utiliser un point de terminaison Coding Plan tel que
`https://api.z.ai/api/coding/paas/v4` ; les clés d’API générales doivent utiliser un point de terminaison d’API générale
tel que `https://api.z.ai/api/paas/v4`. Des échecs persistants avec la
même clé et le même point de terminaison peuvent indiquer un rejet côté fournisseur ou une limitation du forfait,
et non une limitation ordinaire due aux pics de charge.

## Exemple de configuration

<Tip>
`zai-api-key` permet à OpenClaw de détecter à partir de la clé le point de terminaison Z.AI correspondant et
d’appliquer automatiquement l’URL de base correcte. Utilisez les options régionales explicites lorsque
vous souhaitez imposer une surface d’API Coding Plan ou générale précise.
</Tip>

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

## Catalogue intégré

Le Plugin du fournisseur `zai` fournit son catalogue dans le manifeste du Plugin ; l’affichage
en lecture seule peut donc présenter les entrées GLM connues sans charger l’environnement d’exécution du fournisseur :

```bash
openclaw models list --all --provider zai
```

Le catalogue issu du manifeste comprend actuellement :

| Référence du modèle | Remarques                              |
| ------------------- | -------------------------------------- |
| `zai/glm-5.2`  | Modèle par défaut de Coding Plan ; contexte de 1M |
| `zai/glm-5.1`  | Modèle par défaut de l’API générale    |
| `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`  |                                        |

<Tip>
Les modèles GLM sont disponibles sous la forme `zai/<model>` (exemple : `zai/glm-5`).
</Tip>

<Note>
La configuration de Coding Plan utilise `zai/glm-5.2` par défaut ; celle de l’API générale conserve
`zai/glm-5.1`. Sur les points de terminaison Coding Plan, la détection automatique se rabat sur
`glm-5.1`, puis sur `glm-4.7` lorsque la clé ou le forfait ne donne pas accès à GLM-5.2. Les versions
et la disponibilité de GLM peuvent changer ; exécutez `openclaw models list --all --provider zai`
pour afficher le catalogue connu de votre version installée.
</Note>

## Niveaux de raisonnement

<Tabs>
  <Tab title="GLM-5.2">
    Plage complète : `off`, `low`, `high`, `max` (`off` par défaut). OpenClaw associe
    `low` et `high` à l’effort de raisonnement `high` de Z.AI, et `max` à
    l’effort `max` de Z.AI, via `reasoning_effort` dans la charge utile de la requête.
  </Tab>
  <Tab title="Autres modèles GLM">
    Uniquement une activation binaire : `off` et `low` (affiché sous la forme `on` dans les sélecteurs), avec
    `off` par défaut. Définir le raisonnement sur `off` envoie `thinking: { type: "disabled" }` ;
    tout autre niveau laisse la charge utile de la requête inchangée (le comportement de raisonnement
    par défaut de Z.AI s’applique).
  </Tab>
</Tabs>

Définir le raisonnement sur `off` évite les réponses qui consacrent le budget de sortie à
`reasoning_content` avant le texte visible.

## Configuration avancée

<AccordionGroup>
  <Accordion title="Résolution anticipée des modèles GLM-5 inconnus">
    Les identifiants `glm-5*` inconnus continuent d’être résolus sur le chemin du fournisseur en
    synthétisant les métadonnées détenues par le fournisseur à partir du modèle `glm-4.7` lorsque l’identifiant
    correspond à la forme actuelle de la famille GLM-5.
  </Accordion>

  <Accordion title="Diffusion en continu des appels d’outils">
    `tool_stream` est activé par défaut pour la diffusion en continu des appels d’outils Z.AI. Pour le désactiver :

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

  </Accordion>

  <Accordion title="Raisonnement conservé">
    Le raisonnement conservé est facultatif, car Z.AI exige de rejouer l’intégralité de l’historique
    `reasoning_content`, ce qui augmente le nombre de jetons de l’invite. Activez-le
    pour chaque modèle :

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

    Lorsqu’il est activé et que le raisonnement est en fonctionnement, OpenClaw envoie
    `thinking: { type: "enabled", clear_thinking: false }` et rejoue les éléments
    `reasoning_content` précédents pour la même transcription compatible avec OpenAI. La clé de paramètre en snake_case
    `preserve_thinking` fonctionne comme alias.

    Les utilisateurs avancés peuvent toujours remplacer la charge utile exacte du fournisseur avec
    `params.extra_body.thinking`.

  </Accordion>

  <Accordion title="Compréhension des images">
    Le Plugin Z.AI enregistre la compréhension des images.

    | Propriété | Valeur              |
    | --------- | ------------------- |
    | Modèle    | `glm-4.6v`  |

    La compréhension des images est automatiquement résolue à partir de l’authentification Z.AI configurée — aucune
    configuration supplémentaire n’est nécessaire.

  </Accordion>

  <Accordion title="Détails de l’authentification">
    - Z.AI utilise l’authentification Bearer avec votre clé d’API.
    - L’option d’intégration initiale `zai-api-key` détecte automatiquement le point de terminaison Z.AI correspondant en testant les points de terminaison pris en charge avec votre clé.
    - Utilisez les options régionales explicites (`zai-coding-global`, `zai-coding-cn`, `zai-global`, `zai-cn`) lorsque vous souhaitez imposer une surface d’API précise.
    - L’ancienne variable d’environnement `Z_AI_API_KEY` est toujours acceptée ; OpenClaw la copie dans `ZAI_API_KEY` au démarrage si `ZAI_API_KEY` n’est pas définie.

  </Accordion>
</AccordionGroup>

## Pages connexes

<CardGroup cols={2}>
  <Card title="Sélection du modèle" href="/fr/concepts/model-providers" icon="layers">
    Choix des fournisseurs, des références de modèles et du comportement de basculement.
  </Card>
  <Card title="Référence de configuration" href="/fr/gateway/configuration-reference" icon="gear">
    Schéma de configuration complet d’OpenClaw, y compris les paramètres des fournisseurs et des modèles.
  </Card>
</CardGroup>
