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

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

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

Consulta Riferimento configurazione 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:

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

PDF multipli:

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

Modello di ripiego con filtro pagine:

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

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

Correlati

• Panoramica degli strumenti - tutti gli strumenti agente disponibili
• Riferimento configurazione - configurazione di pdfMaxBytesMb e pdfMaxPages