1. Points de douleur : 429 et timeouts sont des modes d’échec différents
(1) 429, c’est la sémantique des quotas : RPM/TPM, concurrence organisationnelle ou limites en périphérie. Augmenter aveuglément les timeouts amplifie souvent le problème en martelant le même seau. (2) Les timeouts sont la sémantique du chemin : DNS, TLS, timeouts inactifs du reverse-proxy ou démarrage à froid ; séparer les minuteurs de connexion et de lecture. (3) Silence de canal : parfois le modèle ne répond pas ; parfois il répond mais la couche canal perd les ACK ou retente mal—les logs doivent attribuer la faute au modèle, au Gateway ou au canal.
En exploitation, on regroupe trop souvent les symptômes visibles sous une seule étiquette. Associer code HTTP et horloge murale clarifie les récurrences. Le drapeau streaming doit figurer au ticket : il déplace fortement la distribution des timeouts.
2. Matrice de routage multi-fournisseur
La matrice ne choisit pas un fournisseur « gagnant » ; elle vise l’isolement des pannes. Le primaire optimise coût et qualité ; le secours optimise la survie. Documentez qui possède la rotation des clés, qui approuve les seuils de disjoncteur et quels canaux ne doivent jamais partager le même quota que l’automatisation batch.
| Stratégie | Quand elle aide | Risque |
|---|---|---|
| Base URL primaire/secours | Même surface compatible OpenAI, plusieurs régions ou vendeurs | Coût et fragmentation des logs ; conserver des request ids |
| Downgrade d’alias de modèle | Préserver la disponibilité sur la qualité aux pics | Dérive de style ; le mentionner dans le prompt système si besoin |
| Fenêtre de disjoncteur | Stopper le thrashing après rafales 429/5xx | Une mauvaise config vide le budget secours instantanément |
| Routage par canal | Support public vs outils internes sur des chemins distincts | Complexité opérationnelle ; tenir la table de routage comme source unique |
3. Runbook d’astreinte en cinq étapes
- Geler les preuves : fenêtre UTC, canal, nom du modèle, drapeau streaming ; capturer codes et extraits de logs.
- Sondes en couches :
openclaw status, santé passerelle, puis curl minimal vers la Base URL (ne jamais coller des secrets prod dans le chat). - Séparer 429 et timeout : 429 ⇒ quota/backoff ; timeout ⇒ réseau/proxy/lecture ; si mixte, réduire d’abord la concurrence.
- Configurer le failover : plafonds de retry, backoff exponentiel avec jitter, intervalle de récupération du disjoncteur, budget journalier du secours.
- Ligne de post-mortem : classer la cause (quota, DNS, proxy, rotation de clés, env launchd) et lier les horodatages.
4. Seuils citables
Remplacez par vos SLA fournisseurs et votre télémétrie :
- Si le même modèle enregistre cinq 429 consécutifs ou plus en 10 minutes et qu’un secours existe, basculer la route et alerter un humain sur la politique de quotas—pas de retry infini sur le primaire.
- Si les médianes de timeout de lecture dépassent 60 secondes avec erreurs TLS/DNS, inspecter les timeouts inactifs du proxy et la sortie avant la longueur de contexte.
- Sur un Gateway launchd Mac distant, si les exports shell diffèrent des
EnvironmentVariablesdu plist, traiter l’écart comme mode d’échec de premier ordre ; smoke après chaque changement.
5. Paramètres de retry et backoff
| Scénario | Faire | Éviter |
|---|---|---|
| 429 avec Retry-After | Respecter l’en-tête ; sans lui démarrer à 2s, plafonner vers 60s | Boucles fixes à 200 ms qui déclenchent des bannissements durs |
| 5xx sporadiques | Retries limités (≤3) avec jitter | Partager la même boucle infinie que pour le 429 |
| Timeout de connexion | Corriger DNS/TLS/proxy d’abord ; timeouts connexion et lecture indépendants | Un seul timeout à 300 s pour masquer un échec de handshake |
6. Lecture en couches des journaux openclaw
Quatre couches : (A) démarrage et configuration—Base URL et préfixes de clés attendus chargés ? (B) egress HTTP—codes et trace ids amont. (C) outils/MCP—outils lents qui dominent le temps réel ? (D) écriture canal—échecs d’ACK ou épuisement des retries. La plupart des « silences aléatoires » se réduisent à une couche une fois qu’on force la séparation.
| Signal | Suspect | Action |
|---|---|---|
| Rafale de 429 sur un champ modèle | Palier de quota ou concurrence | Réduire la concurrence, passer au secours, ou modèle plus petit |
| Timeout de handshake TLS | Sortie réseau ou boîte intermédiaire | Changer de chemin, vérifier l’heure système, retirer les mauvais proxys |
| HTTP 200 du modèle mais canal vide | Formatage canal ou chemin ACK | Comparer logs debug canal et logs d’émission Gateway |
7. Checklist Gateway Mac distant (spécifique launchd)
launchd hérite d’un environnement plus étroit que le shell de connexion. Toute mise à jour touchant des clés API ou des variables OPENCLAW_* est en deux temps : mettre à jour le plist, recharger le job, puis valider avec une sonde non interactive. Les bureaux distants diffèrent des serveurs colocalisés : économie Wi-Fi, coupures VPN et veille écran peuvent interrompre les démons longue durée si le rôle hôte Gateway n’est pas verrouillé.
| Vérification | Pourquoi c’est important |
|---|---|
| EnvironmentVariables du plist | Doit correspondre aux exports shell interactifs après upgrade |
| UserName / WorkingDirectory | Mauvais utilisateur ou workspace ⇒ échecs de permission silencieux |
| Rotation des logs et disque | Disque plein ressemble à des blocages mystérieux |
| Runbooks d’upgrade liés | Associer articles upgrade et passerelle silencieuse pour les smokes |
8. FAQ
Q : La qualité du modèle secours baisse—que voient les utilisateurs ? Indiquer clairement le mode dégradé dans le prompt système, revenir après rétablissement des quotas, journaliser les bascules.
Q : Réseau domestique, clés à l’étranger toujours en timeout ? C’est une classe de lien, pas la logique OpenClaw ; colocaliser le Gateway ou changer de région fournisseur.
Q : 401 brutal après upgrade ? Suivre l’article upgrade pour préfixes de clés et migration du state-dir avant des éditions de config parallèles.
9. Étude de cas : ralentissements d’après-midi dus au RPM, pas au canal
Une équipe exécutait le Gateway sur un Mac distant. Les utilisateurs blâmaient le canal de messagerie, mais les logs montraient des 429 denses entre 14h et 16h avec Retry-After croissant. Cause : pas de séparation entre trafic d’automatisation et humain sur le même palier RPM. Correctif : charges heartbeat sur petit modèle et clé séparée ; chat principal sur la clé principale ; disjoncteur 90 s vers le secours pendant les rafales. Les pannes sont passées d’heures à minutes.
Deuxième schéma : confondre latence d’outil et latence de modèle. Un appel MCP lent peut consommer tout le timeout de lecture et produire des messages vides. Séparer timeouts d’outil et de modèle stabilise l’expérience.
Croiser avec le guide webhooks GitHub : la sémantique HTTP (401/403/429) suit la même mentalité que les échecs de signature—chaînes de preuve, pas mysticisme.
Les runbooks battent le héroïsme : à 3h du matin, tout le monde exécute les mêmes étapes. Des seuils documentés débloquent les décisions de capacité, y compris louer du Apple Silicon dédié plutôt que partager un portable.
Si des LLM locaux tournent sur le même Mac, la mémoire et le Wi-Fi concurrent rendent les timeouts difficiles à reproduire ; un nœud distant dédié réduit les variables.
Tester les scripts de failover : synthétiser 429 et timeout en préproduction et vérifier qu’une boucle ne vide pas le budget secours d’un coup.
Le parallélisme multi-agents masque les plafonds RPM : chaque appel peut être 200 alors que le RPM agrégé déclenche 429—« certaines salles répondent, d’autres non ». Corriger avec des budgets de concurrence globaux dans la configuration et les tableaux de bord, pas seulement des taux de succès par requête.
Tenir une page listant chaque job d’automatisation qui touche la pile modèle, sa cadence et sa clé—sans cela, chaque vendredi après-midi ressemble à une chasse aux fantômes.
Les équipes redémarrent par habitude lorsque 429 et timeouts sont lus comme un bloc unique ; l’ordre en couches impose d’abord le HTTP modèle, puis le processus Gateway, puis l’écriture canal, puis la dérive launchd—répétable et sobre.
Multi-fournisseur : granularité de facturation et limites diffèrent ; des noms de modèles identiques peuvent donner des RPM effectifs différents. Inscrivez identifiants réels, propriétaires de clés, tolérance de rafale et plafonds journaliers dans la table de routage et exigez des revues de changement pour éviter les errances nocturnes.
Les Gateways sur Mac distant n’ont pas les mêmes hypothèses d’alimentation et de Wi-Fi qu’un portable de développeur ; pour du 24/7, intégrez paramètres d’énergie et stabilité réseau aux SLO et calibrez les timeouts comme pour un serveur fixe, pas un client itinérant.
Quand outils et MCP partagent le timeout de lecture avec le modèle, la cause se brouille ; des plafonds courts côté outil et une fenêtre de lecture légèrement plus longue côté modèle séparent journaux et triage incident.
Journaliser structurément les bascules failover accélère post-mortems et audits : qui a approuvé, quel seuil a été franchi, quand le primaire est revenu—traçabilité en une ligne.
Des tests de charge en préproduction avec 429 et timeouts injectés valident que les politiques de retry ne brûlent pas le contingent secours en une nuit ; les politiques prod ont besoin de traces, pas seulement de chiffres dans un wiki.
Les sous-agents parallèles créent des pics RPM agrégés invisibles requête par requête ; des tableaux par clé et profondeur de file globale plutôt que seulement par canal révèlent le plafond.
Les upgrades OpenClaw et l’auth appareil v2 peuvent déclencher des tempêtes 401 indépendamment du HTTP modèle ; placez le runbook d’upgrade dans le même dossier incident que ce playbook HTTP pour les astreintes de nuit.
10. Minimums d’observabilité
Suivre au minimum : taux de 429 par modèle, latence de bout en bout p95, nombre de bascules failover, taux d’échec d’ACK canal, nombre de redémarrages Gateway. Si les cinq se dégradent ensemble, suspectez quota ou panne amont régionale ; si seul l’ACK se dégrade, suspectez la couche canal.
| Symptôme | Vérifier d’abord | Atténuer |
|---|---|---|
| Un canal lent | Limites API canal et délai webhook | Throttler, file, ou changer le mode de connexion |
| Tous les canaux lents | Egress modèle ou CPU Gateway | Failover, scaler le nœud, limiter le débit |
| Pic post-upgrade | Dérive d’environnement et d’auth | doctor, checklist upgrade, rollback |
Sans APM, des pulls de santé planifiés et des comptages grep structurés suffisent si les séries temporelles sont alignées sur les fenêtres d’incident. Avec le durcissement de surface, n’exposez jamais publiquement des endpoints de debug—sinon votre chaîne de preuve devient vecteur d’attaque.
11. Conclusion : le failover est une discipline, pas de la chance
(1) Limites : clé unique, région unique, sans backoff finit toujours par heurter 429 et la latence de queue ; un portable qui dort sous un Gateway amplifie les timeouts.
(2) Pourquoi Apple Silicon distant aide : alimentation dédiée, surfaces d’environnement plus claires, meilleur ajustement pour Gateways 24/7 et retries en file.
(3) MACGPU : si vous voulez essayer sans friction de la capacité Mac distante pour découpler postes de travail et automatisation plus réunions, MACGPU propose des nœuds louables et de l’aide publique—le CTA ci-dessous mène aux offres sans login.
(4) Portail final : n’expédiez pas de politique de failover tant que la préproduction ne prouve pas qu’un mode de défaillance ne peut pas vider le budget secours d’un seul coup.