Intégrer Z.ai GLM-5.2 dans votre application : TypeScript, Claude Code, Cline et auto-hébergement

Pendant deux ans, les modèles de codage les plus puissants étaient fermés, coûteux et impossibles à exécuter sur son propre matériel. GLM-5.2, lancé par Z.ai (anciennement Zhipu) le 13 juin 2026, brise ce schéma. C'est un modèle à poids ouverts de type mélange d'experts (MoE) conçu pour l'ingénierie logicielle agentique plutôt que pour la conversation, livré avec une fenêtre de contexte réellement exploitable d'un million de jetons, et dont l'API hébergée est exposée à travers deux couches de compatibilité à la fois — l'une qui imite le /chat/completions d'OpenAI et l'autre qui imite l'API Messages d'Anthropic.

Cette double personnalité est la partie intéressante pour les développeurs. Elle signifie qu'un seul modèle peut alimenter votre backend TypeScript via le SDK OpenAI, et servir de remplaçant direct de Claude au sein de Claude Code, et — parce que les poids sont sous licence MIT et publiés sur Hugging Face — s'exécuter entièrement dans votre propre centre de données avec vLLM. Pour les équipes de la région MENA soumises aux règles de l'INPDP en Tunisie ou au PDPL en Arabie saoudite, cette dernière option signifie une assistance au codage de niveau frontière sans qu'un seul jeton ne quitte votre infrastructure.

Ce tutoriel couvre tout cela : appeler GLM-5.2 depuis TypeScript, le streaming, l'appel d'outils, le substituer dans Claude Code et Cline, et enfin auto-héberger les poids ouverts.

Prérequis

Avant de commencer, assurez-vous d'avoir :

• Node.js 20+ et un gestionnaire de paquets (nous utilisons pnpm, mais npm fonctionne aussi)
• Une familiarité de base avec TypeScript et async/await
• Un compte Z.ai avec une clé API (un abonnement Coding Plan ou des crédits à l'usage) — inscrivez-vous sur z.ai
• Optionnel, pour la section auto-hébergement : une machine Linux équipée d'un GPU NVIDIA (ou un accès à l'une) et Docker
• Optionnel : Claude Code et/ou l'extension Cline pour VS Code installée

Ce que vous allez construire

À la fin, vous disposerez de :

1. Un petit script TypeScript qui appelle GLM-5.2 via le point d'accès compatible OpenAI
2. Une fonction de chat en streaming et une boucle d'agent avec appel d'outils
3. Claude Code reconfiguré pour utiliser GLM-5.2 comme backend de modèle
4. Cline pointé vers le même modèle dans VS Code
5. Un point d'accès GLM auto-hébergé tournant sur vLLM, au comportement identique à l'API hébergée

L'astuce qui rend ces cinq étapes possibles est de comprendre les deux points d'accès de Z.ai ; commençons par là.

Étape 1 : Comprendre les deux points d'accès

Z.ai expose les modèles GLM via deux surfaces d'API. Choisir la bonne pour chaque outil est la décision la plus importante de ce tutoriel.

L'identifiant du modèle est glm-5.2 partout, à une exception près que nous verrons plus loin : dans Claude Code, vous ajoutez un suffixe [1m] (glm-5.2[1m]) pour déverrouiller la fenêtre complète d'un million de jetons.

Étape 2 : Mise en place du projet

Créez un nouveau projet et installez le SDK OpenAI. Même si nous parlons à GLM, le point d'accès compatible OpenAI fait du paquet officiel openai la voie la plus propre.

mkdir glm-quickstart && cd glm-quickstart
pnpm init
pnpm add openai
pnpm add -D typescript tsx @types/node
npx tsc --init

Stockez votre clé dans une variable d'environnement plutôt que de la coder en dur — une règle qui vaut même pour les scripts jetables.

# .env (ne jamais le committer)
ZAI_API_KEY=your-zai-api-key-here

Ajoutez une ligne .env à .gitignore, puis créez src/client.ts qui construit un client configuré une fois et l'exporte :

