--- seo_title: Skill ClawHub per OpenClaw: scraping e conversione | EnConvert meta_desc: Installa la skill EnConvert da ClawHub: un agent OpenClaw legge le pagine in markdown, cerca sul web, estrae campi tipizzati e converte file con curl. keywords: agent openclaw web scraping, skill clawhub, installare skill openclaw, estrazione markdown per agent, openclaw da url a markdown, skill ricerca web openclaw, clawhub enconvert, chiave api openclaw, estrazione dati strutturati agent, skill conversione file openclaw --- # Skill ClawHub per gli agent OpenClaw La skill EnConvert è pubblicata su [ClawHub](https://clawhub.ai), il registro di skill per gli agent [OpenClaw](https://openclaw.ai). 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: ```bash 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à: ```bash 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](/it/dashboard/api-keys). 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](https://docs.openclaw.ai/tools/skills) descrive il blocco `env` per singola skill. 3. Verifica che la chiave funzioni prima di chiedere qualsiasi cosa all'agent: ```bash 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](/it/docs/authentication.md#private-keys).
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: ```bash 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](/it/docs/concepts/signed-urls.md). - **`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: ```bash 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. ```bash curl -sS -X POST https://api.enconvert.com/v1/convert/anything-to-markdown \ -H "X-API-Key: $ENCONVERT_API_KEY" -F "file=@report.docx" ``` 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. --- ## Sorgente e link - **Scheda ClawHub**: [clawhub.ai/enconvert/skills/enconvert](https://clawhub.ai/enconvert/skills/enconvert) - **Publisher**: [@enconvert](https://clawhub.ai/@enconvert) - **Skill OpenClaw**: [docs.openclaw.ai/tools/skills](https://docs.openclaw.ai/tools/skills) - **Formato delle skill ClawHub**: [docs.openclaw.ai/clawhub/skill-format](https://docs.openclaw.ai/clawhub/skill-format) - **API sottostante**: [Introduzione](/it/docs/introduction.md), [Perceive](/it/docs/endpoints/perceive.md), [Anything to Markdown](/it/docs/endpoints/convert/documents/anything-to-markdown.md) - **Codice sorgente**: [enconvert/clawhub-enconvert](https://github.com/enconvert/clawhub-enconvert) Se invece il tuo coding agent supporta il Model Context Protocol, [Configurazione MCP](/it/docs/guides/integrations/mcp-setup.md) 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.