API Documentation

Skill ClawHub pour les agents OpenClaw#

Le skill EnConvert est publié sur ClawHub, le registre de skills des agents OpenClaw. Son installation donne à un agent six opérations : lire une URL en markdown, chercher sur le web, lister les adresses d'un site, extraire des champs typés de pages, et convertir un fichier en markdown ou en PDF. Chaque lecture de page porte un score render_quality de 0.0 à 1.0 : un mur anti-bot ou la coquille vide d'une single-page app arrive donc signalé comme tel, au lieu d'être transmis comme s'il s'agissait de la page.

Installation : openclaw skills install @enconvert/enconvert · Fiche : clawhub.ai/enconvert/skills/enconvert · Version : 0.0.1 · Code source : enconvert/clawhub-enconvert

Ce qu'est un skill ClawHub#

Un skill ClawHub est un simple fichier markdown d'instructions. L'agent le lit et exécute lui-même les appels avec curl. C'est tout le mécanisme.

Cela compte plus qu'il n'y paraît. Les six opérations ci-dessous ne sont pas des schémas d'outils enregistrés. Rien n'apparaît dans une liste d'outils, aucun objet d'arguments n'est validé avant qu'un appel ne parte, et aucun SDK ne s'interpose entre l'agent et l'API. Le skill indique à l'agent quel endpoint appeler, quel en-tête envoyer et à quoi ressemble la réponse ; c'est l'agent qui compose la requête HTTP. Parlez d'opérations, pas d'outils, et le comportement que vous observez prendra tout son sens : un agent qui n'a pas lu le fichier n'appellera rien, et un agent qui l'a lu peut s'en écarter.

L'avantage pratique : rien à installer au-delà de curl, et les mêmes instructions fonctionnent sur n'importe quelle plateforme capable de lancer une commande shell.

Les six opérations#

Opération Endpoint Ce qui revient
Perceive URL POST /v2/perceive render_quality, plus un objet outputs d'URL signées valables 15 minutes
Web Search POST /v2/lookup results[] avec title, url, snippet, position
Discover URLs POST /v2/discover urls[] et total, sans rendre aucune page
Extract Structured POST /v2/distill results[], une entrée par URL, chacune avec data et extraction_tier
Convert File to Markdown POST /v1/convert/anything-to-markdown du JSON portant presigned_url
Convert File to PDF POST /v1/convert/anything-to-pdf du JSON portant presigned_url

Chaque appel envoie l'en-tête X-API-Key, jamais Authorization: Bearer. Les six passent par la même API REST documentée sur ce site : le quota de votre plan et vos limites de débit s'appliquent donc exactement comme partout ailleurs.

La recherche web, c'est POST /v2/lookup. L'espace de noms V2 ne contient aucun endpoint nommé d'après le mot « search » ; une requête vers un tel chemin renvoie 404. Si un agent tente ce chemin, c'est que le fichier de skill qu'il a lu n'était pas à jour.

Installation#

Installez-le avec la CLI OpenClaw :

openclaw skills install @enconvert/enconvert

C'est la forme qu'affiche la fiche ClawHub. Ajoutez --global pour l'installer pour tous les projets plutôt que pour le projet courant, et openclaw skills update --all plus tard pour récupérer les nouvelles versions.

La CLI ClawHub installe le même skill, si c'est l'outil que vous avez déjà :

npm i -g clawhub
clawhub install @enconvert/enconvert

Le paquet npm clawhub est la CLI. Il existe sur PyPI un paquet homonyme sans aucun rapport, dont toutes les versions sont retirées ; pip install clawhub ne mène donc pas à cette CLI.

Donner votre clé API au skill#

Le skill lit un seul secret : ENCONVERT_API_KEY.

  1. Générez une clé API privée dans le tableau de bord. Les clés privées commencent par sk_.
  2. Rendez-la disponible pour l'agent, soit via ENCONVERT_API_KEY dans l'environnement où tourne l'agent, soit injectée pour ce skill par votre configuration OpenClaw. La référence de configuration des skills décrit le bloc env propre à chaque skill.
  3. Vérifiez que la clé fonctionne avant de demander quoi que ce soit à l'agent :
