Timeouts de lecture passerelle OpenClaw et diagnostic de blocage en 2026 sur un Mac mini cloud

Les passerelles OpenClaw sur un Mac mini macOS 24/7 gèlent parfois sans crasher : Slack perd ses indicateurs de frappe, les tableaux de bord affichent « sonde RPC : ok », pourtant aucune réponse d'assistant n'arrive pendant plus de 90 secondes. L'exploitation étiquette souvent ces incidents comme pannes modèle alors que la cause est un timeout de lecture attendant des octets qui ne se terminent jamais — ou une session TLS semi-ouverte après un à-coup Wi-Fi. Ce runbook sépare les blocages de lecture des vagues HTTP 429, fixe des baselines curl -m reproductibles et relie la backpressure des canaux aux journaux passerelle. Associez-le à 429 fournisseur et Retry-After lorsque les réponses arrivent mais exigent un recul, et à diagnostic doctor passerelle pour l'authentification, le bind et les ports. Si un proxy inverse précède la passerelle, lisez durcissement proxy et tunnel afin d'aligner les timeouts d'inactivité de bout en bout. Enfin reliez la limitation de charge locale à budget jetons, limitation d'outils et concurrence : les tempêtes de retry aggravent souvent les stalls de lecture plus que le modèle lui-même.

Vous obtiendrez une matrice de décision, des valeurs de départ pour les timeouts, des conseils journaux macOS et une FAQ orientée ingénierie plateforme — avec des garde-fous financiers pour documenter toute hausse temporaire des plafonds.

Signaux que vous déboguez le mauvais mode de panne

Lorsque les tableaux restent verts côté RPC mais que les utilisateurs attendent, vous êtes probablement coincé dans des lectures applicatives, pas dans la mort de processus. Un autre indice est le flux JSON partiel : des jetons apparaissent 300 ms puis silence — l'amont s'est arrêté au milieu d'un chunk. Sans cette distinction, des journées partent sur le routage modèle alors qu'un timer idle du proxy est coupable.

Compteurs compatibles finance : timeouts de lecture par heure, durée moyenne de blocage, conversations abandonnées et tickets rouverts tagués « IA bloquée ». Sans ces quatre séries vous ne pouvez pas prouver qu'un changement de timeout a aidé. Fixez des seuils d'incident explicites pour calmer la communication.

Lors d'un incident, figez le développement fonctionnel : capturez des résumés tcpdump redactés et des identifiants TLS, puis annulez le dernier changement de timeout avant d'empiler de nouvelles expériences. C'est conservateur mais évite des configurations « boîte magique » qui ne marchent que le dimanche soir.

Documentez les hausses « brise-vitre » avec identifiants de ticket ; sinon les équipes augmentent silencieusement les plafonds aux lancements et s'étonnent des factures du dimanche. Une ligne de tableur par environnement listant connect, premier octet, idle et horloge murale permet aux auditeurs de comparer staging et production en moins de cinq minutes en bridge.

Formez le support à distinguer stalls de lecture et erreurs OAuth — courtes capsules et macros ticketing réduisent les escalades. Pointez vers doctor diagnostic pour que le niveau 1 exécute les mêmes contrôles que l'ingénierie.

Matrice : timeout de lecture vs 429 vs DNS

Symptôme	classe probable	première sonde
HTTP 429 avec Retry-After	limite de débit	suivre le guide 429
pas de ligne de statut > temps de connect	stall lecture	curl -m progressif vers l'URL amont
NXDOMAIN immédiat	DNS	dig +trace depuis l'hôte passerelle

Timeouts initiaux qui survivent aux audits

Côté client de départ : connect 5 s, lecture premier octet 45 s pour modèles bavards, idle chunk streaming 12 s, horloge murale par tour utilisateur 180 s avant de renvoyer un lien de transfert structuré. Ce sont des points de départ auditables, non des dogmes immuables.

Plafonnez les retries après timeout de lecture à 2 par message utilisateur sauf incident déclaré côté statut fournisseur. Combinez avec budget jetons et limitation pour que les espaces de travail parallèles ne se poussent pas mutuellement dans des boucles de retry.

Quand le fournisseur annonce une maintenance, baissez la concurrence de 20 % à partir de 15 minutes avant — sinon les retries qui se chevauchent amplifient exponentiellement les stalls. Versionnez les tables de timeout dans Git ; l'astreinte ne doit jamais deviner quelles constantes étaient actives pendant un incident.

Pour les environnements réglementés, faites passer les hausses de fenêtres de lecture par le même CAB que les règles pare-feu lorsqu'elles augmentent aussi le nombre de flux simultanés possibles.

Recettes de reproduction curl

# Monter les plafonds par étapes pour trouver où l'amont bloque
curl -sS -o /dev/null -w '%{http_code} %{time_connect} %{time_starttransfer}\n' \
  -H "Authorization: Bearer $TOKEN" \
  -m 10 https://api.example.com/v1/models
curl ... -m 30 ...
curl ... -m 60 ...

Exécutez la même séquence depuis l'hôte passerelle et depuis un bastion ; des time_starttransfer divergents pointent vers le réseau plutôt qu'OpenClaw. Capturez -w '%{remote_ip}' pour épingler le DNS sur le POP anycast attendu pendant les brownouts.

