Strumento PDF

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

​

Disponibilità

1. agents.defaults.pdfModel
2. fallback a agents.defaults.imageModel
3. fallback al modello sessione/predefinito risolto dell’agente
4. se i provider PDF nativi sono supportati da autenticazione, preferirli prima dei candidati fallback generici per immagini

• La catena di fallback è 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 sessione/predefinito risolto ha già un modello vision/PDF configurato, lo strumento PDF lo riutilizza prima di ricorrere ad altri provider supportati da autenticazione.

​

Riferimento 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 a base 1, deduplicato, ordinato e limitato al massimo di pagine configurato.
• maxBytesMb usa come valore predefinito agents.defaults.pdfMaxBytesMb o 10.

​

Riferimenti PDF supportati

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

• 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 solo workspace abilitata, i percorsi file locali fuori dalle radici consentite vengono rifiutati.
• I riferimenti inbound gestiti e i percorsi riprodotti nell’archivio media inbound di OpenClaw sono consentiti con la policy file solo workspace.

​

Modalità di esecuzione

​

Modalità provider nativa

• pages non è supportato. Se impostato, lo strumento restituisce un errore.
• L’input multi-PDF è supportato; ogni PDF viene inviato come blocco documento nativo / parte PDF inline prima del prompt.

​

Modalità fallback di estrazione

1. Estrae 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 come immagini PNG e le include.
3. Invia il contenuto estratto più il prompt al modello selezionato.

• L’estrazione delle immagini delle pagine usa un budget pixel di 4,000,000.
• 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 vision su un modello solo testo, OpenClaw elimina le immagini renderizzate e prosegue con il testo estratto.
• Il fallback di estrazione usa il Plugin document-extract incluso. Il Plugin possiede pdfjs-dist; @napi-rs/canvas viene usato solo quando è disponibile il fallback di rendering immagini.

​

Configurazione

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

​

Dettagli output

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

• input PDF singolo: details.pdf
• input PDF multiplo: details.pdfs[] con voci pdf
• metadati di riscrittura 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 errore strutturato in details.error = "too_many_pdfs"
• Schema 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": "/tmp/report.pdf",
  "prompt": "Summarize this report in 5 bullets"
}

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

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

​

Correlati

• Panoramica strumenti - tutti gli strumenti disponibili dell’agente
• Riferimento configurazione - configurazione pdfMaxBytesMb e pdfMaxPages