The OpenClaw PDF tool

The PDF tool analyses one or more PDF documents and returns text. On Anthropic and Google models it uses native document input, sending the raw bytes to the provider as a document part; on every other provider it falls back to text and image extraction. The part people miss is that the tool only exists when a PDF-capable model can be resolved and authenticated for the agent. Here is that resolution order, the inputs, the two modes and what each forbids, the config, and the errors.

When the tool exists

• Resolution order: an explicit PDF model with primary and fallbacks, then an explicit image model, then the agent’s resolved session or default model if its provider supports native PDF input or already has a configured vision model, then auto-detected image-capable providers with usable auth, native-PDF providers first.
• Every fallback candidate is auth-checked before use, so a configured provider and model only counts if OpenClaw can authenticate that provider for the agent.
• Inputs: one PDF path or URL, or up to ten in a list, merged and deduplicated; an analysis prompt with a default; a page filter such as a range or a comma list, parsed as one-based pages, deduplicated, sorted and clamped to the page cap of twenty; a password for encrypted files; an optional model override; and a per-file size cap defaulting to ten megabytes.
• References: a local path with tilde expansion, a file URL, an HTTP or HTTPS URL, or an OpenClaw-managed inbound media reference; other schemes return an unsupported-reference error, remote URLs are rejected when the tool runs sandboxed, and a workspace-only file policy rejects local paths outside the allowed roots while still allowing managed inbound refs.

If no usable model resolves, the pdf tool is not exposed.

The two modes

Native mode is used for the two providers that declare native PDF document support: the raw bytes go straight to the provider API as a native document part per file, and two parameters throw, the page filter and the password, so an encrypted PDF needs a non-native model. Extraction mode is used for everyone else: the bundled document-extract plugin, built on a PDFium WebAssembly package, extracts text from the selected pages up to the page cap; if the extracted text is shorter than two hundred characters, the same pages are rendered to PNG within a total budget of four million pixels shared proportionally across the pages that need images, so pages with enough text skip rendering; then the text, any images and the prompt go to the selected model. Extraction runs in a reusable worker so it never blocks the Gateway, cancelling the run stops it, a model without image input and no extractable text is an error, a failed render drops the images and continues, and a text-only model gets text only.

Config, output, errors

• Three keys under the agent defaults: the PDF model with primary and fallbacks, which falls back to the image model and then the session model; the per-file size cap, ten by default; and the page cap, twenty by default.
• The analysis comes back both as the content text and in the details, so Code Mode and Tool Search read the same result; details also carry the resolved model, a native flag, the fallback attempts that failed before success, the path or paths, and any sandbox path rewrite.
• Errors: no input throws with a message asking for a path or URL; more than ten PDFs, or an unsupported reference scheme, come back as error codes in the details; the page filter or the password with a native provider throws the matching not-supported message.

OpenClaw with Claude and OpenClaw and Gemini are the two provider setups where the native path applies.

Choosing the model for documents

The practical advice falls out of the modes: for scanned or encrypted documents, or when you need a page filter, point the PDF model at a provider that takes the extraction path and has image input; for clean text documents on Claude or Gemini, the native path is one call with no extraction step. OpenClaw models and providers covers the provider and model choice the resolution order walks, and OpenClaw sandboxing explained explains why a sandboxed run cannot fetch a remote URL.

On Diali

On Diali the PDF tool follows the model you chose: with Claude or Gemini it reads the document natively, with anything else the extraction path runs inside the instance. Hosted OpenClaw on Diali is the assistant.

• No PDF-capable model, no tool.
• Native on Claude and Gemini; extraction, then images, elsewhere.
• Pages and passwords are extraction-only.