API Documentation

Skill de ClawHub para agentes de OpenClaw#

La skill de EnConvert está publicada en ClawHub, el registro de skills para agentes de OpenClaw. Instalarla le da al agente seis operaciones: leer una URL como markdown, buscar en la web, listar las direcciones de un sitio, extraer campos con tipo de una página y convertir un archivo a markdown o a PDF. Cada lectura de página lleva una puntuación render_quality de 0.0 a 1.0, así que un muro anti-bot o el cascarón vacío de una single-page app llega marcado en lugar de pasar adelante como si fuera la página.

Instalación: openclaw skills install @enconvert/enconvert · Ficha: clawhub.ai/enconvert/skills/enconvert · Versión: 0.0.1 · Código fuente: enconvert/clawhub-enconvert

Qué es una skill de ClawHub#

Una skill de ClawHub es un único archivo markdown de instrucciones. El agente lo lee y ejecuta él mismo las llamadas con curl. Ese es todo el mecanismo.

Esto importa más de lo que parece. Las seis operaciones de abajo no son esquemas de herramientas registradas. No aparece nada en una lista de herramientas, no se valida ningún objeto de argumentos antes de que salga una llamada, y no hay ningún SDK entre el agente y la API. La skill le dice al agente a qué endpoint llamar, qué cabecera enviar y qué aspecto tiene la respuesta; el agente compone la solicitud HTTP. Llámalas operaciones y no herramientas, y el comportamiento que observes tendrá sentido: un agente que no ha leído el archivo no llamará a nada, y un agente que sí lo ha leído puede desviarse de él.

La ventaja práctica es que no hay que instalar nada más allá de curl, y las mismas instrucciones funcionan en cualquier plataforma capaz de ejecutar un comando de shell.

Las seis operaciones#

Operación Endpoint Qué devuelve
Perceive URL POST /v2/perceive render_quality, más un objeto outputs de URLs firmadas de 15 minutos
Web Search POST /v2/lookup results[] con title, url, snippet y position
Discover URLs POST /v2/discover urls[] y total, sin renderizar ninguna página
Extract Structured POST /v2/distill results[], una entrada por URL, cada una con data y extraction_tier
Convert File to Markdown POST /v1/convert/anything-to-markdown JSON que lleva presigned_url
Convert File to PDF POST /v1/convert/anything-to-pdf JSON que lleva presigned_url

Todas las llamadas envían la cabecera X-API-Key, nunca Authorization: Bearer. Las seis se ejecutan contra la misma API REST documentada en el resto de este sitio, así que la cuota de tu plan y los límites de frecuencia se aplican exactamente igual que en cualquier otra parte.

La búsqueda web es POST /v2/lookup. El espacio de nombres V2 no tiene ningún endpoint llamado como la palabra «search»; una solicitud a uno así devuelve 404. Si un agente recurre a esa ruta, el archivo de skill que leyó estaba desactualizado.

Instalación#

Instálala con la CLI de OpenClaw:

openclaw skills install @enconvert/enconvert

Esa es la forma que muestra la ficha de ClawHub. Añade --global para instalarla en todos los proyectos en lugar de solo en el actual, y openclaw skills update --all más adelante para recoger las versiones nuevas.

La CLI de ClawHub instala la misma skill, si esa es la herramienta que ya tienes:

npm i -g clawhub
clawhub install @enconvert/enconvert

El paquete npm clawhub es la CLI. Existe en PyPI un paquete sin relación con el mismo nombre cuyas versiones están todas retiradas, así que pip install clawhub no lleva a esta CLI.

Dale tu clave de API a la skill#

La skill lee un único secreto: ENCONVERT_API_KEY.

  1. Genera una clave de API privada en el panel. Las claves privadas empiezan por sk_.
  2. Ponla a disposición del agente, ya sea como ENCONVERT_API_KEY en el entorno en el que se ejecuta el agente, o inyectada para esta skill desde tu configuración de OpenClaw. La referencia de configuración de skills cubre el bloque env por skill.
  3. Comprueba que la clave funciona antes de pedirle nada al agente:
curl -sS https://api.enconvert.com/v1/whoami -H "X-API-Key: $ENCONVERT_API_KEY"
# {"project_id":"2","plan_slug":"free"}

Una clave pública pk_ se rechaza aquí con un 403. Las claves públicas existen para los widgets de navegador y ninguna operación de esta skill acepta una. Consulta Claves privadas.

Sin la clave, la skill simplemente no se carga. OpenClaw filtra las skills en el momento de la carga según los requisitos declarados en el archivo: esta necesita la variable de entorno ENCONVERT_API_KEY y el binario curl en el PATH. Si falta cualquiera de los dos, la skill queda descartada sin más, y no hay ningún mensaje de error que leer. El síntoma es un agente que responde como si nunca hubiera oído hablar de EnConvert. Comprueba curl --version y la llamada a whoami de arriba antes de depurar cualquier otra cosa.

Qué devuelve la lectura de una página#

La forma de la respuesta de POST /v2/perceive es lo que más merece la pena entender antes de que un agente la ejecute:

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

