OpenClaw a été conçu pour être agnostique vis-à-vis du fournisseur, ce qui constitue son super-pouvoir discret. Il prend en charge les noms habituels comme OpenAI et Anthropic, mais vous permet également de connecter n'importe quelle API compatible OpenAI en tant que fournisseur personnalisé (OpenClaw docs, 2026). Ce simple choix de conception vous permet de conserver l'agent que vous appréciez tout en l'exécutant sur des modèles open-weight bien moins chers, dont le coût par jeton ne représente qu'une fraction des tarifs des modèles de pointe.
Le piège est que la configuration comporte une étape que presque tout le monde oublie, et une erreur à ce stade génère un message d'erreur qui égare les utilisateurs. Ce guide décrit en détail la procédure complète de configuration d'une API personnalisée OpenClaw : fonctionnement interne, configuration exacte à copier, le piège de la liste blanche et comment vérifier la connexion. Prévoyez environ cinq minutes.
Pourquoi configurer une API personnalisée OpenClaw ?
La raison honnête est le coût. Les outils agentiques comme OpenClaw renvoient le contexte accumulé à chaque étape de raisonnement, consommant ainsi 10 à 100 fois plus de jetons qu'une fenêtre de chat pour la même tâche (LeanOps, 2026). Ce multiplicateur explique pourquoi les factures d'agents grimpent si vite, les utilisateurs intensifs de modèles de pointe atteignant environ 13 USD par jour et par développeur actif (CloudZero, 2026). Une configuration d'API personnalisée OpenClaw s'attaque directement à la source de cette facture : le prix par jeton. Dirigez l'agent vers un modèle open-weight au lieu d'un modèle de pointe, et le coût unitaire baisse drastiquement, souvent de 70 % ou plus sur les tâches courantes, tandis que l'écart de qualité sur le code quotidien reste minime. Vous conservez le flux de travail OpenClaw que vous connaissez déjà et changez simplement le moteur qui répond aux requêtes. Il existe une seconde raison importante pour les équipes situées en dehors des régions desservies directement par un fournisseur donné. Un fournisseur personnalisé vous offre un moyen stable et compatible d'exécuter l'agent sans dépendre de la facturation, du calendrier de déploiement ou de la disponibilité régionale d'une seule entreprise.
Fonctionnement d'une configuration d'API personnalisée OpenClaw : les deux étapes oubliées
Avant de copier la configuration, comprenez le modèle utilisé par OpenClaw, car cela explique l'erreur que tout le monde rencontre. Un fournisseur personnalisé est défini en deux endroits, et les deux sont obligatoires.
Premièrement, vous décrivez le fournisseur lui-même dans la section models.providers : son URL de base, sa clé API, le protocole réseau (openai-completions pour tout endpoint compatible OpenAI) et la liste des modèles qu'il dessert. Deuxièmement, et c'est ce que les gens oublient, vous devez ajouter le modèle exact à la liste blanche dans agents.defaults.models, en utilisant l'identifiant complet nom-du-fournisseur/nom-du-modèle (OpenClaw docs, 2026). Définir un fournisseur ne rend pas ses modèles utilisables automatiquement. OpenClaw rejettera tout ce qui ne figure pas sur la liste blanche.
C'est voulu. La liste blanche vous permet de définir un large catalogue de fournisseurs et de modèles, mais de ne rendre accessibles que ceux que vous souhaitez réellement utiliser. Une fois que vous avez compris que les fournisseurs et la liste blanche sont des couches distinctes, le reste de la configuration de l'API personnalisée OpenClaw est purement mécanique.
Configuration d'une API personnalisée OpenClaw, étape par étape
L'exemple ci-dessous utilise Atlas Cloud comme fournisseur, car il expose un endpoint compatible OpenAI qui centralise les principaux modèles open-weight sous une seule clé. Cela simplifie la configuration et permet de changer de modèle ultérieurement sans rien enregistrer de nouveau. Les mêmes étapes s'appliquent à tout fournisseur compatible ; seuls l'URL de base et la clé changent.
Étape 1 : Obtenez votre endpoint et votre clé API
À la fin de cette étape, vous disposerez de deux éléments : une URL de base et une clé.
- Créez un compte auprès de votre fournisseur et accédez à sa section de clés API.
- Générez une clé avec une portée limitée à l'utilisation pour le code. Sur Atlas Cloud, sélectionnez Coding Plan comme type de clé, ce qui la lie au quota de code basé sur des crédits plutôt qu'à une facturation à l'usage générale.
- Notez l'URL de base. Pour les clients compatibles OpenAI comme OpenClaw, Atlas Cloud utilise https://api.atlascloud.ai/v1 (le suffixe /v1 est ici important).
Étape 2 : Exécutez l'assistant d'intégration (la méthode la plus rapide)
À la fin de cette étape, la connexion sera opérationnelle. Dans un terminal, lancez l'assistant guidé :
Bash1openclaw onboard
Suivez ensuite les invites : choisissez Yes, sélectionnez QuickStart, puis Custom Provider. L'assistant vous demandera l'URL de base de l'API (https://api.atlascloud.ai/v1), la clé API que vous avez copiée et l'ID du modèle. Assurez-vous de choisir le protocole OpenAI-compatible lorsque cela est demandé. Lorsque le message Verification successful s'affiche, l'endpoint fonctionne. Terminez en donnant à l'endpoint un ID et un nom convivial. L'avantage caché de l'assistant : il écrit à la fois la définition du fournisseur et l'entrée de la liste blanche pour vous, puis redémarre la passerelle, vous évitant ainsi le mode d'échec le plus courant.
Étape 3 : Ou modifiez directement le fichier de configuration
À la fin de cette étape, vous comprendrez ce que l'assistant a écrit, ce qui est utile pour ajouter d'autres modèles ultérieurement. La configuration se trouve dans ~/.openclaw/openclaw.json (OpenClaw docs, 2026). Définissez le fournisseur :
JSON1{ 2 "models": { 3 "mode": "merge", 4 "providers": { 5 "atlascloud": { 6 "baseUrl": "https://api.atlascloud.ai/v1", 7 "apiKey": "your-atlas-api-key", 8 "api": "openai-completions", 9 "models": [ 10 { "id": "zai-org/glm-5.1", "name": "glm-5.1", "contextWindow": 200000 } 11 ] 12 } 13 } 14 } 15}
Le paramètre "mode": "merge" préserve vos fournisseurs existants au lieu de les écraser. Pour les fournisseurs personnalisés, les champs comme reasoning, cost et maxTokens sont optionnels et utilisent des valeurs par défaut pertinentes ; vous n'avez donc pas besoin de tout remplir pour commencer.
Étape 4 : Ajoutez le modèle à la liste blanche
À la fin de cette étape, OpenClaw vous permettra d'utiliser le modèle. C'est l'étape que les gens sautent. Ajoutez l'identifiant complet à la liste blanche :
JSON1{ 2 "agents": { 3 "defaults": { 4 "models": { 5 "atlascloud/zai-org/glm-5.1": { "alias": "glm" } 6 } 7 } 8 } 9}
La clé est le nom de votre fournisseur suivi de l'ID du modèle exactement tel que vous l'avez défini. L'alias est simplement un raccourci que vous pouvez taper au lieu du chemin complet. Sans ce bloc, le fournisseur existe mais chaque requête est rejetée.
Étape 5 : Vérifiez votre configuration d'API personnalisée OpenClaw
À la fin de cette étape, vous saurez que tout fonctionne. Démarrez OpenClaw, sélectionnez votre modèle (ou son alias) et demandez-lui une tâche simple, comme expliquer un fichier. Une réponse normale signifie que les requêtes sont bien acheminées vers votre endpoint. Si vous voyez "model not allowed", revenez à l'étape 4 ; la clé de la liste blanche ne correspond probablement pas exactement au nom du fournisseur et du modèle. Si vous obtenez une erreur d'authentification, la clé est erronée ou contient un espace superflu. Si la connexion échoue, revérifiez l'URL de base et le suffixe /v1.
Choisir un modèle pour votre configuration d'API personnalisée OpenClaw
Le choix du modèle détermine les économies réalisées. La stratégie intelligente consiste à utiliser par défaut un modèle open-weight performant et peu coûteux pour le travail quotidien, et de réserver un modèle plus onéreux pour les tâches de raisonnement complexes. Les capacités sont réelles : sur SWE-Bench Pro, les principaux modèles open-weight obtiennent des scores proches de 70-80, contre environ 91 pour les meilleurs modèles de pointe (Codersera, 2026), un écart significatif sur les problèmes les plus ardus, mais faible pour le travail de développement et les refactorisations de routine. Sur une passerelle basée sur des crédits, chaque modèle possède un multiplicateur qui mappe l'utilisation des jetons aux crédits, ce qui facilite la comparaison des coûts relatifs :
| ID du modèle | Contexte | Multiplicateur entrée | Multiplicateur sortie | Économies approx. vs officiel |
|---|---|---|---|---|
| deepseek-ai/deepseek-v4-flash | 1M | 0.23 | 0.46 | ~50% |
| deepseek-ai/deepseek-v3.2 | 160K | 0.42 | 0.62 | ~55% |
| minimaxai/minimax-m2.5 | 200K | 0.65 | 2.18 | ~45% |
| moonshotai/kimi-k2.6 | 262K | 1.72 | 7.26 | ~45% |
| zai-org/glm-5.1 | 200K | 2.54 | 7.99 | ~45% |
Source : Règles de crédit du Coding Plan d'Atlas Cloud. Coût en crédits = jetons d'entrée × multiplicateur d'entrée + jetons de sortie × multiplicateur de sortie. Un choix par défaut judicieux : utilisez GLM-5.1 ou Kimi K2.6 pour le codage interactif, passez à DeepSeek V4 Flash pour les tâches à haut volume ou en arrière-plan, et n'utilisez un modèle de pointe que pour les rares tâches qu'un modèle open-weight ne peut pas accomplir. Comme tout est centralisé chez un seul fournisseur, basculer d'un modèle à l'autre ne demande qu'une modification d'une ligne sur l'alias.
Un seul endpoint pour OpenClaw, Claude Code et Codex
L'endpoint qui alimente votre configuration OpenClaw n'est pas limité à OpenClaw. La plupart des développeurs utilisent plusieurs agents, et diriger chacun vers un fournisseur différent signifie jongler avec des clés, des tableaux de bord et des factures distincts. Centraliser le tout sur un seul endpoint compatible OpenAI regroupe ces éléments dans un seul pool de crédits et un seul endroit pour changer de modèle.
Comme Atlas Cloud expose la même URL de base pour différents outils, la configuration OpenClaw ci-dessus possède des équivalents directs ailleurs. Claude Code lit son backend depuis ~/.claude/settings.json en utilisant ANTHROPIC_BASE_URL défini sur https://api.atlascloud.ai (note : pas de /v1 pour Claude Code spécifiquement). Codex utilise ~/.codex/config.toml avec base_url pointé vers https://api.atlascloud.ai/v1. Cursor, OpenCode et les clients de style Copilot utilisent le même endpoint /v1. Une seule clé, un seul budget, tous les outils.
Cette consolidation permet également de mieux contrôler les dépenses. Un plan qui actualise un quota de crédits quotidien à minuit impose un plafond structurel à une boucle d'agent qui s'emballerait, tandis que les packs de paiement à l'usage absorbent les pics occasionnels. Les plans Atlas Cloud commencent à 10 USD par mois, les packs à l'usage bénéficient d'une réduction de 41 %, et les mises à niveau en milieu de cycle sont proratisées ; un changement de palier ne coûte donc que la différence plutôt qu'un nouveau plan complet.
Erreurs courantes de configuration d'API personnalisée OpenClaw
La plupart des échecs de configuration proviennent d'une liste courte d'erreurs, et presque toutes se situent dans le fichier de configuration plutôt qu'ailleurs. Oublier la liste blanche. L'erreur la plus fréquente. Définir le fournisseur n'est que la moitié du travail. Si vous voyez "model not allowed", le modèle est absent de agents.defaults.models ou la clé ne correspond pas (haimaker, 2026). Clé de liste blanche mal assortie. La clé de la liste blanche doit être nom-du-fournisseur/nom-du-modèle en utilisant exactement les chaînes que vous avez définies. Une coquille dans l'une ou l'autre partie produit le même rejet que si vous l'aviez omise. Chemin d'URL de base erroné. Les outils compatibles OpenAI comme OpenClaw attendent le chemin /v1. L'omettre ou l'ajouter là où l'outil ne le souhaite pas provoque des erreurs de connexion. Écraser au lieu de fusionner. Si vous éditez la configuration à la main sans "mode": "merge", vous risquez d'effacer vos autres fournisseurs. Gardez le mode de fusion à moins que vous ne souhaitiez tout remplacer.
FAQ : Configuration d'API personnalisée OpenClaw
Est-il difficile de configurer une API personnalisée OpenClaw ?
Non. Le chemin le plus rapide est l'assistant openclaw onboard, qui écrit la définition du fournisseur et la liste blanche pour vous en environ cinq minutes. La méthode manuelle consiste en deux petites modifications JSON. Le seul obstacle conceptuel est de se souvenir que définir un fournisseur et ajouter un modèle à la liste blanche sont deux étapes distinctes.
Quelle est l'erreur la plus courante dans la configuration OpenClaw ?
Le rejet "model not allowed", qui signifie presque toujours que le modèle est absent de la liste blanche dans agents.defaults.models, ou que la clé nom-du-fournisseur/nom-du-modèle contient une erreur de frappe. Ne pas utiliser la liste blanche est la cause numéro un de cette erreur (haimaker, 2026), c'est pourquoi l'assistant d'intégration le gère automatiquement.
Quel modèle choisir pour ma configuration OpenClaw ?
Pour le codage interactif, un modèle généraliste performant comme GLM-5.1 ou Kimi K2.6 est un bon choix par défaut. Pour un volume élevé ou des tâches en arrière-plan, un modèle moins coûteux comme DeepSeek V4 Flash est judicieux. Gardez un modèle de pointe en réserve uniquement pour les tâches qu'un modèle open-weight ne peut vraiment pas résoudre.
Combien une configuration personnalisée peut-elle me faire économiser ?
Cela dépend du modèle, mais l'écart est important. DeepSeek V4 Flash coûte environ 0,14 USD par million de jetons d'entrée, contre plusieurs dollars pour les modèles de pointe (Codersera, 2026). Router le travail courant vers un modèle open-weight réduit donc souvent la facture par jeton de 70 % ou plus sans changer vos habitudes de travail.
Puis-je revenir à mon fournisseur initial plus tard ?
Oui. Les fournisseurs personnalisés sont additifs si vous conservez "mode": "merge", vos fournisseurs originaux restent donc définis. Passer de l'un à l'autre consiste simplement à sélectionner un modèle ou un alias différent dans OpenClaw, et vous pouvez supprimer un bloc fournisseur à tout moment.
Conclusion
Configurer une API personnalisée OpenClaw est l'un des changements les plus efficaces et rapides qu'un développeur puisse effectuer en 2026. L'agent reste le même, mais le backend et la facture changent. Définissez le fournisseur, ajoutez le modèle à la liste blanche, pointez vers une option open-weight, et vous conservez le flux de travail OpenClaw que vous connaissez tout en payant une fraction des tarifs des modèles de pointe. Si vous souhaitez centraliser cela sous une seule clé et un seul budget couvrant également Claude Code et Codex, vous pouvez le mettre en place via la console Coding Plan d'Atlas Cloud et changer de modèle dès que la nature de la tâche évolue.
