Les modèles sont optimistes ; l’infrastructure ne doit pas l’être. Si vous laissez un agent invoquer shell, HTTP ou dépôt sans garde-fous de schéma ni timeouts stricts, une seule boucle défectueuse peut saturer les workers, remplir les disques ou marteler une API tierce. La solution est répétable et presque ennuyeuse : valider les arguments avant toute exécution, couper les appels trop longs, ouvrir le disjoncteur après des modes d’échec prévisibles, et réutiliser un seul modèle de retry partout où un effet de bord compte.

Ce guide suppose qu’OpenClaw est installé sur le Mac distant et qu’une passerelle en boucle locale sert déjà l’IDE ou des agents sans tête. Pour l’orientation produit, partez de l’accueil ; pour les chemins d’installation, les jetons et les bases de la passerelle, utilisez le centre d’aide · Guide OpenClaw. Pour héberger durablement passerelle, pulls de modèles et bacs à sable d’outils sur un nœud Mac mini M4 dédié, comparez les régions sur la page d’achat (parcours possible sans connexion pour parcourir les offres). La disposition décrite ici prolonge notre playbook pont IDE, sandbox minimal, diff et sonde de santé : gardez le même découpage dépôt en lecture seule et répertoire scratch inscriptible afin que journaux, traces de retry et dumps de validation ne polluent jamais l’arbre des sources.

Passerelle et répertoire des skills

La reproductibilité commence par des chemins que toute l’équipe peut copier mot pour mot. Sur le Mac distant, regroupez l’état de la passerelle sous une racine unique, typiquement ~/.openclaw (configuration, jetons, pointeurs de cache local), et versionnez les skills sous ~/openclaw-skills/<nom-du-skill>/ avec un manifeste skill.yaml ou skill.json, plus des sous-dossiers optionnels schemas/ et scripts/. Réservez ~/openclaw-scratch/ aux journaux structurés, charges temporaires et sorties de sondes — jamais à la racine Git du projet applicatif.

  • Un manifeste par skill. Déclarez noms d’outils, points d’entrée, politiques par défaut et références vers des fichiers JSON Schema ; les revues de code peuvent ainsi différ le comportement comme du code applicatif.
  • Secrets à part. Jetons en fichiers 0600, référencés via OPENCLAW_TOKEN_FILE ; le manifeste ne contient que des chemins, pas de secrets en clair.
  • launchd ou gestionnaire de processus. Lancez la passerelle avec KeepAlive, rotation des logs vers ~/openclaw-scratch/logs/gateway.log, et variables d’environnement qui pointent explicitement vers skills et scratch — archivez le plist ou l’unité dans le même dépôt que les manifestes.

Après tout changement d’arborescence, exécutez openclaw doctor --json > ~/openclaw-scratch/probe/doctor-last.json pour figer une ligne de base avant d’affiner les outils. Cette étape prend quelques secondes mais évite des heures de « ça marchait sur ma machine » lorsque l’environnement du service diffère du shell interactif.

Exemple de validation JSON Schema

Attachez un objet inputSchema à chaque outil que le modèle est autorisé à appeler. Privilégiez JSON Schema Draft 2020-12 ou Draft-07 selon ce que votre build OpenClaw embarque comme validateur. La validation doit s’exécuter avant tout sous-processus ou client HTTP, et les échecs doivent renvoyer une erreur lisible par machine — nom de champ, type attendu, contrainte violée — que le modèle peut corriger dans l’itération suivante.

Exemple : un outil « récupérer un ticket » qui ne doit accepter ni URL arbitraires ni libellés illimités :

{ "name": "linear.fetch_issue", "description": "Récupère un ticket Linear par identifiant stable", "inputSchema": { "type": "object", "additionalProperties": false, "required": ["issueId"], "properties": { "issueId": { "type": "string", "pattern": "^[A-Z]{2,10}-[0-9]+$", "maxLength": 32 }, "includeComments": { "type": "boolean", "default": false } } } }

Règles opérationnelles qui épargnent des semaines de débogage : additionalProperties: false sur les objets exposés au modèle, plafonds maxLength sur les chaînes, maxItems sur les tableaux, et enum pour les modes plutôt que du texte libre. Stockez les schémas volumineux sous ~/openclaw-skills/linear/schemas/issue.fetch.json et référencez-les depuis le manifeste lorsque le JSON inline devient illisible. Lorsqu’un appel échoue à la validation, journalisez tool, correlationId et le chemin d’erreur du validateur — sans logger de secrets bruts susceptibles d’apparaître dans des charges rejetées.

Paramètres de timeout et de disjoncteur