// src/client.ts
import OpenAI from "openai";
 
if (!process.env.ZAI_API_KEY) {
  throw new Error("Missing ZAI_API_KEY environment variable");
}
 
export const glm = new OpenAI({
  apiKey: process.env.ZAI_API_KEY,
  // L'URL de base compatible OpenAI — notez la barre oblique finale
  baseURL: "https://api.z.ai/api/paas/v4/",
});
 
export const GLM_MODEL = "glm-5.2";

Comme le client n'est que le SDK OpenAI pointé vers un hôte différent, chaque méthode que vous connaissez déjà — chat.completions.create, le streaming, les appels d'outils — fonctionne sans changement.

Étape 3 : Votre première complétion

Créez src/hello.ts :

// src/hello.ts
import "dotenv/config";
import { glm, GLM_MODEL } from "./client";
 
async function main() {
  const completion = await glm.chat.completions.create({
    model: GLM_MODEL,
    messages: [
      { role: "system", content: "You are a precise senior TypeScript engineer." },
      { role: "user", content: "Write a one-line function that debounces a callback." },
    ],
  });
 
  console.log(completion.choices[0].message.content);
}
 
main().catch((err) => {
  console.error("GLM request failed:", err);
  process.exit(1);
});

Installez dotenv et exécutez-le :

pnpm add dotenv
pnpm tsx src/hello.ts

Si votre clé est valide, une implémentation de debounce s'affichera dans le terminal. Remarquez que rien dans ce code ne fait référence à Z.ai, hormis l'URL de base dans client.ts — c'est tout l'intérêt de la couche compatible OpenAI.

Étape 4 : Réponses en streaming

Pour tout ce qui est interactif, vous voulez les jetons au fur et à mesure qu'ils arrivent plutôt que d'attendre la réponse complète. Définissez stream: true et parcourez le flux asynchrone :

// src/stream.ts
import "dotenv/config";
import { glm, GLM_MODEL } from "./client";
 
async function streamChat(prompt: string) {
  const stream = await glm.chat.completions.create({
    model: GLM_MODEL,
    messages: [{ role: "user", content: prompt }],
    stream: true,
  });
 
  for await (const chunk of stream) {
    const delta = chunk.choices[0]?.delta?.content;
    if (delta) process.stdout.write(delta);
  }
  process.stdout.write("\n");
}
 
streamChat("Explain the actor model in three sentences.");

La forme du chunk est identique à celle d'OpenAI, donc tout code de streaming d'interface que vous avez déjà écrit pour des applications de style ChatGPT fonctionne sans modification.

Étape 5 : Contrôler l'effort de raisonnement

GLM-5.2 est livré avec deux niveaux d'effort de réflexion sélectionnables. Un effort plus élevé dépense davantage de jetons à raisonner avant de répondre — utile pour les refactorisations difficiles et les questions d'architecture, gaspilleur pour les recherches simples. Vous le contrôlez avec le paramètre reasoning via le passe-plat extra_body du SDK (les types OpenAI ne le connaissent pas, nous forçons donc le type) :

// src/reasoning.ts
import "dotenv/config";
import { glm, GLM_MODEL } from "./client";
 
async function deepThink(prompt: string) {
  const completion = await glm.chat.completions.create({
    model: GLM_MODEL,
    messages: [{ role: "user", content: prompt }],
    // Champ propre à Z.ai transmis directement à l'API
    // @ts-expect-error reasoning is a Z.ai extension, not in OpenAI types
    reasoning: { effort: "high" },
  });
 
  return completion.choices[0].message.content;
}
 
deepThink("Design a retry strategy for a payment webhook that must never double-charge.")
  .then(console.log);

Utilisez l'effort high avec parcimonie — sur les boucles d'agent à long horizon, cela s'accumule. Pour les complétions de routine, omettez complètement le paramètre et laissez le modèle adopter son mode le plus rapide.

Étape 6 : Appel d'outils pour les agents

