Les hooks de configuration OpenClaw

Un assistant devient utile dès que quelque chose d’extérieur peut engager la conversation. OpenClaw traite ce besoin avec des hooks entrants, une petite surface HTTP sur la passerelle qui accepte un corps JSON et le transforme en réveil ou en exécution d’agent. Cette surface est volontairement étroite, et presque chaque décision intéressante relève de la configuration plutôt que du code. Une décision mal prise ne produit généralement pas d’erreur, elle produit un chemin où la charge utile reste non fiable et où rien n’est prouvé sur l’expéditeur.

Le contrat HTTP

• Les points d’entrée restent fermés tant que le bloc des hooks n’est pas activé et doté d’un jeton partagé non vide, qui authentifie l’accès entrant et rien d’autre, si bien que le contenu reçu reste non fiable et que l’agent visé a toujours besoin de ses propres limites d’outils et d’espace de travail.
• L’authentification accepte un en-tête porteur ou un en-tête de jeton propre à OpenClaw, un jeton passé en paramètre de requête est rejeté avec un code 400 même lorsqu’un en-tête valide est présent, et après vingt tentatives échouées en soixante secondes les tentatives invalides suivantes de ce client sont freinées avec un code 429 et un délai de réessai, sans exemption pour la boucle locale.
• La limite ordinaire du corps de requête est de 256 Kio avec un délai de lecture de trente secondes, le chemin Gmail dérive une allocation plus large de sa limite d’octets par message, et la diffusion ne traite toujours que les deux cents premiers éléments d’un tableau, en abandonnant le reste avec un avertissement plutôt qu’un échec HTTP.
• Un appel direct à l’agent renvoie un identifiant d’exécution une fois l’admission faite, une admission qui n’aboutit pas en quinze secondes renvoie un code 503 et annule ce travail en file, et un code 200 prouve l’admission plutôt qu’un résultat de modèle ou un message livré.

La persistance contrôle la réutilisation de la conversation, pas les permissions des outils ni le bac à sable.

Sessions, mappages et transformations

La politique de session concentre l’essentiel du poids de la configuration. Une clé logique se résout depuis la requête ou le mappage correspondant, puis depuis une valeur par défaut configurée, et enfin depuis une clé de hook générée porteuse d’un identifiant unique, et une valeur par défaut configurée doit elle-même correspondre à la liste des préfixes autorisés. Le mode persistant sur le point d’entrée agent direct exige une clé explicite dans la requête, l’autorisation des clés fournies par l’appelant et une liste de préfixes non vide, tandis qu’un mappage persistant demande une clé de mappage stable ou une valeur par défaut. Les clés de mappage construites par gabarit exigent la liste de préfixes au moment de la configuration et l’autorisation des clés d’appelant au moment de la répartition, ce qui inclut le préréglage Gmail intégré tant qu’un mappage antérieur ne le remplace pas. Les requêtes qui partagent une même clé logique canonique sont sérialisées jusqu’à leur achèvement, même en mode isolé, si bien qu’une valeur par défaut fixe les ordonne et peut aussi pousser une requête plus tardive vers le délai d’admission pendant qu’une exécution antérieure est encore active. Les mappages sont évalués dans l’ordre du tableau avant les préréglages, la première correspondance possède la requête, y compris une transformation qui ne renvoie rien, et les mappages suivants ne sont pas essayés. Les gabarits peuvent lire des champs de la charge utile, des positions de tableau, des en-têtes, des valeurs de requête, le chemin et un horodatage ISO, les valeurs manquantes devenant des chaînes vides et les objets étant sérialisés en JSON. Les transformations sont du code de passerelle de confiance et non du code exécuté dans le bac à sable de l’agent, elles vivent sous un répertoire de transformations contraint qui rejette la traversée et les échappements par lien symbolique, et elles restent en cache jusqu’au rechargement de la configuration des hooks. Une transformation qui ne renvoie rien termine la requête avec un code 204 avant qu’une exécution, une tâche, une identité d’exécution ou un reçu d’audit n’existe.

Reprises et diffusion

• Les clés de rejeu sont lues dans un en-tête d’idempotence, puis dans un en-tête propre à OpenClaw, puis dans le champ de la charge utile, et seules les chaînes non vides d’au plus 256 caractères sont retenues, la même clé ne rejouant que pour le même jeton, le même chemin et les mêmes champs de répartition résolus.
• Une entrée de rejeu terminale expire cinq minutes après le règlement de l’achèvement et compte dans une limite de mille entrées terminales, les admissions en attente sont conservées sans expiration, et un redémarrage efface entièrement l’état de rejeu tandis que les admissions échouées restent rejouables.
• La diffusion attend jusqu’à huit secondes après le travail de mappage et de transformation, renvoie les identifiants d’exécution admis avec un compte d’envois, et peut signaler une erreur en même temps qu’un travail encore en attente, ce qui explique pourquoi la référence la décrit comme quelque chose de moins qu’un traitement durable exactement une fois.

Si vous câblez cela pour la première fois, lisez la référence des hooks à côté de la référence de configuration de la passerelle, car le contrat du point d’entrée et la politique de session forment un seul récit et les valeurs par défaut ne prennent sens qu’ensemble.

Pourquoi un contrat étroit

En lisant les tableaux de champs, un motif apparaît, car presque chaque garantie est énoncée en même temps que ce qu’elle n’est pas. Un jeton accorde un accès entrant, pas une identité. Un réveil mis en file demande un battement sans prouver qu’il a eu lieu. Un statut d’achèvement indique qu’une réponse a existé sans en exposer un seul caractère, et une erreur de livraison se réduit à une seule valeur catégorielle. Cette retenue est ce qui permet à la passerelle OpenClaw d’accepter des appels de systèmes dont elle ne peut pas répondre, et le même réflexe se retrouve dans les conseils sur l’injection de prompt. Le prix à payer est que les opérateurs doivent lire attentivement, car le chemin heureux et le chemin prouvé ne sont pas le même chemin.

Sur Diali

Sur Diali, chaque client fait tourner son propre assistant, les canaux sont connectés depuis le tableau de bord, et la configuration d’exécution est générée à partir de celui-ci puis remplacée à chaque version. L’état vit sur un volume persistant, avec des instantanés quotidiens et une restauration en un clic grâce à l’option Sauvegardes (incluse avec Max). Pour voir en quoi la forme hébergée diffère d’une installation autogérée, OpenClaw hébergé sur Diali et Les tarifs Diali sont les points de départ.

• Les hooks restent fermés tant qu’aucun jeton n’est défini.
• Un code 200 prouve l’admission, pas une réponse livrée.
• La diffusion s’arrête à deux cents éléments par requête.