API Documentation

Skill ClawHub per gli agent OpenClaw#

La skill EnConvert è pubblicata su ClawHub, il registro di skill per gli agent OpenClaw. Installarla dà a un agent sei operazioni: leggere un URL come markdown, cercare sul web, elencare gli URL di un sito, estrarre campi tipizzati dalle pagine e convertire un file in markdown o in PDF. Ogni lettura di pagina porta con sé un punteggio render_quality da 0.0 a 1.0, così un muro anti-bot o il guscio vuoto di una single-page app arriva segnalato invece di essere passato avanti come se fosse la pagina.

Installazione: openclaw skills install @enconvert/enconvert · Scheda: clawhub.ai/enconvert/skills/enconvert · Versione: 0.0.1 · Codice sorgente: enconvert/clawhub-enconvert

Che cos'è una skill ClawHub#

Una skill ClawHub è un unico file markdown di istruzioni. L'agent lo legge ed esegue da sé le chiamate con curl. Il meccanismo è tutto qui.

Conta più di quanto sembri. Le sei operazioni qui sotto non sono schemi di tool registrati. Non compare nulla in un elenco di tool, nessun oggetto di argomenti viene validato prima che parta una chiamata e non c'è alcun SDK tra l'agent e l'API. La skill dice all'agent quale endpoint chiamare, quale header inviare e che aspetto ha la risposta; è l'agent a comporre la richiesta HTTP. Chiamale operazioni, non tool, e il comportamento che osservi avrà senso: un agent che non ha letto il file non chiamerà nulla, e un agent che lo ha letto può discostarsene.

Il vantaggio pratico è che non serve installare nulla oltre a curl, e le stesse istruzioni funzionano su qualunque piattaforma in grado di eseguire un comando di shell.

Le sei operazioni#

Operazione Endpoint Cosa torna indietro
Perceive URL POST /v2/perceive render_quality, più un oggetto outputs di URL firmati validi 15 minuti
Web Search POST /v2/lookup results[] con title, url, snippet, position
Discover URLs POST /v2/discover urls[] e total, senza renderizzare alcuna pagina
Extract Structured POST /v2/distill results[], una voce per URL, ciascuna con data e extraction_tier
Convert File to Markdown POST /v1/convert/anything-to-markdown JSON che contiene presigned_url
Convert File to PDF POST /v1/convert/anything-to-pdf JSON che contiene presigned_url

Ogni chiamata invia l'header X-API-Key, mai Authorization: Bearer. Tutte e sei girano sulla stessa REST API documentata in questo sito, quindi la quota del tuo piano e i rate limit valgono esattamente come altrove.

La ricerca web è POST /v2/lookup. Il namespace V2 non ha alcun endpoint che porta la parola "search" nel nome; una richiesta a un percorso simile restituisce 404. Se un agent prova quella strada, il file della skill che ha letto non era aggiornato.

Installazione#

Installala con la CLI di OpenClaw:

openclaw skills install @enconvert/enconvert

È la forma che mostra la scheda su ClawHub. Aggiungi --global per installarla su tutti i progetti invece che solo su quello corrente, e più avanti openclaw skills update --all per prendere le nuove versioni.

La CLI di ClawHub installa la stessa skill, se è quello lo strumento che hai già:

npm i -g clawhub
clawhub install @enconvert/enconvert

Il pacchetto npm clawhub è la CLI. Su PyPI esiste un pacchetto omonimo senza alcun rapporto con questo, con tutte le release ritirate; pip install clawhub quindi non porta a questa CLI.

Passa la tua chiave API alla skill#

La skill legge un solo segreto: ENCONVERT_API_KEY.

  1. Genera una chiave API privata nella dashboard. Le chiavi private iniziano con sk_.
  2. Rendila disponibile all'agent, come ENCONVERT_API_KEY nell'ambiente in cui l'agent gira oppure iniettandola per questa skill dalla tua configurazione OpenClaw. Il riferimento di configurazione delle skill descrive il blocco env per singola skill.
  3. Verifica che la chiave funzioni prima di chiedere qualsiasi cosa all'agent:
curl -sS https://api.enconvert.com/v1/whoami -H "X-API-Key: $ENCONVERT_API_KEY"
# {"project_id":"2","plan_slug":"free"}

Una chiave pubblica pk_ viene rifiutata qui con un 403. Le chiavi pubbliche esistono per i widget nel browser e nessuna operazione di questa skill le accetta. Vedi Chiavi private.

Senza la chiave, la skill semplicemente non si carica. OpenClaw filtra le skill al momento del caricamento in base ai requisiti dichiarati nel file: questa richiede la variabile d'ambiente ENCONVERT_API_KEY e il binario curl nel PATH. Se manca uno dei due la skill non è idonea, e non c'è nessun messaggio di errore da leggere. Il sintomo è un agent che risponde come se non avesse mai sentito parlare di EnConvert. Controlla curl --version e la chiamata whoami qui sopra prima di mettere mano ad altro.

Cosa torna indietro dalla lettura di una pagina#

La forma della risposta di POST /v2/perceive è la cosa che vale di più capire prima che un agent la esegua:

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}'