La raison pour laquelle GLM-5.2 a été conçu pour « l'ingénierie logicielle agentique » plutôt que pour la conversation est sa fiabilité dans l'appel d'outils. Le schéma est le tableau tools standard d'OpenAI, de sorte qu'une boucle d'agent paraît familière. Voici une boucle minimale qui donne un outil au modèle et l'exécute :

// src/agent.ts
import "dotenv/config";
import { glm, GLM_MODEL } from "./client";
import type { ChatCompletionMessageParam } from "openai/resources/chat/completions";
 
const tools = [
  {
    type: "function" as const,
    function: {
      name: "get_repo_file_count",
      description: "Return how many files live in a given directory of the repo.",
      parameters: {
        type: "object",
        properties: {
          path: { type: "string", description: "Directory path, e.g. src/" },
        },
        required: ["path"],
      },
    },
  },
];
 
// Une implémentation factice — en réalité vous liriez le système de fichiers.
function runTool(name: string, args: Record<string, unknown>): string {
  if (name === "get_repo_file_count") {
    return JSON.stringify({ path: args.path, count: 42 });
  }
  return JSON.stringify({ error: "unknown tool" });
}
 
async function agent(userPrompt: string) {
  const messages: ChatCompletionMessageParam[] = [
    { role: "user", content: userPrompt },
  ];
 
  // Premier tour : le modèle décide s'il appelle un outil.
  const first = await glm.chat.completions.create({
    model: GLM_MODEL,
    messages,
    tools,
  });
 
  const choice = first.choices[0].message;
  messages.push(choice);
 
  // Exécuter les appels d'outils et renvoyer les résultats.
  for (const call of choice.tool_calls ?? []) {
    const args = JSON.parse(call.function.arguments);
    const result = runTool(call.function.name, args);
    messages.push({ role: "tool", tool_call_id: call.id, content: result });
  }
 
  // Deuxième tour : le modèle répond à partir de la sortie de l'outil.
  const second = await glm.chat.completions.create({
    model: GLM_MODEL,
    messages,
    tools,
  });
 
  return second.choices[0].message.content;
}
 
agent("How many files are in the src directory?").then(console.log);

En production, vous boucleriez l'étape d'exécution d'outils jusqu'à ce que le modèle cesse d'en demander, ajouteriez une garde max_steps et journaliseriez chaque appel d'outil. Mais le schéma central — demander, exécuter, renvoyer, redemander — est exactement la boucle qui anime les agents de codage.

Étape 7 : Utiliser GLM-5.2 comme backend de Claude Code

C'est ici que le point d'accès compatible Anthropic prend tout son sens. Claude Code lit une poignée de variables d'environnement pour décider quelle API et quels modèles appeler. Pointez-les vers Z.ai et Claude Code n'y verra que du feu.

Ajoutez ceci à votre profil shell, ou au bloc env de ~/.claude/settings.json :

export ANTHROPIC_BASE_URL="https://api.z.ai/api/coding/paas/v4"
export ANTHROPIC_API_KEY="your-glm-coding-plan-key"
export ANTHROPIC_DEFAULT_SONNET_MODEL="glm-5.2[1m]"
export ANTHROPIC_DEFAULT_OPUS_MODEL="glm-5.2[1m]"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="glm-4.7"
export CLAUDE_CODE_AUTO_COMPACT_WINDOW=1000000
export API_TIMEOUT_MS=3000000

Ce que fait chaque ligne :

• ANTHROPIC_BASE_URL redirige chaque requête de Claude Code vers le point d'accès de codage de Z.ai.
• ANTHROPIC_DEFAULT_SONNET_MODEL / OPUS_MODEL mappent les paliers de Claude sur GLM-5.2. Le suffixe [1m] est une convention de Claude Code qui demande la variante à contexte d'un million de jetons.
• ANTHROPIC_DEFAULT_HAIKU_MODEL dirige le modèle d'arrière-plan bon marché (utilisé pour les résumés et les titres) vers le glm-4.7, plus petit et plus rapide.
• CLAUDE_CODE_AUTO_COMPACT_WINDOW indique à Claude Code de ne pas compacter la conversation avant qu'elle n'approche le million de jetons, pour utiliser réellement la fenêtre que vous payez.
• API_TIMEOUT_MS augmente le délai d'attente des requêtes afin que les longues exécutions agentiques ne soient pas interrompues.

