> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Strumento PDF

`pdf` analizza uno o più documenti PDF e restituisce testo.

Comportamento rapido:

* Modalità provider nativa per i provider di modelli Anthropic e Google.
* Modalità di ripiego con estrazione per altri provider (prima estrae il testo, poi le immagini delle pagine quando necessario).
* Supporta input singolo (`pdf`) o multiplo (`pdfs`), massimo 10 PDF per chiamata.

## Disponibilità

Lo strumento viene registrato solo quando OpenClaw può risolvere una configurazione di modello compatibile con PDF per l’agente:

1. `agents.defaults.pdfModel`
2. ripiego su `agents.defaults.imageModel`
3. ripiego sul modello di sessione/predefinito risolto dell’agente
4. se i provider PDF nativi sono supportati da autenticazione, preferiscili rispetto ai candidati generici di ripiego per immagini

Se non è possibile risolvere alcun modello utilizzabile, lo strumento `pdf` non viene esposto.

Note sulla disponibilità:

* La catena di ripiego è consapevole dell’autenticazione. Un `provider/model` configurato conta solo se
  OpenClaw può effettivamente autenticare quel provider per l’agente.
* I provider PDF nativi sono attualmente **Anthropic** e **Google**.
* Se il provider di sessione/predefinito risolto ha già un modello di visione/PDF
  configurato, lo strumento PDF lo riutilizza prima di ricorrere ad altri
  provider supportati da autenticazione.

## Riferimento input

<ParamField path="pdf" type="string">
  Un percorso o URL di PDF.
</ParamField>

<ParamField path="pdfs" type="string[]">
  Più percorsi o URL di PDF, fino a 10 in totale.
</ParamField>

<ParamField path="prompt" type="string" default="Analyze this PDF document.">
  Prompt di analisi.
</ParamField>

<ParamField path="pages" type="string">
  Filtro delle pagine come `1-5` o `1,3,7-9`.
</ParamField>

<ParamField path="password" type="string">
  Password per PDF cifrati in modalità di ripiego con estrazione.
</ParamField>

<ParamField path="model" type="string">
  Override opzionale del modello nel formato `provider/model`.
</ParamField>

<ParamField path="maxBytesMb" type="number">
  Limite di dimensione per PDF in MB. Il valore predefinito è `agents.defaults.pdfMaxBytesMb` o `10`.
</ParamField>

Note sull’input:

* `pdf` e `pdfs` vengono uniti e deduplicati prima del caricamento.
* Se non viene fornito alcun input PDF, lo strumento restituisce un errore.
* `pages` viene interpretato come numeri di pagina con base 1, deduplicato, ordinato e limitato al massimo di pagine configurato.
* `password` si applica a ogni PDF nella richiesta ed è usato solo dalla modalità di ripiego con estrazione.
* Il valore predefinito di `maxBytesMb` è `agents.defaults.pdfMaxBytesMb` o `10`.

## Riferimenti PDF supportati

* percorso di file locale (inclusa l’espansione di `~`)
* URL `file://`
* URL `http://` e `https://`
* riferimenti in ingresso gestiti da OpenClaw, come `media://inbound/<id>`

Note sui riferimenti:

* Altri schemi URI (per esempio `ftp://`) vengono rifiutati con `unsupported_pdf_reference`.
* In modalità sandbox, gli URL remoti `http(s)` vengono rifiutati.
* Con la policy file limitata al workspace abilitata, i percorsi di file locali esterni alle radici consentite vengono rifiutati.
* I riferimenti in ingresso gestiti e i percorsi riprodotti nell’archivio multimediale in ingresso di OpenClaw sono consentiti con la policy file limitata al workspace.

## Modalità di esecuzione

### Modalità provider nativa

La modalità nativa viene usata per i provider `anthropic` e `google`.
Lo strumento invia i byte PDF grezzi direttamente alle API dei provider.

Limiti della modalità nativa:

* `pages` non è supportato. Se impostato, lo strumento restituisce un errore.
* `password` non è supportato. Usa un modello non nativo per analizzare PDF cifrati.
* L’input multi-PDF è supportato; ogni PDF viene inviato come blocco documento nativo /
  parte PDF inline prima del prompt.

### Modalità di ripiego con estrazione

La modalità di ripiego viene usata per provider non nativi.

Flusso:

1. Estrai il testo dalle pagine selezionate (fino a `agents.defaults.pdfMaxPages`, valore predefinito `20`).
2. Se la lunghezza del testo estratto è inferiore a `200` caratteri, renderizza le pagine selezionate in immagini PNG e includile.
3. Invia il contenuto estratto più il prompt al modello selezionato.

Dettagli del ripiego:

* L’estrazione delle immagini delle pagine usa un budget di pixel di `4,000,000`.
* I PDF cifrati possono essere aperti con il parametro di primo livello `password`.
* Se il modello di destinazione non supporta input immagine e non c’è testo estraibile, lo strumento restituisce un errore.
* Se l’estrazione del testo riesce ma l’estrazione delle immagini richiederebbe la visione su un
  modello solo testo, OpenClaw scarta le immagini renderizzate e continua con il
  testo estratto.
* Il ripiego con estrazione usa il Plugin `document-extract` incluso. Il Plugin possiede
  `clawpdf`, che fornisce estrazione del testo e rendering delle immagini tramite PDFium
  WebAssembly.

## Configurazione

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: {
      pdfModel: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["openai/gpt-5.4-mini"],
      },
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
    },
  },
}
```

Consulta [Riferimento configurazione](/it/gateway/configuration-reference) per i dettagli completi dei campi.

## Dettagli output

Lo strumento restituisce testo in `content[0].text` e metadati strutturati in `details`.

Campi `details` comuni:

* `model`: riferimento del modello risolto (`provider/model`)
* `native`: `true` per la modalità provider nativa, `false` per il ripiego
* `attempts`: tentativi di ripiego non riusciti prima del successo

Campi percorso:

* input PDF singolo: `details.pdf`
* input PDF multipli: `details.pdfs[]` con voci `pdf`
* metadati di riscrittura del percorso sandbox (quando applicabile): `rewrittenFrom`

## Comportamento degli errori

* Input PDF mancante: genera `pdf required: provide a path or URL to a PDF document`
* Troppi PDF: restituisce un errore strutturato in `details.error = "too_many_pdfs"`
* Schema di riferimento non supportato: restituisce `details.error = "unsupported_pdf_reference"`
* Modalità nativa con `pages`: genera un errore chiaro `pages is not supported with native PDF providers`

## Esempi

PDF singolo:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "pdf": "/tmp/report.pdf",
  "prompt": "Summarize this report in 5 bullets"
}
```

PDF multipli:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "pdfs": ["/tmp/q1.pdf", "/tmp/q2.pdf"],
  "prompt": "Compare risks and timeline changes across both documents"
}
```

Modello di ripiego con filtro pagine:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "pdf": "https://example.com/report.pdf",
  "pages": "1-3,7",
  "model": "openai/gpt-5.4-mini",
  "prompt": "Extract only customer-impacting incidents"
}
```

PDF cifrato con ripiego tramite estrazione:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "pdf": "/tmp/locked.pdf",
  "password": "example-password",
  "model": "openai/gpt-5.4-mini",
  "prompt": "Summarize this contract"
}
```

## Correlati

* [Panoramica degli strumenti](/it/tools) - tutti gli strumenti agente disponibili
* [Riferimento configurazione](/it/gateway/config-agents#agent-defaults) - configurazione di pdfMaxBytesMb e pdfMaxPages