Tre regole governano la risposta:

  • render_quality viene prima di tutto. È un numero da 0.0 a 1.0 dentro una risposta 200, non un errore HTTP. Un punteggio basso significa che il render è degradato, quindi tratta il contenuto come sospetto e non come autorevole.
  • Ogni artefatto sotto outputs è un URL firmato valido 15 minuti, markdown compreso. outputs.markdown.url è un link, non il testo della pagina. Lo stesso vale per html_cleaned, html_raw, screenshot, screenshot_full_page, pdf, links e images. Recupera ciascuno con un semplice GET e senza header X-API-Key: la firma dentro l'URL è l'autenticazione, e allegare la tua chiave la consegnerebbe all'host di storage per niente. Altri dettagli in URL firmati.
  • structured è l'eccezione. Torna inline al livello superiore della risposta, non sotto outputs.

Un agent che si aspetta markdown inline legge un oggetto dove voleva del testo, e riporta la pagina come vuota. I passaggi sono due, non uno:

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

Alla fine la conversione dei file funziona allo stesso modo: il JSON contiene presigned_url, e quello lo recuperi con un semplice GET e senza chiave.

Convertire un file#

Entrambi gli endpoint di conversione accettano multipart/form-data con un unico campo chiamato file. Non impostare Content-Type a mano; lo definisce il boundary multipart.

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

L'estensione del nome del file decide il formato di input. È lo spigolo più tagliente di questo flusso su una piattaforma per agent, dove l'input di solito è un URL e non un percorso locale: scarica prima la sorgente senza header X-API-Key (l'host è di terze parti), conserva il nome file originale, poi invia i byte. Un nome che l'API non riesce a leggere viene riparato dai byte quando il formato porta una firma (un PDF, un'immagine o un DOCX sopravvivono), ma un formato di testo non ce l'ha: del markdown salvato come notes.lJzoMq6Akq torna come 400 Invalid file format '.ljzomq6akq' for anything-to-markdown. Lo script scripts/convert.sh incluso nella skill esegue correttamente l'intera sequenza di download, invio e recupero.

Risoluzione dei problemi#

L'agent non nomina mai EnConvert. La skill non si è caricata. O ENCONVERT_API_KEY non è visibile al processo dell'agent, oppure curl non è nel PATH. Il filtro al caricamento è silenzioso per scelta progettuale, quindi nei log non c'è nulla da trovare.

401 o 403 su ogni chiamata. La chiave manca, è sbagliata oppure è una chiave pubblica pk_. Esegui la chiamata whoami qui sopra: fallisce esattamente allo stesso modo e te lo dice in una riga.

Un 404 dalla ricerca web. L'agent ha tirato a indovinare un endpoint chiamato con la parola "search". Quel percorso non esiste. La ricerca web è POST /v2/lookup.

400 Invalid file format. Il file caricato non aveva un'estensione utilizzabile né una firma nei byte da cui ricavarla, il che vale per ogni formato di testo: CSV, HTML, Markdown, testo semplice. Conserva il nome file di origine, oppure rinomina il download con il suffisso giusto.

La pagina torna vuota, oppure come [object Object]. outputs.markdown è un URL firmato. Recuperalo. Solo structured arriva inline.

Un link di download ha smesso di funzionare. Gli URL firmati durano 15 minuti. Esegui di nuovo l'operazione invece di provare a rinnovare il link.

Se invece il tuo coding agent supporta il Model Context Protocol, Configurazione MCP espone le stesse operazioni come veri tool registrati.

Domande frequenti#

Come installo la skill EnConvert in OpenClaw?#

Esegui openclaw skills install @enconvert/enconvert. È il comando che mostra la scheda su ClawHub. La CLI di ClawHub installa la stessa skill con clawhub install @enconvert/enconvert dopo npm i -g clawhub. Poi imposta ENCONVERT_API_KEY con una chiave privata sk_ presa dalla tua dashboard, perché senza quella la skill non si carica.

Come faccio leggere a un agent OpenClaw una pagina web come markdown?#

Chiediglielo, una volta installata la skill. Chiama POST /v2/perceive con outputs: ["markdown"], poi recupera outputs.markdown.url con un semplice GET e senza chiave. Il markdown è circa sei volte più leggero dell'HTML grezzo della stessa pagina, il che taglia il costo in token di tutto quello che l'agent ci fa dopo.

Perché la skill non fa assolutamente nulla?#

OpenClaw filtra le skill al caricamento in base ai requisiti che dichiarano. Questa dichiara la variabile d'ambiente ENCONVERT_API_KEY e il binario curl. Se manca uno dei due la skill viene esclusa prima ancora che l'agent la veda, senza alcun messaggio di errore. Quasi sempre la causa è questa.

La skill è un tool registrato che l'agent può chiamare?#

No. È un file markdown di istruzioni che l'agent legge e su cui agisce con curl. Non c'è nessuno schema di tool e nessuna validazione degli argomenti, ed è per questo che il file della skill esplicita ogni endpoint, ogni header e la forma di ogni risposta. Non serve installare altro.

Posso usare una chiave pubblica pk_?#

No. Le chiavi pubbliche servono per i widget nel browser e ogni operazione qui le rifiuta con un 403. Usa una chiave privata che inizia con sk_, generata in Dashboard, chiavi API.

Come fa l'agent a sapere che una pagina non è stata renderizzata bene?#

Ogni risposta di perceive porta render_quality, un numero da 0.0 a 1.0 dentro un normale 200. Una pagina di challenge, un cookie wall o uno script che non si è mai stabilizzato ottengono un punteggio basso. La skill istruisce l'agent a leggere per primo quel punteggio e a segnalare una lettura degradata invece di presentarla come affidabile.

← MCP Setup Dify →