Les passerelles d’agents qui fan-out vers des outils HTTP finissent par rencontrer des échecs qu’aucun backoff exponentiel inline ne répare : charges utiles empoisonnées, dérive de contrat entre le schéma JSON de la passerelle et le microservice amont, ou pannes qui dépassent tout budget de relance raisonnable. En 2026, les déploiements OpenClaw matures isolent ces échecs terminaux dans une file de lettres mortes (DLQ) afin que les opérateurs inspectent, modifient et rejouent les appels sous garde humaine ou politique sans bloquer le chemin chaud. Cet article décrit quand les messages atterrissent en DLQ, comment concevoir rétention et partitionnement, comment le rejeu s’aligne sur les clés d’idempotence et la déduplication, comment les disjoncteurs cadrent les vidages, quelles métriques Prometheus prouvent la santé de la file, et comment la journalisation avec rédaction préserve la valeur forensique.
Cadrage économique : répéter les politiques DLQ sur un Mac mini dédié chez MacHTML pour environ 16,9 $ par jour coûte moins cher qu’un incident de production où un double rejeu facture deux fois un client ou altère des enregistrements CRM partagés.
Pourquoi une DLQ au-delà des relances
Les relances supposent une faute transitoire qui disparaît en millisecondes à secondes. Les intégrations d’outils contredisent constamment cette hypothèse : une API partenaire renvoie 422 parce qu’un champ a été renommé dans l’OpenAPI pendant la nuit, ou un outil de recherche vectorielle répond 500 douze minutes durant un rééquilibrage de shard. Si la passerelle garde ces appels dans le pool de workers, la latence du streaming modèle explose, les blocages utilisateur augmentent, et la pression mémoire monte car chaque appel coincé retient des tampons et des traces.
La DLQ déplace les échecs terminaux vers une voie plus lente où l’on inspecte les charges par lots, corrige les schémas ou met les locataires en quarantaine. Règle pratique en 2026 : plafonner les relances inline à trois tentatives en 2,5 secondes pour les lectures idempotentes, puis DLQ si la classe d’erreur est inconnue ou si l’amont signale explicitement l’absence de réessayabilité. Les écritures sans clé d’idempotence ne doivent jamais boucler à l’infini ; elles doivent échouer vite vers le planificateur avec une erreur structurée, ou atterrir en DLQ si la politique exige une validation humaine avant d’exposer l’échec au modèle.
Le motif fan-out d’OpenClaw amplifie le risque : une étape de planification peut déclencher six outils. Si chacun déraille, il faut des partitions DLQ par outil pour qu’un CRM empoisonné n’empêche pas le vidage d’un calculateur sain partageant le même cluster Redis.
Messages poison et échecs de schéma
Les messages poison sont des charges qui ne réussiront jamais sans changement de code ou de données : arguments rejetés par la validation JSON Schema à la passerelle, URL bloquées par la politique de sortie, ou noms d’outils pointant vers une capacité retirée d’un déploiement canary. La passerelle doit les classer non réessayables immédiatement, attacher un failure_class lisible machine comme SCHEMA_REJECT ou EGRESS_DENY, et mettre en file avec l’identifiant de trace d’origine pour corréler les tickets support.
La dérive de schéma mérite un traitement spécial : épingler chaque enqueue avec tool_contract_version: 20260425.3 pour que les opérateurs de rejeu sachent si l’échec est antérieur à un correctif déployé à 14:00 UTC. Avec des versions hebdomadaires, une rétention de 14 jours et 500 Mo par partition est courante ; au-delà, expiration automatique avec métrique de tombe pour prouver la suppression aux équipes finance tout en comptant les charges expirées non lues.
Pour des lots partiellement empoisonnés — cinq lignes sur cent échouent à la validation — créer une entrée DLQ par ligne plutôt que rejeter tout le lot, afin de cibler le rejeu et préserver le débit des quatre-vingt-quinze enregistrements sains.
Champs d’enveloppe DLQ attendus
Chaque message DLQ doit porter une enveloppe distincte des arguments bruts de l’outil. Champs minimum pour survivre aux astreintes : tenant_id, request_id, idempotency_key ou null explicite, tool_name, tool_version, first_seen_at, last_error_code, retry_count, failure_class, et une copie rédigée des en-têtes HTTP sous plafond 4 Ko. Au-delà de 256 Ko de charge, pointer vers un corps compressé externe pour garder le courtier réactif.
{
"dlq_version": 1,
"request_id": "req_9f2c…",
"idempotency_key": "idem_7a91…",
"tool": {"name": "crm_search", "contract": "20260425.3"},
"failure_class": "UPSTREAM_TIMEOUT",
"retry_count": 3,
"last_http_status": 504,
"first_seen_at": "2026-04-25T01:12:04Z",
"traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}Ne stocker les secrets que comme références de coffre, jamais en jetons inline. Si l’appel original transportait un artefact OAuth de rafraîchissement, le remplacer par vault://tenant/42/oauth et laisser les workers de rejeu réhydrater à l’exécution pour éviter qu’un snapshot disque ne devienne une fuite d’identifiants.
Sécurité du rejeu et contrats d’idempotence
Rejouer sans idempotence, c’est envoyer deux fois les mêmes factures. Les rejeux doivent soit réutiliser la clé d’origine dans son TTL — souvent 24 à 72 heures pour les outils financiers — soit en émettre une nouvelle avec métadonnées supersedes_request_id pour signaler une seconde tentative intentionnelle. Voir l’article idempotence pour les motifs Redis TTL et stockage sans collision.
Limiter manuellement les vidages : démarrer à un message par seconde par dépendance amont, puis accélérer si le taux d’erreur reste sous 0,5 % pendant cinq minutes. Coupler avec des plafonds de concurrence par opérateur pour éviter que deux ingénieurs de garde ne doublent accidentellement le débit pendant un incident.
Pour les outils mutateurs, exiger un drapeau d’approbation à deux personnes dans l’enveloppe avant dequeuer, comme pour les migrations de base. Les rejeux CI automatisés utilisent un compte de service dédié avec rotation de clés tous les 30 jours et des métriques à cardinalité plus élevée, isolées des vidages humains.
Coordonner les vidages avec les disjoncteurs
Ne jamais vider une DLQ pendant qu’un disjoncteur amont est ouvert, sauf pour réempoisonner un service convalescent. Playbook : surveiller les jauges de disjoncteur, attendre des sondes semi-ouvertes réussies comme dans le guide disjoncteur, puis activer un job de vidage qui se met en pause si le disjoncteur se rouvre. Certaines équipes codent une machine d’états : les transitions DRAIN_PAUSED_BREAKER_OPEN déclenchent un webhook Slack et incrémentent dlq_drain_paused_total.
Quand l’amont renvoie 429 avec Retry-After, traiter les vidages DLQ comme du trafic client : respecter l’en-tête plus un jitter jusqu’à 250 ms pour éviter les essaims entre workers de rejeu.
Compteurs Prometheus et SLO de retard
Exporter au minimum : jauge dlq_depth par partition d’outil, dlq_ingress_total{failure_class}, dlq_replay_success_total, dlq_replay_failure_total, histogramme dlq_age_seconds du premier échec au rejeu réussi, et dlq_expired_total pour la conformité. Brancher sur les tableaux déjà construits après l’article Prometheus.
Exemple de SLO : 95 % des messages DLQ sont rejoués avec succès ou reçoivent une disposition opérateur explicite sous 48 heures. Alerter lorsque la profondeur dépasse 10 000 messages pour un locataire en quinze minutes, signe habituel d’une panne amont déguisée en erreur client.
Journaux, PII et pistes d’audit
Les opérations de rejeu sont sensibles : elles réexécutent la logique métier. Journaliser chaque rejeu avec identité opérateur, horodatage, anciennes et nouvelles clés d’idempotence, et différence rédigée des mutations d’arguments. Suivre les motifs de l’article journalisation et logrotate pour que les disques des petits Mac mini ne débordent pas quand un vidage incontrôlé génère des gigaoctets de JSON.
Sous macOS, des rotations newsyslog à 50 Mo avec sept générations sont fréquentes pour les journaux de passerelle ; aligner la rotation sur la rétention DLQ pour que les enquêteurs corrélationnent encore lorsque les messages expirent du courtier.
Matrice : file de relance, DLQ, outbox
| Préoccupation | File de relance chaude | DLQ | Outbox transactionnelle |
|---|---|---|---|
| Budget latence | Millisecondes | Minutes à jours | Borné par commit DB |
| Revue humaine | Rare | Attendue | Optionnelle |
| Garanties d’ordre | Best effort par clé | FIFO par partition | Fort avec writer unique |
| Idéal pour | Rafales 5xx transitoires | Poison, longues pannes, attentes policy | Effets exactement une fois vers votre propre DB |
Runbook numéroté
- Vérifier que le pic de profondeur n’est pas un bug de scrape en comparant l’UI du courtier à
dlq_depth. - Échantillonner cinq charges ; si elles partagent
failure_class, ouvrir un ticket racine unique. - Valider l’état des disjoncteurs et les budgets d’erreur avant d’autoriser les vidages.
- Démarrer le vidage à un message par seconde ; surveiller
dlq_replay_failure_total. - Après vidage, capturer les métriques et les joindre au dossier d’incident.
FAQ
DLQ et file de relance doivent-elles partager un cluster Redis ?
Elles peuvent partager le matériel mais doivent utiliser des espaces de clés et politiques mémoire distincts pour qu’un backlog DLQ n’évince pas les métadonnées de relance chaude.
Quelle durée de vie pour les clés d’idempotence ?
Alignez sur la fenêtre de litige la plus longue attendue ; beaucoup d’équipes B2B choisissent 72 heures pour les outils et 30 jours pour la facturation.
Les agents peuvent-ils rejeu automatiquement sans humain ?
Seulement pour les outils en lecture seule avec idempotence prouvée et limites de débit ; sinon exiger une intention opérateur explicite pour éviter les boucles autonomes.
Livrer des flux DLQ fiables en 2026, c’est autant une question d’observabilité et de répétitions façon macOS que de mécanique de files. Un Mac mini loué chez MacHTML pour environ 16,9 $/jour offre le macOS natif, du matériel silencieux et la marge Apple Silicon pour faire tourner binaires de passerelle, courtiers et sidecars Prometheus pendant que vous validez scripts de vidage, minuteurs LaunchAgent et journaux rédigés avant de toucher le trafic de production.
Répéter les vidages DLQ OpenClaw sur Mac mini cloud
Exécuter des passerelles adossées à un courtier avec des quotas disque réalistes, valider logrotate et répéter les exercices d’incident sur Apple Silicon dédié avant de modifier les règles de rejeu en production.