PDF-Tool

pdf analysiert ein oder mehrere PDF-Dokumente und gibt Text zurück.

Kurzverhalten:

• Nativer Provider-Modus für Anthropic- und Google-Model-Provider.
• Extraktions-Fallback-Modus für andere Provider (zuerst Text extrahieren, dann bei Bedarf Seitenbilder).
• Unterstützt einzelne (pdf) oder mehrere (pdfs) Eingaben, maximal 10 PDFs pro Aufruf.

Verfügbarkeit

Das Tool wird nur registriert, wenn OpenClaw eine PDF-fähige Modellkonfiguration für den Agent auflösen kann:

1. agents.defaults.pdfModel
2. Fallback auf agents.defaults.imageModel
3. Fallback auf Best-Effort-Provider-Defaults basierend auf verfügbarer Auth

Wenn kein verwendbares Modell aufgelöst werden kann, wird das pdf-Tool nicht exponiert.

Eingabe-Referenz

• pdf (string): ein PDF-Pfad oder URL
• pdfs (string[]): mehrere PDF-Pfade oder URLs, insgesamt bis zu 10
• prompt (string): Analyse-Prompt, Standard Analyze this PDF document.
• pages (string): Seitenfilter wie 1-5 oder 1,3,7-9
• model (string): optionaler Modell-Override (provider/model)
• maxBytesMb (number): Größenbegrenzung pro PDF in MB

Eingabe-Hinweise:

• pdf und pdfs werden vor dem Laden zusammengeführt und dedupliziert.
• Wenn keine PDF-Eingabe angegeben wird, gibt das Tool einen Fehler aus.
• pages wird als 1-basierte Seitennummern geparst, dedupliziert, sortiert und auf die konfigurierte maximale Seitenzahl begrenzt.
• maxBytesMb wird standardmäßig auf agents.defaults.pdfMaxBytesMb oder 10 gesetzt.

Unterstützte PDF-Referenzen

• lokaler Dateipfad (einschließlich ~-Expansion)
• file://-URL
• http://- und https://-URL

Referenz-Hinweise:

• Andere URI-Schemata (zum Beispiel ftp://) werden mit unsupported_pdf_reference abgelehnt.
• Im Sandbox-Modus werden Remote http(s)-URLs abgelehnt.
• Bei aktivierter Workspace-only-Dateirichtlinie werden lokale Dateipfade außerhalb erlaubter Wurzelverzeichnisse abgelehnt.

Ausführungsmodi

Nativer Provider-Modus

Der native Modus wird für die Provider anthropic und google verwendet. Das Tool sendet rohe PDF-Bytes direkt an die Provider-APIs.

Einschränkungen im nativen Modus:

• pages wird nicht unterstützt. Wenn gesetzt, gibt das Tool einen Fehler zurück.

Extraktions-Fallback-Modus

Der Fallback-Modus wird für nicht-native Provider verwendet.

Ablauf:

1. Text von ausgewählten Seiten extrahieren (bis zu agents.defaults.pdfMaxPages, Standard 20).
2. Wenn der extrahierte Text kürzer als 200 Zeichen ist, ausgewählte Seiten als PNG-Bilder rendern und einbinden.
3. Extrahierte Inhalte plus Prompt an das ausgewählte Modell senden.

Fallback-Details:

• Die Seitenbild-Extraktion verwendet ein Pixelbudget von 4.000.000.
• Wenn das Zielmodell keine Bildeingabe unterstützt und kein extrahierbarer Text vorhanden ist, gibt das Tool einen Fehler aus.
• Der Extraktions-Fallback erfordert pdfjs-dist (und @napi-rs/canvas für Bild-Rendering).

Konfiguration

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

Siehe Konfigurationsreferenz für vollständige Felddetails.

Ausgabedetails

Das Tool gibt Text in content[0].text und strukturierte Metadaten in details zurück.

Häufige details-Felder:

• model: aufgelöste Modellreferenz (provider/model)
• native: true für nativen Provider-Modus, false für Fallback
• attempts: Fallback-Versuche, die vor dem Erfolg fehlgeschlagen sind

Pfadfelder:

• einzelne PDF-Eingabe: details.pdf
• mehrere PDF-Eingaben: details.pdfs[] mit pdf-Einträgen
• Sandbox-Pfad-Rewrite-Metadaten (wenn zutreffend): rewrittenFrom

Fehlerverhalten

• Fehlende PDF-Eingabe: wirft pdf required: provide a path or URL to a PDF document
• Zu viele PDFs: gibt strukturierten Fehler in details.error = "too_many_pdfs" zurück
• Nicht unterstütztes Referenz-Schema: gibt details.error = "unsupported_pdf_reference" zurück
• Nativer Modus mit pages: wirft klaren pages is not supported with native PDF providers-Fehler

Beispiele

Einzelnes PDF:

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

Mehrere PDFs:

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

Seitengefiltertes Fallback-Modell:

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