Analyze PDF Documents with OpenClaw: Setup Guide

Handling PDFs in your development workflow is usually a mess. You often end up writing custom scripts or fighting with layout issues just to get readable text into your model.

The pdf tool simplifies this by analyzing documents and returning clean text directly to your agent. It handles the heavy lifting of extraction and provider-specific formatting so you can focus on the actual analysis.

Availability

The tool only appears when OpenClaw finds a model configuration that can handle PDFs. It looks for these settings in order:

1. The agents.defaults.pdfModel setting.
2. A fallback to agents.defaults.imageModel.
3. A best-effort check of provider defaults based on your auth.
4. A final check for any available vision-capable models.

If no usable model is found, the pdf tool stays hidden from the agent.

Input reference

You have several options when sending data to the tool:

• pdf (string): A single path or URL.
• pdfs (string[]): An array of paths or URLs, up to 10 total.
• prompt (string): Your analysis instructions. It defaults to Analyze this PDF document.
• pages (string): A filter like 1-5 or 1,3,7-9.
• model (string): An optional override for the model (format: provider/model).
• maxBytesMb (number): A size limit per PDF.

The tool merges and removes duplicates from the pdf and pdfs fields. If you don’t provide any input, the tool returns an error. The pages field uses 1-based numbering and automatically sorts and clamps values to your max page limit. For the size limit, it uses agents.defaults.pdfMaxBytesMb or 10MB by default.

Supported PDF references

You can point the tool to files in a few different ways:

• Local file paths, including ~ expansion.
• file:// URLs.
• http:// and https:// URLs.

Keep in mind that other schemes like ftp:// are rejected. If you are running in sandbox mode, remote URLs are blocked. If you have a workspace-only file policy, the tool rejects any local paths outside your allowed roots.

Execution modes

Native provider mode

This mode kicks in for anthropic and google providers. The tool sends the raw PDF bytes directly to their APIs. Note that the pages filter does not work in native mode; you will get an error if you try to use it.

Extraction fallback mode

For all other providers, the tool uses a fallback flow:

1. It extracts text from your selected pages, up to the pdfMaxPages limit (default is 20).
2. If the text is shorter than 200 characters, it renders the pages as PNG images.
3. It sends the text or images along with your prompt to the model.

Page images use a pixel budget of 4,000,000. This mode requires pdfjs-dist and @napi-rs/canvas for rendering. If the model doesn’t support images and no text can be extracted, the tool fails.

Config

You can set your defaults in the configuration file:

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

Check the Configuration Reference for more details on these fields.

Output details

The tool provides text in content[0].text and extra metadata in the details object. You will find the resolved model name, a native boolean to show which mode was used, and any failed attempts. It also includes the original paths or URLs and any sandbox rewrite metadata.

Error behavior

The tool is specific about what went wrong:

• If you forget the PDF, it throws a “pdf required” error.
• If you exceed 10 PDFs, it returns a too_many_pdfs error code.
• If you use an invalid URL scheme, it returns unsupported_pdf_reference.
• If you try to use pages with a native provider, it throws a clear error explaining the limitation.

Examples

Here is how you can use the tool for a single file:

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

If you need to compare multiple documents:

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

You can also target specific pages with a fallback model:

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

Related

• Tools Overview — See all available agent tools.
• Configuration Reference — Details on pdfMaxBytesMb and pdfMaxPages.

Next steps

Ready to get started? You can configure your models in the agent settings or try out the AI Setup Assistant to help you build your first PDF-aware agent.