curl -sS https://api.enconvert.com/v1/whoami -H "X-API-Key: $ENCONVERT_API_KEY"
# {"project_id":"2","plan_slug":"free"}

Une clé publique pk_ est rejetée ici avec un 403. Les clés publiques existent pour les widgets navigateur et aucune opération de ce skill n'en accepte. Voir Clés privées.

Sans la clé, le skill ne se charge jamais, en silence. OpenClaw filtre les skills au chargement selon les prérequis déclarés dans le fichier : celui-ci a besoin de la variable d'environnement ENCONVERT_API_KEY et du binaire curl dans le PATH. S'il en manque un, le skill est purement et simplement inéligible, et aucun message d'erreur ne s'affiche. Le symptôme : un agent qui répond comme s'il n'avait jamais entendu parler d'EnConvert. Vérifiez curl --version et l'appel whoami ci-dessus avant de déboguer quoi que ce soit d'autre.

Ce que renvoie la lecture d'une page#

La forme de la réponse de POST /v2/perceive est la seule chose qu'il vaille vraiment la peine de comprendre avant de lancer un agent dessus :

curl -sS -X POST https://api.enconvert.com/v2/perceive \
  -H "X-API-Key: $ENCONVERT_API_KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","outputs":["markdown"],"only_main_content":true}'

Trois règles régissent la réponse :

  • render_quality passe en premier. C'est un nombre de 0.0 à 1.0 dans une réponse 200, pas une erreur HTTP. Un score bas signifie que le rendu est dégradé : traitez alors le contenu comme suspect plutôt que comme faisant autorité.
  • Chaque artefact sous outputs est une URL signée valable 15 minutes, markdown compris. outputs.markdown.url est un lien, pas le texte de la page. Idem pour html_cleaned, html_raw, screenshot, screenshot_full_page, pdf, links et images. Récupérez chacun avec un simple GET et sans en-tête X-API-Key : c'est la signature contenue dans l'URL qui authentifie, et y joindre votre clé la livrerait à l'hôte de stockage pour rien. Plus de détails dans URL signées.
  • structured fait exception. Il revient inline, au premier niveau de la réponse, et non sous outputs.

Un agent qui attend du markdown inline lit un objet là où il voulait du texte, et rapporte la page comme vide. Deux étapes, pas une :

MD=$(curl -sS -X POST https://api.enconvert.com/v2/perceive \
  -H "X-API-Key: $ENCONVERT_API_KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","outputs":["markdown"]}' \
  | grep -o '"url":"[^"]*"' | head -n1 | cut -d'"' -f4)
curl -sS "$MD"   # no key here

La conversion de fichiers se termine de la même façon : le JSON porte presigned_url, que vous récupérez avec un simple GET et sans clé.

Convertir un fichier#

Les deux endpoints de conversion attendent du multipart/form-data avec un unique champ nommé file. Ne fixez pas Content-Type à la main ; c'est la frontière multipart qui le définit.

curl -sS -X POST https://api.enconvert.com/v1/convert/anything-to-markdown \
  -H "X-API-Key: $ENCONVERT_API_KEY" -F "[email protected]"

C'est l'extension du nom de fichier qui détermine le format d'entrée. C'est l'arête la plus vive de ce flux sur une plateforme d'agents, où l'entrée est le plus souvent une URL plutôt qu'un chemin local : téléchargez d'abord la source sans en-tête X-API-Key (c'est un hôte tiers), conservez le nom de fichier d'origine, puis envoyez les octets. Un nom que l'API ne sait pas lire est réparé à partir des octets quand le format porte une signature (un PDF, une image ou un DOCX y survivent), mais un format texte n'en a pas : du markdown enregistré sous notes.lJzoMq6Akq revient en 400 Invalid file format '.ljzomq6akq' for anything-to-markdown. Le script scripts/convert.sh fourni avec le skill exécute correctement toute la séquence téléchargement-envoi-récupération.

