L’API ClawHub

Très peu de registres disent tout haut que vous pouvez bâtir une surface concurrente par-dessus eux. ClawHub le dit, puis consacre l’essentiel de sa documentation d’API aux conditions, ce qui est le bon ordre. La base est l’hôte du registre lui-même, et toute la surface v1 est décrite par un document OpenAPI que le client peut lire directement.

Les règles de réutilisation

• Les points de lecture publics, la liste des compétences, le point de recherche et la fiche d’une compétence unique, sont la fondation prévue pour un catalogue, un annuaire ou une surface de recherche tiers.
• Les réponses devraient être mises en cache, et les réponses 429, l’en-tête Retry-After et les en-têtes de limite respectés, plutôt qu’interrogés agressivement.
• Les fiches devraient renvoyer vers la page canonique ClawHub pour qu’un lecteur puisse inspecter l’enregistrement du registre source, en utilisant la forme d’URL canonique bâtie sur le pseudonyme du propriétaire et l’identifiant de la compétence.
• Le contenu masqué, privé ou bloqué par la modération ne doit pas être recopié en contournant les filtres de l’API publique ou la frontière d’authentification.

Ne laissez pas entendre que ClawHub approuve, vérifie ou exploite le site tiers.

Où se situe la frontière du jeton

Les lectures publiques n’ont besoin d’aucun jeton, ce qui est précisément ce qui rend un catalogue indépendant praticable. Tout ce qui écrit, ou qui touche à un compte, exige un en-tête d’autorisation portant un jeton porteur. Cette seule ligne est tout le modèle d’authentification, et le limiteur lit le même jeton pour décider quel budget dépense une requête.

Deux budgets, pas un

• Les requêtes anonymes sont comptées par adresse IP et les requêtes authentifiées sur un seau par utilisateur, et un jeton absent ou invalide retombe sur l’application par IP plutôt que d’être rejeté d’emblée.
• Les lectures autorisent trois mille par minute et par IP et douze mille par clé, les écritures trois cents et trois mille, les téléchargements mille deux cents et six mille, donc se connecter vaut environ quatre fois une adresse anonyme sur chaque classe.
• Les erreurs en v1 sont du texte brut plutôt que du JSON, y compris 400, 401, 403, 404, 429 et les réponses de téléchargement bloqué, ce qu’il vaut mieux savoir avant qu’un client tente d’en analyser une comme un objet.

Les paramètres de requête inconnus sont ignorés par compatibilité, mais un paramètre connu portant une valeur invalide renvoie 400. Une faute de frappe dans une valeur échoue donc bruyamment tandis qu’une faute dans un nom de paramètre échoue en silence, et c’est la seule asymétrie qui mérite un test. Pour la liste des points auxquels ces conventions s’appliquent, voir Les points de terminaison HTTP ClawHub, et pour le versant publication du même registre, Ce que ClawHub vérifie avant publication.

Lire les en-têtes de réessai

Deux familles d’en-têtes portent la même information dans deux unités différentes, et les confondre est la cause habituelle d’une tempête de réessais. L’en-tête de réinitialisation préfixé est une seconde absolue depuis l’époque Unix, celui sans préfixe est un délai en secondes, et Retry-After sur un 429 est aussi un délai. Un client devrait préférer Retry-After quand il est présent, se rabattre sur la réinitialisation en forme de délai, ne dériver un délai de la valeur absolue qu’en dernier recours, et ajouter de la gigue dans tous les cas. Les en-têtes de budget restant sont exacts quand ils sont présents et sont omis plutôt qu’approchés sur les requêtes réussies réparties, donc leur absence n’est pas un zéro. Voir Le CLI ClawHub et Signaler une vulnérabilité ClawHub pour les deux surfaces qui consomment le plus cette API.

Sur Diali

Diali héberge OpenClaw, et les appels au registre décrits ici sont faits par l’assistant pour votre compte plutôt que par vous. Chaque client fait tourner sa propre instance, la configuration d’exécution est générée depuis le tableau de bord et remplacée à chaque version, et 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). Voir OpenClaw hébergé sur Diali pour ce que l’hébergement comprend et Tarifs Diali pour ce qu’il coûte.

• Les lectures publiques n’ont besoin d’aucun jeton ; tout ce qui écrit en a besoin.
• Préférez Retry-After, puis la réinitialisation en forme de délai, et ajoutez toujours de la gigue.
• Un en-tête de budget restant absent est une répartition, pas un zéro.