PDF-Werkzeug

pdf analysiert ein oder mehrere PDF-Dokumente und gibt Text zurück. Das Tool verwendet die native Dokumenteingabe bei Modellen von Anthropic und Google und greift bei allen anderen Providern auf die Text-/Bildextraktion zurück.

Verfügbarkeit

Das Tool wird nur registriert, wenn OpenClaw ein PDF-fähiges Modell für den Agenten ermitteln kann. Reihenfolge der Ermittlung:

1. agents.defaults.pdfModel (explizites primäres Modell/Fallbacks)
2. agents.defaults.imageModel (explizites primäres Modell/Fallbacks)
3. Das ermittelte Sitzungs-/Standardmodell des Agenten, sofern dessen Provider die native PDF-Eingabe unterstützt (Anthropic, Google) oder bereits über ein konfiguriertes Vision-Modell verfügt
4. Automatisch erkannte bild-/vision-fähige Provider mit verwendbarer Authentifizierung, wobei Provider mit nativer PDF-Unterstützung bevorzugt werden

Die Authentifizierung jedes Fallback-Kandidaten wird vor der Verwendung geprüft. Ein konfiguriertes provider/model zählt daher nur, wenn OpenClaw den Provider für den Agenten authentifizieren kann. Wenn kein verwendbares Modell ermittelt wird, wird das Tool pdf nicht bereitgestellt.

Eingabereferenz

Hinweise:

• pdf und pdfs werden vor dem Laden zusammengeführt und dedupliziert; mindestens eine Angabe ist erforderlich.
• pages wird als 1-basierte Seitennummern interpretiert, dedupliziert, sortiert und auf agents.defaults.pdfMaxPages (Standardwert 20) begrenzt. Ein Bereich, der keine innerhalb der Grenzen liegenden Seiten enthält, führt vor dem Modellaufruf zu einem Fehler.

Unterstützte PDF-Referenzen

• Lokaler Dateipfad (einschließlich ~-Erweiterung)
• file://-URL
• http://- und https://-URL
• Von OpenClaw verwaltete eingehende Referenzen wie media://inbound/<id>

Andere URI-Schemata (zum Beispiel ftp://) geben details.error = "unsupported_pdf_reference" zurück. Entfernte http(s)-URLs werden abgelehnt, wenn das Tool in einer Sandbox ausgeführt wird. Bei aktivierter Dateirichtlinie, die den Zugriff auf den Workspace beschränkt, werden lokale Pfade außerhalb der zulässigen Wurzeln abgelehnt; verwaltete eingehende Referenzen und erneut wiedergegebene Pfade im Speicher für eingehende Medien von OpenClaw bleiben zulässig.

Ausführungsmodi

Nativer Provider-Modus

Wird für die Provider anthropic und google verwendet (die einzigen Provider, die derzeit native Unterstützung für PDF-Dokumente deklarieren). Die rohen PDF-Bytes werden pro Datei direkt als nativer Dokument-/Inline-PDF-Teil an die Provider-API gesendet.

Beschränkungen:

• pages wird nicht unterstützt; falls festgelegt, löst das Tool pages is not supported with native PDF providers aus.
• password wird nicht unterstützt; falls festgelegt, löst das Tool password is not supported with native PDF providers aus. Verwenden Sie für verschlüsselte PDFs ein nicht natives Modell.

Extraktions-Fallback-Modus

Wird für alle anderen Provider verwendet.

1. Extrahiert über das gebündelte Plugin document-extract Text aus den ausgewählten Seiten (bis zu agents.defaults.pdfMaxPages, Standardwert 20). Das Plugin verwendet das Paket clawpdf (PDFium WebAssembly) zur Text- und Bildextraktion.
2. Wenn der extrahierte Text kürzer als 200 Zeichen ist, werden dieselben Seiten als PNG-Bilder gerendert. Das Renderbudget beträgt insgesamt 4,000,000 Pixel und wird auf alle Seiten verteilt, für die Bilder erforderlich sind (proportional pro verbleibender Seite, nicht pro Seite). Textseiten, die bereits genügend Text enthalten, überspringen das Rendering daher vollständig.
3. Sendet den extrahierten Text (und alle gerenderten Bilder) zusammen mit dem Prompt an das ausgewählte Modell.

Details:

• Verschlüsselte PDFs werden mit dem übergeordneten Parameter password geöffnet.
• Wenn das Modell keine Bildeingabe unterstützt und kein Text extrahiert werden kann, gibt das Tool einen Fehler zurück.
• Wenn das Rendern der Bilder fehlschlägt, verwirft OpenClaw die Bilder und fährt mit dem extrahierten Text fort.
• Wenn das Zielmodell ausschließlich Text unterstützt und die Extraktion Bilder erzeugt hat, verwirft OpenClaw die Bilder und sendet nur den Text.

Konfiguration

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

Vollständige Details zu den Feldern finden Sie in der Konfigurationsreferenz.

Ausgabedetails

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

Gängige details-Felder:

• model: ermittelte Modellreferenz (provider/model)
• native: true für den nativen Provider-Modus, false für den 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
• Metadaten zur Umschreibung von Sandbox-Pfaden (falls zutreffend): rewrittenFrom

Fehlerverhalten

Beispiele

Einzelnes PDF:

{  "pdf": "/tmp/report.pdf",  "prompt": "Fassen Sie diesen Bericht in 5 Stichpunkten zusammen"}

Mehrere PDFs:

{  "pdfs": ["/tmp/q1.pdf", "/tmp/q2.pdf"],  "prompt": "Vergleichen Sie Risiken und Änderungen des Zeitplans in beiden Dokumenten"}

Fallback-Modell mit Seitenfilter:

{  "pdf": "https://example.com/report.pdf",  "pages": "1-3,7",  "model": "openai/gpt-5.4-mini",  "prompt": "Extrahieren Sie nur Vorfälle mit Auswirkungen auf Kunden"}

Verschlüsseltes PDF mit Extraktions-Fallback:

{  "pdf": "/tmp/locked.pdf",  "password": "example-password",  "model": "openai/gpt-5.4-mini",  "prompt": "Fassen Sie diesen Vertrag zusammen"}

Verwandte Themen

• Tool-Übersicht – alle verfügbaren Agenten-Tools
• Konfigurationsreferenz – Konfiguration von pdfMaxBytesMb und pdfMaxPages