Herramienta de PDF

pdf analiza uno o más documentos PDF y devuelve texto. Usa la entrada nativa de documentos en los modelos de Anthropic y Google, y recurre a la extracción de texto e imágenes con todos los demás proveedores.

Disponibilidad

La herramienta solo se registra cuando OpenClaw puede resolver un modelo compatible con PDF para el agente. Orden de resolución:

1. agents.defaults.pdfModel (modelo principal y alternativas explícitos)
2. agents.defaults.imageModel (modelo principal y alternativas explícitos)
3. El modelo predeterminado o resuelto para la sesión del agente, si su proveedor admite la entrada nativa de PDF (Anthropic, Google) o ya tiene configurado un modelo de visión
4. Proveedores compatibles con imágenes o visión detectados automáticamente y con autenticación utilizable, dando prioridad a los proveedores con PDF nativo

La autenticación de cada candidato alternativo se comprueba antes de usarlo, por lo que un provider/model configurado solo cuenta si OpenClaw puede autenticar ese proveedor para el agente. Si no se resuelve ningún modelo utilizable, la herramienta pdf no se expone.

Referencia de entrada

Notas:

• pdf y pdfs se combinan y deduplican antes de la carga; se requiere al menos uno.
• pages se interpreta como números de página con base 1, se deduplica, se ordena y se limita a agents.defaults.pdfMaxPages (valor predeterminado: 20). Un intervalo que no coincida con ninguna página dentro de los límites genera un error antes de la llamada al modelo.

Referencias de PDF admitidas

• Ruta de archivo local (incluida la expansión de ~)
• URL file://
• URL http:// y https://
• Referencias de entrada administradas por OpenClaw, como media://inbound/<id>

Otros esquemas de URI (por ejemplo, ftp://) devuelven details.error = "unsupported_pdf_reference". Las URL remotas http(s) se rechazan cuando la herramienta se ejecuta en un entorno aislado. Con la política de archivos restringida al espacio de trabajo activada, se rechazan las rutas locales situadas fuera de las raíces permitidas; las referencias de entrada administradas y las rutas reproducidas dentro del almacén de contenido multimedia entrante de OpenClaw siguen estando permitidas.

Modos de ejecución

Modo nativo del proveedor

Se usa con los proveedores anthropic y google (los únicos proveedores que actualmente declaran compatibilidad nativa con documentos PDF). Los bytes sin procesar de cada PDF se envían directamente a la API del proveedor como una parte de documento nativo o PDF en línea.

Limitaciones:

• pages no se admite; si se establece, la herramienta genera pages is not supported with native PDF providers.
• password no se admite; si se establece, la herramienta genera password is not supported with native PDF providers. Usa un modelo no nativo para los PDF cifrados.

Modo alternativo de extracción

Se usa con todos los demás proveedores.

1. Extrae el texto de las páginas seleccionadas (hasta agents.defaults.pdfMaxPages, con un valor predeterminado de 20) mediante el Plugin document-extract incluido, que usa el paquete clawpdf (PDFium WebAssembly) para extraer texto e imágenes.
2. Si el texto extraído tiene menos de 200 caracteres, representa las mismas páginas como imágenes PNG. El presupuesto de representación es de 4,000,000 píxeles en total, compartido entre todas las páginas que necesitan imágenes (asignado proporcionalmente por cada página restante, no por página), por lo que las páginas que ya contienen suficiente texto omiten por completo la representación.
3. Envía al modelo seleccionado el texto extraído (y las imágenes representadas, si las hay) junto con la indicación.

Detalles:

• Los PDF cifrados se abren con el parámetro de nivel superior password.
• Si el modelo no admite entrada de imágenes y no hay texto extraíble, la herramienta genera un error.
• Si falla la representación de imágenes, OpenClaw descarta las imágenes y continúa con el texto extraído.
• Si el modelo de destino solo admite texto y la extracción produjo imágenes, OpenClaw descarta las imágenes y envía únicamente el texto.

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 habituales de details:

• model: referencia del modelo resuelto (provider/model)
• native: true para el modo nativo del proveedor, false para el modo alternativo
• attempts: intentos alternativos que fallaron antes de completarse correctamente

Campos de ruta:

• Entrada de un solo PDF: details.pdf
• Entradas de varios PDF: details.pdfs[] con elementos pdf
• Metadatos de reescritura de rutas del entorno aislado (cuando corresponda): rewrittenFrom

Comportamiento ante errores

Ejemplos

Un solo PDF:

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

PDF cifrado con extracción alternativa:

{  "pdf": "/tmp/locked.pdf",  "password": "example-password",  "model": "openai/gpt-5.4-mini",  "prompt": "Summarize this contract"}

Temas relacionados

• Descripción general de las herramientas - todas las herramientas disponibles para agentes
• Referencia de configuración - configuración de pdfMaxBytesMb y pdfMaxPages