Ouvrez un nouveau terminal pour charger les variables, lancez claude et demandez-lui quelque chose. Les réponses proviennent désormais de GLM-5.2 — à environ un sixième du coût par jeton d'un modèle fermé de frontière.

Étape 8 : Utiliser GLM-5.2 dans Cline

Cline (l'agent VS Code) parle le dialecte OpenAI ; vous utilisez donc ici le point d'accès compatible OpenAI. Dans les paramètres de Cline :

• Fournisseur d'API : OpenAI Compatible
• URL de base : https://api.z.ai/api/paas/v4/ (gardez la barre oblique finale)
• Clé API : votre clé Z.ai
• ID du modèle : glm-5.2 (pas de suffixe [1m] ici — c'est une convention propre à Claude Code)
• Fenêtre de contexte : 1000000

Ce dernier réglage compte plus qu'il n'y paraît. Cline utilise la fenêtre de contexte configurée pour décider quand tronquer l'historique de conversation. Laissez-la à une petite valeur par défaut et vous jetez la majeure partie de la fenêtre d'un million de jetons de GLM-5.2 avant même que le modèle ne la voie. Les mêmes champs et valeurs fonctionnent pour la configuration de modèle personnalisé de Cursor.

Étape 9 : Auto-héberger les poids ouverts avec vLLM

L'API hébergée est pratique, mais la fonctionnalité phare pour les équipes réglementées est que les poids de GLM-5.2 sont sous licence MIT et publiés sur Hugging Face et ModelScope. Vous pouvez les servir vous-même avec vLLM, qui expose un serveur compatible OpenAI — ce qui signifie que le client.ts exact de l'étape 2 fonctionne sur votre propre matériel en changeant une seule URL.

Un lancement de serveur minimal (sur une machine multi-GPU, puisqu'il s'agit d'un grand modèle MoE) :

# Installer vLLM dans un environnement neuf
pip install "vllm>=0.8.0"
 
# Servir GLM-5.2 avec une API compatible OpenAI sur le port 8000
vllm serve zai-org/GLM-5.2 \
  --served-model-name glm-5.2 \
  --tensor-parallel-size 8 \
  --max-model-len 200000 \
  --host 0.0.0.0 \
  --port 8000

Pointez ensuite votre client TypeScript vers le serveur local — aucune clé API ne quitte votre réseau :

// src/client-selfhosted.ts
import OpenAI from "openai";
 
export const glm = new OpenAI({
  apiKey: "not-needed-locally", // vLLM ignore ceci par défaut
  baseURL: "http://localhost:8000/v1",
});
 
export const GLM_MODEL = "glm-5.2";

Si un déploiement multi-GPU complet est hors de portée, commencez par l'API hébergée pour le développement et réservez la voie auto-hébergée aux charges de travail qui exigent réellement un traitement des données sur site.

Étape 10 : Tirer le meilleur du contexte d'un million de jetons

Une fenêtre d'un million de jetons change la façon de rédiger les invites. Au lieu de rogner soigneusement le contexte, vous pouvez coller un module entier, ses tests et la documentation pertinente en une seule requête. Deux conseils pratiques :

• Le contexte long n'est pas gratuit. Même avec les optimisations d'attention clairsemée de GLM-5.2, plus de jetons signifie une latence et un coût plus élevés. Envoyez tout le dépôt quand la tâche l'exige vraiment ; envoyez un seul fichier quand ce n'est pas le cas.
• Le suffixe [1m] est propre à Claude Code. Dans votre propre code TypeScript et dans Cline, la fenêtre est contrôlée par la configuration (le réglage de fenêtre de contexte), pas par l'identifiant du modèle. N'ajoutez pas [1m] à glm-5.2 dans les appels d'API — ce n'est pas un nom de modèle valide à cet endroit.

Tester votre intégration

Vérifiez chaque couche indépendamment pour savoir où se situe une défaillance :

1. Couche OpenAI : pnpm tsx src/hello.ts renvoie une complétion → votre clé et votre URL de base sont correctes.
2. Streaming : pnpm tsx src/stream.ts affiche le texte progressivement → le streaming fonctionne.
3. Outils : pnpm tsx src/agent.ts renvoie une réponse qui fait référence à la sortie de l'outil (le compte de 42) → l'appel d'outils fait l'aller-retour.
4. Claude Code : dans un terminal neuf, lancez claude et vérifiez que les réponses arrivent ; si Claude Code signale une erreur d'authentification, votre ANTHROPIC_API_KEY ou votre URL de base est incorrecte.
5. Auto-hébergé : curl http://localhost:8000/v1/models liste glm-5.2 → votre serveur vLLM est opérationnel.

Dépannage

401 Unauthorized : Votre clé API est manquante, mal formée ou pour le mauvais plan. La clé Coding Plan et la clé API standard sont facturées différemment — assurez-vous d'utiliser celle qui correspond à votre point d'accès.

Claude Code appelle toujours la vraie API Anthropic : Les variables d'environnement ne s'appliquent qu'aux terminaux ouverts après les avoir définies. Ouvrez un nouveau terminal, ou confirmez avec echo $ANTHROPIC_BASE_URL.

Les réponses sont tronquées trop tôt dans Cline : Le réglage de fenêtre de contexte est trop bas. Augmentez-le à 1000000 pour que Cline cesse de jeter l'historique prématurément.

Nom de modèle invalide sur un appel d'API direct : Vous avez ajouté [1m] en dehors de Claude Code. Utilisez glm-5.2 simple dans le point d'accès compatible OpenAI et dans vLLM.

Mémoire insuffisante de vLLM au lancement : Réduisez --max-model-len, augmentez --tensor-parallel-size si vous avez plus de GPU, ou quantifiez les poids. Un grand modèle MoE nécessite une VRAM importante même lorsqu'une fraction seulement des paramètres est active par jeton.

Prochaines étapes

• Encapsulez la boucle d'agent de l'étape 6 dans un véritable framework — voyez nos guides sur la création d'un agent IA avec le SDK Vercel AI et les agents typés avec le SDK OpenAI Agents, qui acceptent tous deux n'importe quel point d'accès compatible OpenAI.
• Ajoutez de l'observabilité pour voir l'utilisation des jetons et la latence — notre tutoriel d'observabilité LLM avec Langfuse se branche sur n'importe quel client compatible OpenAI.
• Comparez GLM-5.2 à d'autres modèles de frontière à poids ouverts avec notre guide développeur de MiniMax M3.

Conclusion

La véritable innovation de GLM-5.2 n'est pas seulement qu'il s'agit d'un modèle à poids ouverts rivalisant avec les systèmes de frontière fermés — c'est à quel point il est portable. Un seul modèle, exposé à travers les dialectes OpenAI et Anthropic, s'intègre à votre code TypeScript, à vos sessions Claude Code et à votre espace de travail Cline avec rien de plus qu'un changement d'URL de base. Et parce que les poids sont ouverts, le même code peut s'exécuter sur un serveur vLLM dans votre propre centre de données le jour où une exigence de conformité l'imposera.

Pour les équipes MENA en particulier, cette combinaison — qualité de codage de frontière, un sixième du coût et une voie crédible vers une souveraineté totale des données sur site — est ce qui rend GLM-5.2 digne d'être intégré à votre stack dès aujourd'hui. Commencez par l'API hébergée pour livrer vite, et gardez la recette d'auto-hébergement sous le coude pour les charges de travail qui l'exigent.