Herramienta PDF

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

Comportamiento rápido:

Modo nativo de proveedor para proveedores de modelos Anthropic y Google.
Modo de fallback por extracción para otros proveedores (extrae texto primero, luego imágenes de páginas cuando es necesario).
Admite entrada simple (pdf) o múltiple (pdfs), máximo 10 PDFs por llamada.

Disponibilidad

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

agents.defaults.pdfModel
fallback a agents.defaults.imageModel
fallback a valores por defecto del proveedor basados en la autenticación disponible (best effort)

Si no se puede resolver un modelo utilizable, la herramienta pdf no se expone.

Referencia de entrada

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

Notas de entrada:

pdf y pdfs se fusionan y deduplican antes de cargar.
Si no se proporciona entrada de PDF, la herramienta da error.
pages se parsea como números de página basados en 1, deduplicados, ordenados y limitados al máximo configurado de páginas.
maxBytesMb tiene por defecto agents.defaults.pdfMaxBytesMb o 10.

Referencias de PDF admitidas

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

Notas de referencias:

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 workspace-only activada, las rutas de archivo locales fuera de las raíces permitidas se rechazan.

Modos de ejecución

Modo nativo de proveedor

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

Límites del modo nativo:

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

Modo de fallback por extracción

El modo de fallback se usa para proveedores no nativos.

Flujo:

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

Detalles del fallback:

La extracción de imágenes de página usa un presupuesto de píxeles de 4,000,000.
Si el modelo destino no admite entrada de imágenes y no hay texto extraíble, la herramienta da error.
El fallback de extracción requiere pdfjs-dist (y @napi-rs/canvas para 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 Referencia de configuración para los detalles completos de los campos.

Detalles de la salida

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

Campos comunes de details:

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

Campos de ruta:

entrada de un solo PDF: details.pdf
entrada de múltiples PDFs: details.pdfs[] con entradas pdf
metadatos de reescritura de ruta del sandbox (cuando aplica): rewrittenFrom

Comportamiento en errores

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

Ejemplos

Un solo PDF:

{
  "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 fallback 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"
}