Herramienta de PDF

pdf analiza uno o más documentos PDF y devuelve texto.

Comportamiento resumido:

• Modo de proveedor nativo para proveedores de modelos Anthropic y Google.
• Modo de reserva de extracción para otros proveedores (extrae texto primero y, después, imágenes de página cuando es necesario).
• Admite entrada única (pdf) o múltiple (pdfs), máximo 10 PDF por llamada.

# Disponibilidad

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

1. agents.defaults.pdfModel
2. reserva en agents.defaults.imageModel
3. reserva en el modelo resuelto de sesión/predeterminado del agente
4. si los proveedores de PDF nativos están respaldados por autenticación, se prefieren antes que los candidatos de reserva genéricos de imagen

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

Notas de disponibilidad:

• La cadena de reserva tiene en cuenta la autenticación. Un provider/model configurado solo cuenta si OpenClaw realmente puede autenticar ese proveedor para el agente.
• Los proveedores de PDF nativos son actualmente Anthropic y Google.
• Si el proveedor de sesión/predeterminado resuelto ya tiene configurado un modelo de visión/PDF, la herramienta PDF lo reutiliza antes de recurrir a otros proveedores respaldados por autenticación.

# Referencia de entrada

pdfstring

Una ruta o URL de PDF.

pdfsstring[]

Varias rutas o URL de PDF, hasta 10 en total.

promptstring

Prompt de análisis.

pagesstring

Filtro de páginas como 1-5 o 1,3,7-9.

modelstring

Anulación opcional de modelo en formato provider/model.

maxBytesMbnumber

Límite de tamaño por PDF en MB. El valor predeterminado es agents.defaults.pdfMaxBytesMb o 10.

Notas de entrada:

• pdf y pdfs se fusionan y deduplican antes de la carga.
• Si no se proporciona ninguna entrada de PDF, la herramienta devuelve un error.
• pages se interpreta como números de página basados en 1, se deduplica, se ordena y se limita al máximo de páginas configurado.
• maxBytesMb usa como valor predeterminado agents.defaults.pdfMaxBytesMb o 10.

# Referencias PDF compatibles

• ruta de archivo local (incluida la expansión de ~)
• URL file://
• URL http:// y https://
• referencias entrantes gestionadas por OpenClaw, como media://inbound/<id>

Notas de referencia:

• Otros esquemas URI (por ejemplo, ftp://) se rechazan con unsupported_pdf_reference.
• En modo sandbox, las URL remotas http(s) se rechazan.
• Con la política de archivos solo de espacio de trabajo habilitada, las rutas de archivos locales fuera de las raíces permitidas se rechazan.
• Las referencias entrantes gestionadas y las rutas reproducidas bajo el almacén de medios entrantes de OpenClaw se permiten con la política de archivos solo de espacio de trabajo.

# Modos de ejecución

# Modo de proveedor nativo

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

Límites del modo nativo:

• pages no es compatible. Si se establece, la herramienta devuelve un error.
• La entrada de varios PDF es compatible; cada PDF se envía como un bloque de documento nativo / parte PDF en línea antes del prompt.

# Modo de reserva de extracción

El modo de reserva se usa para proveedores no nativos.

Flujo:

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

Detalles de reserva:

• 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 admite entrada de imagen y no hay texto extraíble, la herramienta devuelve un error.
• Si la extracción de texto se realiza correctamente pero la extracción de imágenes requeriría visión en un modelo de solo texto, OpenClaw descarta las imágenes renderizadas y continúa con el texto extraído.
• La reserva de extracción usa el Plugin document-extract incluido. El Plugin es propietario de pdfjs-dist; @napi-rs/canvas se usa solo cuando la reserva de renderizado de imágenes está disponible.

# Configuración

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

Consulta la Referencia de configuración para obtener todos los detalles de los campos.

# Detalles de salida

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

Campos comunes de details:

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

Campos de ruta:

• entrada de un solo PDF: details.pdf
• entradas de varios PDF: details.pdfs[] con entradas pdf
• metadatos de reescritura de ruta de sandbox (cuando corresponda): rewrittenFrom

# Comportamiento de errores

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

# Ejemplos

PDF único:

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

Varios PDF:

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

Modelo de reserva con filtro de páginas:

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

# Relacionado

• Resumen de herramientas - todas las herramientas de agente disponibles
• Referencia de configuración - configuración de pdfMaxBytesMb y pdfMaxPages