Analiza documentos PDF con OpenClaw: Guía de integración

Extraer información de documentos PDF para alimentar a tus modelos de IA suele ser un dolor de cabeza constante. Entre parsear el formato, manejar imágenes o lidiar con diferentes APIs de proveedores, es fácil perder tiempo en tareas que no aportan valor real a tu lógica de negocio.

La herramienta pdf analiza uno o más documentos PDF y te devuelve el texto procesado. Es la mejor forma de manejar documentos sin complicarte con librerías externas de bajo nivel.

Características rápidas:

• Modo de proveedor nativo para Anthropic y Google.
• Modo de extracción de respaldo para otros proveedores (extrae texto primero y luego imágenes de página si es necesario).
• Soporta entrada única (pdf) o múltiple (pdfs), con un máximo de 10 PDFs por llamada.

Disponibilidad

La herramienta solo se registra cuando OpenClaw puede resolver una configuración de modelo con capacidad para PDF para el agent:

1. agents.defaults.pdfModel
2. Respaldo a agents.defaults.imageModel
3. Respaldo a los valores predeterminados del proveedor según la autenticación disponible

Si no se puede resolver ningún modelo utilizable, la herramienta pdf no se expone.

Referencia de entrada

• pdf (string): una ruta de PDF o URL.
• pdfs (string[]): múltiples rutas de PDF o URLs, hasta 10 en total.
• prompt (string): instrucción de análisis, por defecto es Analyze this PDF document..
• pages (string): filtro de páginas como 1-5 o 1,3,7-9.
• model (string): sobrescritura opcional del modelo (provider/model).
• maxBytesMb (number): límite de tamaño por PDF en MB.

Notas de entrada:

• pdf y pdfs se combinan y se eliminan duplicados antes de la carga.
• Si no proporcionas ninguna entrada de PDF, la herramienta devuelve un error.
• pages se procesa como números de página basados en 1, se eliminan duplicados, se ordenan y se limitan al máximo de páginas configurado.
• maxBytesMb usa por defecto agents.defaults.pdfMaxBytesMb o 10.

Referencias de PDF soportadas

• Ruta de archivo local (incluyendo expansión de ~).
• URL file://.
• URL http:// y https://.

Notas de referencia:

• Otros esquemas de URI (por ejemplo ftp://) se rechazan con unsupported_pdf_reference.
• En modo sandbox, las URLs remotas http(s) se rechazan.
• Con la política de archivos solo para el workspace activada, las rutas de archivos locales fuera de las raíces permitidas se rechazan.

Modos de ejecución

Modo de proveedor nativo

El modo nativo se usa para los proveedores anthropic y google. La herramienta envía los bytes del PDF directamente a las APIs del proveedor.

Límites del modo nativo:

• pages no está soportado. Si se configura, la herramienta devuelve un error.

Modo de extracción de respaldo

El modo de respaldo se usa para proveedores no nativos.

Flujo:

1. Extrae texto de las páginas seleccionadas (hasta agents.defaults.pdfMaxPages, por defecto 20).
2. Si la longitud del texto extraído es inferior a 200 caracteres, renderiza las páginas seleccionadas a imágenes PNG y las incluye.
3. Envía el contenido extraído junto con el prompt al modelo seleccionado.

Detalles del respaldo:

• La extracción de imágenes de página usa un presupuesto de píxeles de 4,000,000.
• Si el modelo de destino no soporta entrada de imágenes y no hay texto extraíble, la herramienta da error.
• El respaldo de extracción requiere pdfjs-dist (y @napi-rs/canvas para el renderizado de imágenes).

Configuración

{
  agents: {
    defaults: {
      pdfModel: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["openai/gpt-5-mini"],
      },
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
    },
  },
}

Consulta la Configuration Reference para ver los detalles completos de los campos.

Detalles de salida

La herramienta devuelve texto en content[0].text y metadatos estructurados en details.

Campos comunes en details:

• model: referencia del modelo resuelto (provider/model).
• native: true para modo de proveedor nativo, false para respaldo.
• attempts: intentos de respaldo que fallaron antes del éxito.

Campos de ruta:

• Entrada de un solo PDF: details.pdf.
• Entradas de múltiples PDFs: details.pdfs[] con entradas pdf.
• Metadatos de reescritura de ruta en sandbox (cuando aplique): rewrittenFrom.

Comportamiento de errores

• Falta entrada de PDF: lanza pdf required: provide a path or URL to a PDF document.
• Demasiados PDFs: devuelve un error estructurado en details.error = "too_many_pdfs".
• Esquema de referencia no soportado: devuelve details.error = "unsupported_pdf_reference".
• Modo nativo con pages: lanza el error pages is not supported with native PDF providers.

Ejemplos

PDF único:

{
  "pdf": "/tmp/report.pdf",
  "prompt": "Summarize this report in 5 bullets"
}

Múltiples PDFs:

{
  "pdfs": ["/tmp/q1.pdf", "/tmp/q2.pdf"],
  "prompt": "Compare risks and timeline changes across both documents"
}

Modelo de respaldo con filtro de páginas:

{
  "pdf": "https://example.com/report.pdf",
  "pages": "1-3,7",
  "model": "openai/gpt-5-mini",
  "prompt": "Extract only customer-impacting incidents"
}

Relacionado

• Tools Overview — todas las herramientas de agent disponibles.
• Configuration Reference — configuración de pdfMaxBytesMb y pdfMaxPages.

Próximos pasos

• Aprende a configurar tus propios modelos en la Configuration Reference.
• Explora cómo combinar esto con otras herramientas en la Tools Overview.

AI Setup Assistant