Pour les points de terminaison streaming, ajoutez --no-buffer et passez la sortie dans pv afin de voir si les chunks cessent parce que le serveur s'arrête ou parce que le terminal local backpressure le tuyau — cela épargne des heures aux tickets « rien ne s'affiche » du support. Lorsque les proxys d'entreprise retirent le chunked encoding, curl peut tamponner jusqu'à EOF — reflétez exactement la bibliothèque HTTP de la passerelle (HTTP/1.1 vs HTTP/2) sinon les reproductions ne valent rien.

Archivez les sorties curl avec horodatage et SHA Git de la passerelle ; les post-mortems sans artefacts survivent rarement au prochain trimestre.

macOS, launchd et pression disque

launchd hérite de défauts résilients, mais un debug verbeux peut bloquer les écritures lorsque le volume racine tombe sous 12 % libre — les stalls ressemblent à des blocages modèle pendant que le processus attend write(). Surveillez diskutil apfs listVolumeGroups pendant les incidents : des destinations Time Machine locales dans le même groupe de volumes volent des IOPS au volume journaux sans alerter le CPU.

La reprise de session TLS peut masquer des gels de lecture intermittents : faites tourner occasionnellement des clients diagnostiques pour forcer de nouvelles poignées de main lorsque vous bissectez un fournisseur. Cela s'aligne sur les parcours doctor décrits dans diagnostic doctor passerelle, qui séparent auth et bindings.

Si l'achat matériel traîne, louez un Mac mini cloud : les hôtes Apple Silicon MacHTML coûtent typiquement environ 16,9 $/jour avec SSH/VNC pour captures live. Mariez le réglage des timeouts de lecture aux limites de fork locales — voir limitation et jetons pour les plafonds de concurrence contre les tempêtes de retry.

Proxys : les timeouts idle doivent s'accorder amont et aval — proxy et tunnel couvre les pièges nginx/Envoy typiques qui finissent en « passerelle bloquée ».

Surveillez aussi les limites de descripteurs de fichiers : un LaunchAgent ouvrant trop de flux parallèles produit les mêmes symptômes qu'un fournisseur lent.

UX canal pendant les stalls

Les utilisateurs Slack et Teams tolèrent l'attente si le texte explique pourquoi. Envoyez un modèle après 8 s sans premier jeton, un second après 45 s et un lien de transfert final après 120 s. Évitez les stack traces brutes dans les canaux — elles peuvent fuiter des noms d'hôte internes.

Pour les équipes multilingues, localisez les messages d'attente selon l'en-tête de locale de l'espace. L'analytique produit doit séparer « pas de premier jeton » de « flux arrêté au milieu de la réponse » ; de mauvais entonnoirs envoient l'ingénierie chasser OAuth au lieu de comparer des tables de timeout.

Les pages de statut publiques gagnent un badge synthétique passant au jaune lorsque les sondes dépassent 2× la baseline time_starttransfer — avant que les erreurs utilisateur ne bougent, la communication peut devancer Twitter.

Recherche UX : testez A/B textes d'attente courts vs longs ; parfois une phrase avec estimation suffit, parfois il faut un lien documenté vers le support humain.

Télémétrie et SLO

Exportez des histogrammes de time_starttransfer depuis les sondes synthétiques et comparez aux métriques passerelle live — une divergence au-delà de 25 % suggère une dérive de politique locale. Étiquetez les sondes avec un user-agent dédié pour que les équipes pare-feu puissent whitelister sans ouvrir de larges fenêtres de scrape.

Lorsque les sondes réussissent mais que le trafic live échoue, comparez MTU et fenêtres TCP entre sous-réseau de sondes et pair VPC production — une MSS mal dimensionnée crée encore des « mystères bloqués » en 2026 comme il y a dix ans. La sécurité peut demander si des fenêtres de lecture plus longues augmentent la surface d'attaque ; couplez toute hausse avec moins de flux concurrents max par locataire.

Alertez lorsque le taux de timeouts de lecture dépasse 4× la baseline sept jours pendant plus de 10 minutes — appelez le réseau avant le routage modèle. Conservez des journaux d'audit structurés 90 jours avec identifiants de corrélation reliant message utilisateur et identifiant de requête fournisseur.

Chaque trimestre, examinez manuellement les 35 attentes les plus longues ; le bucketing automatique étiquette encore mal les brownouts régionaux comme des bugs locaux. Annotez Grafana avec les fusions Git touchant les constantes de timeout pour lier les pics aux changements intentionnels.

Coordination fournisseur : lorsque les pages de statut affichent « latence élevée » sans panne dure, raccourcissez temporairement les timeouts idle streaming pour que les utilisateurs voient un texte de retry explicite plutôt que des spinners infinis — restaurez ensuite les valeurs précédentes dans les 4 heures via la checklist de retour liée au ticket.

FAQ

Un timeout de lecture est-il identique au 429 ?

Non — 429 inclut une ligne de statut ; les stalls de lecture finissent sans réponse terminale.

Faut-il augmenter les timeouts en premier ?

Seulement avec ticket, plafond et minuteur de retour arrière.

Pourquoi répéter sur un Mac mini physique ?

TLS macOS, launchd et comportement disque diffèrent du CI Linux.

Le Mac mini Apple Silicon reste la plateforme de répétition la plus fidèle pour le travail sur timeouts OpenClaw : thermique prévisible pendant de longues captures, intégration Keychain native et piles réseau alignées sur les passerelles de production. MacHTML loue des Mac mini cloud avec SSH/VNC pour que les équipes plateforme valident politiques de timeout de lecture, sondes doctor et limiteurs sans nouveau cycle d'investissement — provisionnez pour l'exercice, capturez les preuves, déprovisionnez au vert.