Tres reglas rigen la respuesta:

  • render_quality va primero. Es un número de 0.0 a 1.0 dentro de una respuesta 200, no un error HTTP. Una puntuación baja significa que el render está degradado, así que trata el contenido como sospechoso en lugar de darlo por bueno.
  • Cada artefacto bajo outputs es una URL firmada de 15 minutos, markdown incluido. outputs.markdown.url es un enlace, no el texto de la página. Lo mismo vale para html_cleaned, html_raw, screenshot, screenshot_full_page, pdf, links e images. Descarga cada uno con un GET normal y sin cabecera X-API-Key: la firma que va en la URL es la autenticación, y adjuntar tu clave se la entregaría al host de almacenamiento para nada. Tienes más información en URLs firmadas.
  • structured es la excepción. Vuelve en línea en el nivel superior de la respuesta, no bajo outputs.

Un agente que espera markdown en línea lee un objeto donde quería texto, e informa de que la página está vacía. Dos pasos, no 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

La conversión de archivos funciona igual al final: el JSON lleva presigned_url, y eso lo descargas con un GET normal y sin clave.

Convertir un archivo#

Los dos endpoints de conversión aceptan multipart/form-data con un único campo llamado file. No fijes Content-Type a mano; lo establece el límite del multipart.

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

La extensión del nombre de archivo decide el formato de entrada. Este es el filo más afilado del flujo en una plataforma de agentes, donde la entrada suele ser una URL y no una ruta local: descarga primero el origen sin cabecera X-API-Key (es un host de terceros), conserva el nombre de archivo original y luego envía los bytes. Un nombre que la API no puede leer se repara a partir de los bytes cuando el formato lleva firma (un PDF, una imagen o un DOCX lo sobreviven), pero un formato de texto no la tiene: markdown guardado como notes.lJzoMq6Akq vuelve como 400 Invalid file format '.ljzomq6akq' for anything-to-markdown. El helper scripts/convert.sh que viene con la skill hace correctamente toda la secuencia de descargar, enviar y recoger.

Solución de problemas#

El agente nunca menciona EnConvert. La skill no se cargó. O ENCONVERT_API_KEY no es visible para el proceso del agente, o curl no está en el PATH. El filtrado en el momento de la carga es silencioso por diseño, así que no hay nada que encontrar en los logs.

401 o 403 en todas las llamadas. La clave falta, es incorrecta o es una clave pública pk_. Ejecuta la llamada a whoami de arriba; falla exactamente igual y te lo dice en una línea.

Un 404 desde la búsqueda web. El agente adivinó un endpoint llamado como la palabra «search». No existe esa ruta. La búsqueda web es POST /v2/lookup.

400 Invalid file format. El archivo subido no llevaba una extensión utilizable ni una firma en sus bytes de la que deducirla, que es el caso de todo formato de texto: CSV, HTML, Markdown, texto plano. Conserva el nombre de archivo de origen, o renombra la descarga a uno con el sufijo correcto.

La página vuelve vacía, o como [object Object]. outputs.markdown es una URL firmada. Descárgala. Solo structured llega en línea.

Un enlace de descarga dejó de funcionar. Las URLs firmadas duran 15 minutos. Vuelve a ejecutar la operación en lugar de intentar refrescar el enlace.

Fuente y enlaces#

Para un agente de programación que admita en su lugar el Model Context Protocol, Configuración de MCP expone las mismas operaciones como herramientas realmente registradas.

Preguntas frecuentes#

¿Cómo instalo la skill de EnConvert en OpenClaw?#

Ejecuta openclaw skills install @enconvert/enconvert. Ese es el comando que muestra la ficha de ClawHub. La CLI de ClawHub instala la misma skill con clawhub install @enconvert/enconvert después de npm i -g clawhub. Luego pon en ENCONVERT_API_KEY una clave privada sk_ de tu panel, porque la skill no se carga sin ella.

¿Cómo hago que un agente de OpenClaw lea una página web como markdown?#

Pídesela una vez instalada la skill. Llama a POST /v2/perceive con outputs: ["markdown"] y después descarga outputs.markdown.url con un GET normal y sin clave. El markdown es unas seis veces más pequeño que el HTML crudo de la misma página, lo que recorta el coste en tokens de todo lo que el agente haga con ella después.

¿Por qué la skill no hace absolutamente nada?#

OpenClaw filtra las skills en el momento de la carga según los requisitos que declaran. Esta declara la variable de entorno ENCONVERT_API_KEY y el binario curl. Si falta cualquiera de los dos, la skill queda excluida antes de que el agente llegue a verla, y sin ningún mensaje de error. Esa es la causa casi siempre.

¿Es la skill una herramienta registrada a la que el agente pueda llamar?#

No. Es un archivo markdown de instrucciones que el agente lee y ejecuta con curl. No hay esquema de herramienta ni validación de argumentos, y por eso el archivo de la skill detalla cada endpoint, cada cabecera y la forma de cada respuesta. No hace falta instalar nada más.

¿Puedo usar una clave pública pk_?#

No. Las claves públicas son para los widgets de navegador y todas las operaciones de aquí las rechazan con un 403. Usa una clave privada que empiece por sk_, generada en Panel, Claves de API.

¿Cómo sabe el agente que una página no se renderizó bien?#

Cada respuesta de perceive lleva render_quality, un número de 0.0 a 1.0 dentro de un 200 normal. Una página de desafío, un muro de cookies o un script que nunca terminó de asentarse puntúan bajo. La skill le indica al agente que lea esa puntuación primero y que avise de una lectura degradada en lugar de presentarla como fiable.

← MCP Setup Dify →