Strumento PDF

pdf analizza uno o più documenti PDF e restituisce del testo. Usa l'input nativo dei documenti sui modelli Anthropic e Google e, per tutti gli altri provider, ricorre all'estrazione di testo e immagini.

Disponibilità

Lo strumento viene registrato solo quando OpenClaw riesce a individuare un modello compatibile con i PDF per l'agente. Ordine di risoluzione:

1. agents.defaults.pdfModel (modello primario/fallback espliciti)
2. agents.defaults.imageModel (modello primario/fallback espliciti)
3. Il modello risolto per la sessione/predefinito dell'agente, se il relativo provider supporta l'input PDF nativo (Anthropic, Google) o dispone già di un modello di visione configurato
4. Provider compatibili con immagini/visione rilevati automaticamente e dotati di autenticazione utilizzabile, dando priorità ai provider con PDF nativi

L'autenticazione di ogni candidato di fallback viene verificata prima dell'uso, quindi un provider/model configurato viene considerato solo se OpenClaw può autenticare tale provider per l'agente. Se non viene individuato alcun modello utilizzabile, lo strumento pdf non viene esposto.

Riferimento degli input

Note:

• pdf e pdfs vengono uniti e deduplicati prima del caricamento; è necessario specificarne almeno uno.
• pages viene interpretato come numeri di pagina con indice iniziale 1, deduplicati, ordinati e limitati a agents.defaults.pdfMaxPages (valore predefinito 20). Un intervallo che non corrisponde ad alcuna pagina entro i limiti genera un errore prima della chiamata al modello.

Riferimenti PDF supportati

• Percorso di un file locale (inclusa l'espansione di ~)
• URL file://
• URL http:// e https://
• Riferimenti in ingresso gestiti da OpenClaw, come media://inbound/<id>

Gli altri schemi URI, ad esempio ftp://, restituiscono details.error = "unsupported_pdf_reference". Gli URL remoti http(s) vengono rifiutati quando lo strumento viene eseguito in sandbox. Quando è abilitata la politica che limita i file all'area di lavoro, i percorsi locali esterni alle radici consentite vengono rifiutati; sono comunque permessi i riferimenti in ingresso gestiti e i percorsi riprodotti nell'archivio dei contenuti multimediali in ingresso di OpenClaw.

Modalità di esecuzione

Modalità nativa del provider

Utilizzata per i provider anthropic e google, gli unici che attualmente dichiarano il supporto nativo dei documenti PDF. I byte PDF non elaborati vengono inviati direttamente all'API del provider come documento nativo/parte PDF incorporata per ciascun file.

Limiti:

• pages non è supportato; se impostato, lo strumento genera pages is not supported with native PDF providers.
• password non è supportato; se impostato, lo strumento genera password is not supported with native PDF providers. Per i PDF crittografati, usa un modello non nativo.

Modalità di fallback con estrazione

Utilizzata per tutti gli altri provider.

1. Estrae il testo dalle pagine selezionate (fino a agents.defaults.pdfMaxPages, valore predefinito 20) tramite il plugin document-extract incluso, che usa il pacchetto clawpdf (PDFium WebAssembly) per estrarre testo e immagini.
2. Se il testo estratto contiene meno di 200 caratteri, converte le stesse pagine in immagini PNG. Il budget di rendering è di 4,000,000 pixel complessivi, condivisi tra tutte le pagine che richiedono immagini (assegnati proporzionalmente per ogni pagina rimanente, non per singola pagina); le pagine che contengono già una quantità sufficiente di testo non vengono quindi convertite.
3. Invia al modello selezionato il testo estratto, le eventuali immagini convertite e il prompt.

Dettagli:

• I PDF crittografati vengono aperti con il parametro password di primo livello.
• Se il modello non supporta l'input di immagini e non è presente testo estraibile, lo strumento genera un errore.
• Se il rendering delle immagini non riesce, OpenClaw elimina le immagini e prosegue con il testo estratto.
• Se il modello di destinazione supporta solo il testo e l'estrazione ha prodotto immagini, OpenClaw elimina le immagini e invia esclusivamente il testo.

Configurazione

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

Consulta il Riferimento della configurazione per i dettagli completi sui campi.

Dettagli dell'output

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

Campi details comuni:

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

Campi dei percorsi:

• Input di un singolo PDF: details.pdf
• Input di più PDF: details.pdfs[] con voci pdf
• Metadati di riscrittura del percorso della sandbox (quando applicabile): rewrittenFrom

Comportamento in caso di errore

Esempi

PDF singolo:

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

Più PDF:

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

Modello di fallback con filtro delle pagine:

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

PDF crittografato con fallback di 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 disponibili per gli agenti
• Riferimento della configurazione - configurazione di pdfMaxBytesMb e pdfMaxPages