En 2026, faire tourner un seul modèle premium sur une passerelle OpenClaw macOS mène souvent à l’arrêt quand Anthropic renvoie HTTP 429, OpenAI 503, ou qu’une panne régionale invalide votre unique clé API. La bascule modèle et le routage fournisseurs explicite transforment ces stops durs en dégradations bornées : chaîne secondaire documentée, schémas d’outils compatibles, budgets de retry respectant Retry-After. Ce tutoriel montre la chaîne dans ~/.openclaw/openclaw.json, les secrets hors git, et la validation via openclaw doctor avant les plist LaunchAgent de production. Associez-le à la discipline 429, aux profils JSON et environnement, aux disjoncteurs amont et aux diagnostics doctor.
Vous repartez avec une matrice de décision, un squelette de configuration copiable, des garde-fous numériques (max. 3 fournisseurs sur le chemin chaud, 30 s par tentative, 120 s par tour) et une checklist staging sur un Apple Silicon Mac mini loué à environ 16,9 $/jour selon la grille MacHTML.
Symptômes nécessitant une bascule
Les canaux restent sur « réflexion… » pendant que les logs répètent des erreurs fournisseur. Les appels d’outils bloquent en milieu de tour car la passerelle a épuisé les retries contre un seul vendeur. La finance voit des factures surprises quand on échange manuellement les clés à 2 h du matin au lieu d’une route secondaire testée—le signal est le routage, pas la qualité du modèle.
La bascule n’est pas « toujours le modèle le moins cher ». C’est une dégradation contrôlée : premium pour le client, milieu de gamme pour les audits HTML/CSS internes, Ollama local uniquement pour des résumés non destructifs quand le cloud est down—chaque niveau documenté et sondé.
Principes de conception de la chaîne
Chemin chaud court : au plus trois fournisseurs, test hebdomadaire avec le même schéma d’outils que vos agents HTML/CSS. Si la production exige des éditions de fichiers, ne pas fail-open vers un modèle sans outils write—préférer des résumés en lecture seule. Logger fournisseur et correlation id par tour pour attribuer les pics de coût.
Séparer les chaînes staging et production même sur le même matériel ; une coquille dans le JSON staging ne doit pas envoyer la production vers un modèle local expérimental.
Squelette de routage openclaw.json
Placer le routage à côté—pas dans—le HTML suivi par git. Noms de fournisseurs dans openclaw.json, clés API dans ~/.openclaw/.env avec chmod 600. Documenter l’ID modèle primaire, fallbacks ordonnés, timeouts et plafonds de coût optionnels.
{
"agents": {
"default": {
"model": {
"primary": "anthropic/claude-sonnet-4-20250514",
"fallbacks": [
"openai/gpt-4.1",
"google/gemini-2.5-pro"
]
},
"providers": {
"anthropic": { "timeoutMs": 30000 },
"openai": { "timeoutMs": 30000 },
"google": { "timeoutMs": 45000 }
}
}
}
}Le fragment est une aide structurelle—les noms de champs évoluent entre versions OpenClaw, différez avant collage. Puis openclaw doctor et une sonde de chat d’une ligne par fournisseur.
Matrice de choix des fournisseurs
| Niveau | Usage | Risque |
|---|---|---|
| Primaire (premium) | Tours Slack/Telegram client | Quota épuisé aux lancements |
| Secondaire (milieu) | Audits internes, correctifs non urgents | Dérive de schéma d’outils |
| Local (Ollama) | Résumés lecture seule si cloud down | Profondeur inférieure au cloud |
| Désactivé | Outils destructifs en panne | Pression « activer quand même » |
429, 503 et Retry-After
La bascule ne remplace pas le respect des limites. Si le primaire renvoie 429, honorer Retry-After jusqu’au plafond documenté (souvent 30 secondes en chat), puis passer au secondaire. Pour les tempêtes 503, coupler le routage au disjoncteur de passerelle. Tables de backoff : article 429.
Plafonner le tour près de 120 secondes ; message de dégradation lisible plutôt que cinq fournisseurs en boucle.
Compatibilité des schémas d’outils
Tous les modèles doivent accepter les mêmes définitions JSON publiées par la passerelle. Un secondaire qui rejette browser casse les pipelines HTML/CSS. Avant les fallbacks production, trois appels figés en staging : lire fichier, écrire patch, lister répertoire.
Sans vision sur le secondaire alors que le primaire utilise des images, retirer les parties image ou router les tâches visuelles uniquement vers un secondaire compatible.
Sondes doctor et chats synthétiques
Après modification du routage, joindre openclaw doctor --json au ticket. Messages synthétiques pour forcer chaque fallback : révoquer la clé primaire en staging, confirmer la réponse secondaire en 10 secondes, restaurer, vérifier le primaire sans redémarrage. Surveiller les labels fournisseur dans les logs.
Aligner les sondes avec les profils staging/production—pas de secrets production sur le portable développeur.
Checklist de déploiement staging
- Exporter les empreintes de
openclaw.jsonet.env(sans secrets) vers un stockage ignoré par git. - Clés secondaires avec alertes de facturation séparées.
- Tests fumée d’outils par fournisseur sur le port passerelle staging.
- Simuler une panne primaire ; confirmer le fallback dans le SLA.
- Promouvoir le plist LaunchAgent après 24 heures de métriques staging propres.
- Documenter le rollback : JSON seul +
launchctl kickstart.
FAQ
Mêmes définitions d’outils pour la bascule ?
Oui—tester les appels d’outils sur chaque fournisseur avant la chaîne.
La bascule corrige-t-elle le 429 automatiquement ?
Seulement si le secondaire a un quota séparé ; sinon backoff requis.
Fréquence de doctor ?
À chaque changement de routage ou secret ; en production, cron hebdomadaire.
Louer un Apple Silicon Mac mini via MacHTML aligne les tests de routage sur les mêmes builds WebKit/Node que vos dirigeants—pas un conteneur Linux. SSH pour les sondes, VNC si Keychain bloque. Veille souvent 6–12 W ; une semaine de répétition coûte moins qu’une nuit « provider error » sur tous les canaux.
Tarif public vers 16,9 $/jour. Arrêter l’instance après l’exercice ; les tables de routage restent dans git sans CapEx sur 36 mois.
Répéter la bascule modèle OpenClaw sur macOS réel
Louez un Mac mini cloud pour valider chaînes fournisseurs, fallbacks 429 et sondes doctor avant de promouvoir les LaunchAgents en production.