Les timeouts sont des fusibles : ils empêchent un seul outil de bloquer indéfiniment le pool de workers. Le disjoncteur (circuit breaker) protège les séquences d’appels défectueux contre une dépendance aval déjà en panne. Exprimez les deux dans le manifeste du skill (ou un policies.yaml partagé) pour que chaque outil hérite de valeurs par défaut et ne surcharge que ce qui est nécessaire.

  • executionTimeoutMs — plafond temps réel sur le corps de l’outil après validation réussie. Point de départ indicatif : 8–30 s pour les helpers HTTP, 60–120 s pour des parcours dépôt bornés, et nettement moins pour des transformations CPU pures.
  • queueWaitMs (optionnel) — durée maximale qu’un appel peut attendre derrière d’autres avant que la passerelle réponde 503 tool_backpressure ; limite l’effet de troupeau lorsque le modèle lance des dizaines d’appels en parallèle.
  • Fenêtre de disjoncteur — par ex. breaker.failureThreshold: 5 échecs consécutifs, ou breaker.errorRatePercent: 40 sur une fenêtre glissante de 60 s, puis breaker.openDurationMs: 30000 pendant laquelle les nouveaux appels échouent vite avec un code explicite breaker_open.
  • Probes semi-ouvertes — autorisez une invocation « canari » après la fenêtre ouverte pour que la récupération soit automatique sans redémarrage manuel de la passerelle.

Documentez les chiffres à côté de chaque outil lors des revues. Si les SLO en aval changent, mettez d’abord à jour les manifestes, puis redéployez la passerelle — évitez les variables d’environnement « mystère » connues d’un seul portable.

Repli exponentiel et politique de nouvelles tentatives

Les retries doivent vivre dans un modèle partagé, pas en boucles sleep copiées-collées dans chaque script. Utilisez un repli exponentiel avec jitter pour les lectures idempotentes, et des retries strictement bornés pour les écritures. Valeur de départ raisonnable pour une passerelle sur Mac distant appelant des API externes :

retry: maxAttempts: 4 initialDelayMs: 200 multiplier: 2.0 maxDelayMs: 8000 jitterRatio: 0.2 retryOnHttpStatus: [408, 425, 429, 500, 502, 503, 504] nonRetryOnHttpStatus: [401, 403, 404, 422]

Associez les retries à des clés d’idempotence sur les routes mutantes lorsque le fournisseur les supporte. Pour les outils sous-processus, évitez le retry automatique sauf si le manifeste marque l’outil idempotent: true et que le script distingue par codes de sortie une « infra transitoire » d’une « entrée invalide ». Émettez à chaque tentative une ligne de journal structurée : attempt, delayMs, errorClass, correlationId. Lorsque le disjoncteur est ouvert, sautez entièrement les retries et exposez l’état au modèle pour qu’il change de stratégie au lieu d’amplifier les dégâts.

FAQ : journaux et dépannage

Pic d’erreurs de validation après une montée de version de modèle. Les modèles récents ajoutent souvent des clés supplémentaires ou allongent les chaînes. Serrez le schéma progressivement : journalisez d’abord les clés inconnues en tête de document, puis passez additionalProperties à false une fois le trafic propre.

Timeouts déclenchés alors que le service aval semble sain. Vérifiez DNS et poignées TLS depuis le Mac lui-même, pas seulement depuis votre portable. Comparez executionTimeoutMs au p95 réel ; les démarrages à froid des voisins serverless dépassent souvent des défauts trop optimistes.

Le disjoncteur reste ouvert après rétablissement. Confirmez que les probes semi-ouvertes sont actives, que la classification d’erreur ne mélange pas 4xx et 5xx, et que l’horloge est synchronisée (un décalage casse les fenêtres glissantes). Inspectez les journaux pour un type d’erreur bloquant comme ECONNRESET qui ne disparaît jamais.

Les retries amplifient les limites de débit. Oubli de traiter 429 ou plafonds de backoff trop agressifs. Respectez Retry-After lorsqu’il est présent et réduisez maxAttempts pour les outils particulièrement burstés.

Les journaux indiquent un succès mais l’effet est absent. L’outil peut rendre la main avant la fin du travail asynchrone. Allongez le timeout pour couvrir tout le pipeline, ou scindez en deux outils « enqueue » et « poll status » avec des schémas distincts.

openclaw doctor réussit mais les outils échouent en production. Doctor vérifie souvent binaires et config, pas les identifiants vivants. Lancez un outil canari en mode dry-run, vérifiez que l’utilisateur de la passerelle lit bien les fichiers de jeton, et que les chemins skills dans l’environnement launchd correspondent à votre shell interactif.

En bref : normalisez passerelle, skills et scratch ; validez chaque outil avec JSON Schema avant exécution ; fixez timeouts par outil plus fenêtres de disjoncteur ; centralisez le repli exponentiel avec jitter ; propagez des identifiants de corrélation à travers validation, tentatives et transitions de disjoncteur. Cette pile transforme le « chaos agentique » en opérations que vous pouvez répéter sur un Mac distant — et transmettre au collègue suivant sans histoire orale.

Si ce playbook correspond à la façon dont vous voulez faire tourner des agents en 2026, placez la passerelle sur du matériel que vous maîtrisez : parcourez les Mac mini M4 cloud sur la page d’achat, consultez les plans sur la page tarifs, et conservez vos runbooks dans le centre d’aide. Lorsque vous serez prêt à provisionner, ouvrez la console depuis l’accueil et déployez les mêmes politiques d’outils centrées sur le schéma partout.