> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 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 Agenten auflösen kann:
1. `agents.defaults.pdfModel`
2. Fallback auf `agents.defaults.imageModel`
3. Fallback auf das aufgelöste Sitzungs-/Standardmodell des Agenten
4. Wenn native PDF-Provider authentifizierungsbasiert verfügbar sind, werden sie generischen Kandidaten für den Bild-Fallback vorgezogen
Wenn kein verwendbares Modell aufgelöst werden kann, wird das Tool `pdf` nicht bereitgestellt.
Hinweise zur Verfügbarkeit:
* Die Fallback-Kette berücksichtigt Authentifizierung. Ein konfiguriertes `provider/model` zählt nur, wenn
OpenClaw diesen Provider für den Agenten tatsächlich authentifizieren kann.
* Native PDF-Provider sind derzeit **Anthropic** und **Google**.
* Wenn der aufgelöste Sitzungs-/Standard-Provider bereits ein konfiguriertes Vision-/PDF-
Modell hat, verwendet das PDF-Tool dieses erneut, bevor es auf andere authentifizierungsbasierte
Provider zurückfällt.
## Eingabereferenz
Ein PDF-Pfad oder eine URL.
Mehrere PDF-Pfade oder URLs, insgesamt bis zu 10.
Analyse-Prompt.
Seitenfilter wie `1-5` oder `1,3,7-9`.
Passwort für verschlüsselte PDFs im Extraktions-Fallback-Modus.
Optionale Modellüberschreibung in der Form `provider/model`.
Größenlimit pro PDF in MB. Standardwert ist `agents.defaults.pdfMaxBytesMb` oder `10`.
Eingabehinweise:
* `pdf` und `pdfs` werden vor dem Laden zusammengeführt und dedupliziert.
* Wenn keine PDF-Eingabe angegeben ist, gibt das Tool einen Fehler aus.
* `pages` wird als 1-basierte Seitenzahlen geparst, dedupliziert, sortiert und auf die konfigurierte maximale Seitenanzahl begrenzt.
* `password` gilt für jedes PDF in der Anfrage und wird nur vom Extraktions-Fallback-Modus verwendet.
* `maxBytesMb` verwendet standardmäßig `agents.defaults.pdfMaxBytesMb` oder `10`.
## Unterstützte PDF-Referenzen
* lokaler Dateipfad (einschließlich `~`-Erweiterung)
* `file://`-URL
* `http://`- und `https://`-URL
* von OpenClaw verwaltete eingehende Refs wie `media://inbound/`
Hinweise zu Referenzen:
* 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 Wurzeln abgelehnt.
* Verwaltete eingehende Refs und wiedergegebene Pfade unter OpenClaws Speicher für eingehende Medien sind mit Workspace-only-Dateirichtlinie erlaubt.
## Ausführungsmodi
### Nativer Provider-Modus
Der native Modus wird für Provider `anthropic` und `google` verwendet.
Das Tool sendet rohe PDF-Bytes direkt an Provider-APIs.
Einschränkungen im nativen Modus:
* `pages` wird nicht unterstützt. Wenn gesetzt, gibt das Tool einen Fehler zurück.
* `password` wird nicht unterstützt. Verwenden Sie ein nicht-natives Modell, um verschlüsselte PDFs zu analysieren.
* Mehrere PDF-Eingaben werden unterstützt; jedes PDF wird vor dem Prompt als nativer Dokumentblock /
Inline-PDF-Teil gesendet.
### Extraktions-Fallback-Modus
Der Fallback-Modus wird für nicht-native Provider verwendet.
Ablauf:
1. Text aus ausgewählten Seiten extrahieren (bis zu `agents.defaults.pdfMaxPages`, Standardwert `20`).
2. Wenn die Länge des extrahierten Texts unter `200` Zeichen liegt, ausgewählte Seiten als PNG-Bilder rendern und einschließen.
3. Extrahierten Inhalt plus Prompt an das ausgewählte Modell senden.
Fallback-Details:
* Die Extraktion von Seitenbildern verwendet ein Pixelbudget von `4,000,000`.
* Verschlüsselte PDFs können mit dem Top-Level-Parameter `password` geöffnet werden.
* Wenn das Zielmodell keine Bildeingabe unterstützt und kein extrahierbarer Text vorhanden ist, gibt das Tool einen Fehler aus.
* Wenn die Textextraktion erfolgreich ist, die Bildextraktion auf einem
reinen Textmodell jedoch Vision erfordern würde, verwirft OpenClaw die gerenderten Bilder und fährt mit dem
extrahierten Text fort.
* Der Extraktions-Fallback verwendet das gebündelte Plugin `document-extract`. Das Plugin besitzt
`clawpdf`, das Textextraktion und Bildrendering über PDFium
WebAssembly bereitstellt.
## Konfiguration
```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
agents: {
defaults: {
pdfModel: {
primary: "anthropic/claude-opus-4-6",
fallbacks: ["openai/gpt-5.4-mini"],
},
pdfMaxBytesMb: 10,
pdfMaxPages: 20,
},
},
}
```
Weitere Felddetails finden Sie in der [Konfigurationsreferenz](/de/gateway/configuration-reference).
## 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
* Metadaten zur Sandbox-Pfadumschreibung (falls 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 Referenzschema: gibt `details.error = "unsupported_pdf_reference"` zurück
* Nativer Modus mit `pages`: wirft eindeutigen Fehler `pages is not supported with native PDF providers`
## Beispiele
Einzelnes PDF:
```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
"pdf": "/tmp/report.pdf",
"prompt": "Summarize this report in 5 bullets"
}
```
Mehrere PDFs:
```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
"pdfs": ["/tmp/q1.pdf", "/tmp/q2.pdf"],
"prompt": "Compare risks and timeline changes across both documents"
}
```
Fallback-Modell mit Seitenfilter:
```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
"pdf": "https://example.com/report.pdf",
"pages": "1-3,7",
"model": "openai/gpt-5.4-mini",
"prompt": "Extract only customer-impacting incidents"
}
```
Verschlüsseltes PDF mit Extraktions-Fallback:
```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
"pdf": "/tmp/locked.pdf",
"password": "example-password",
"model": "openai/gpt-5.4-mini",
"prompt": "Summarize this contract"
}
```
## Verwandt
* [Tools-Übersicht](/de/tools) - alle verfügbaren Agent-Tools
* [Konfigurationsreferenz](/de/gateway/config-agents#agent-defaults) - Konfiguration von pdfMaxBytesMb und pdfMaxPages