Dépannage#

L'agent ne mentionne jamais EnConvert. Le skill ne s'est pas chargé. Soit ENCONVERT_API_KEY n'est pas visible depuis le processus de l'agent, soit curl n'est pas dans le PATH. Le filtrage au chargement est silencieux par conception : il n'y a rien à trouver dans les logs.

401 ou 403 sur chaque appel. La clé est absente, incorrecte, ou c'est une clé publique pk_. Lancez l'appel whoami ci-dessus ; il échoue exactement de la même manière et vous le dit en une ligne.

Un 404 sur la recherche web. L'agent a deviné un endpoint nommé d'après le mot « search ». Ce chemin n'existe pas. La recherche web, c'est POST /v2/lookup.

400 Invalid file format. Le fichier envoyé n'avait ni extension exploitable ni signature dans ses octets pour en déduire une, ce qui est le cas de tous les formats texte : CSV, HTML, Markdown, texte brut. Conservez le nom de fichier de la source, ou renommez le téléchargement avec le bon suffixe.

La page revient vide, ou sous la forme [object Object]. outputs.markdown est une URL signée. Allez la chercher. Seul structured arrive inline.

Un lien de téléchargement a cessé de fonctionner. Les URL signées durent 15 minutes. Relancez l'opération plutôt que d'essayer de rafraîchir le lien.

Source et liens#

Pour un agent de code qui prend en charge le Model Context Protocol à la place, Configuration MCP expose les mêmes opérations sous forme de vrais outils enregistrés.

Questions fréquentes#

Comment installer le skill EnConvert dans OpenClaw ?#

Lancez openclaw skills install @enconvert/enconvert. C'est la commande qu'affiche la fiche ClawHub. La CLI ClawHub installe le même skill avec clawhub install @enconvert/enconvert, après npm i -g clawhub. Définissez ensuite ENCONVERT_API_KEY avec une clé privée sk_ issue de votre tableau de bord, car le skill ne se chargera pas sans elle.

Comment faire lire une page web en markdown à un agent OpenClaw ?#

Demandez-lui la page une fois le skill installé. Il appelle POST /v2/perceive avec outputs: ["markdown"], puis récupère outputs.markdown.url avec un simple GET et sans clé. Le markdown est environ six fois plus léger que le HTML brut de la même page, ce qui réduit le coût en tokens de tout ce que l'agent en fait ensuite.

Pourquoi le skill ne fait-il absolument rien ?#

OpenClaw filtre les skills au chargement selon les prérequis qu'ils déclarent. Celui-ci déclare la variable d'environnement ENCONVERT_API_KEY et le binaire curl. S'il en manque un, le skill est écarté avant même que l'agent ne le voie, sans aucun message d'erreur. C'est la cause dans la quasi-totalité des cas.

Le skill est-il un outil enregistré que l'agent peut appeler ?#

Non. C'est un fichier markdown d'instructions que l'agent lit et applique avec curl. Il n'y a ni schéma d'outil ni validation d'arguments, et c'est pour cela que le fichier de skill détaille chaque endpoint, chaque en-tête et chaque forme de réponse. Rien d'autre n'est à installer.

Puis-je utiliser une clé publique pk_ ?#

Non. Les clés publiques sont destinées aux widgets navigateur et chaque opération présentée ici les rejette avec un 403. Utilisez une clé privée commençant par sk_, générée dans Dashboard, API keys.

Comment l'agent sait-il qu'une page ne s'est pas rendue correctement ?#

Chaque réponse de perceive porte render_quality, un nombre de 0.0 à 1.0 à l'intérieur d'un 200 normal. Une page de vérification, un mur de cookies ou un script qui ne se stabilise jamais obtiennent un score bas. Le skill demande à l'agent de lire ce score en premier et de signaler une lecture dégradée plutôt que de la présenter comme fiable.

← MCP Setup Dify →