Herramientas integradas

Herramienta PDF

pdf analiza uno o más documentos PDF y devuelve texto. Comportamiento rápido:

Modo de proveedor nativo para los proveedores de modelos Anthropic y Google.
Modo de respaldo por extracción para otros proveedores (extrae texto primero, luego imágenes de página cuando es necesario).
Soporta entrada única (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 compatible con PDF para el agente:

agents.defaults.pdfModel
respaldo a agents.defaults.imageModel
respaldo a valores predeterminados del proveedor de mejor esfuerzo según la autenticación disponible

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): indicación de análisis, predeterminada Analyze this PDF document.
pages (string): filtro de páginas como 1-5 o 1,3,7-9
model (string): anulación 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 se eliminan duplicados antes de cargar.
Si no se proporciona entrada de PDF, la herramienta genera un error.
pages se analiza 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 tiene como valor predeterminado agents.defaults.pdfMaxBytesMb o 10.

Referencias PDF admitidas

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

Notas de referencia:

Otros esquemas URI (por ejemplo ftp://) son rechazados con unsupported_pdf_reference.
En modo sandbox, las URLs remotas http(s) son rechazadas.
Con la política de solo archivos de espacio de trabajo habilitada, las rutas de archivo local fuera de las raíces permitidas son rechazadas.

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 brutos del PDF directamente a las APIs del proveedor. Límites del modo nativo:

pages no es compatible. Si se establece, la herramienta devuelve un error.

Modo de respaldo por extracción

El modo de respaldo se usa para proveedores no nativos. Flujo:

Extrae texto de las páginas seleccionadas (hasta agents.defaults.pdfMaxPages, predeterminado 20).
Si la longitud del texto extraído es inferior a 200 caracteres, renderiza las páginas seleccionadas a imágenes PNG y las incluye.
Envía el contenido extraído más la indicación 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 objetivo no admite entrada de imagen y no hay texto extraíble, la herramienta genera un error.
El respaldo por 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 Referencia de Configuración para detalles completos 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 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 PDF único: details.pdf
entradas de PDF múltiples: details.pdfs[] con entradas pdf
metadatos de reescritura de ruta sandbox (cuando aplica): rewrittenFrom

Comportamiento de error

Falta entrada de PDF: 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

PDF único:

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

PDFs múltiples:

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

Diferencias Modo Elevado